/ Hex Artifact Content
Login

Artifact 69c7d92c615945a7053cb899c6ae6a6a0fc36cca:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b  return SQLITE_OK
2ad0: 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69   if.** the [sqli
2ae0: 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20 73  te3] object is s
2af0: 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65 73 74  uccessfully dest
2b00: 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20 61 73  royed and all as
2b10: 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65 73 6f  sociated.** reso
2b20: 75 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f  urces are deallo
2b30: 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  cated..**.** ^If
2b40: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2b50: 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73 73 6f  nnection is asso
2b60: 63 69 61 74 65 64 20 77 69 74 68 20 75 6e 66 69  ciated with unfi
2b70: 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72 65 64  nalized prepared
2b80: 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  .** statements o
2b90: 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c  r unfinished sql
2ba0: 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62 6a 65  ite3_backup obje
2bb0: 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74 65 33  cts then sqlite3
2bc0: 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69 6c 6c  _close().** will
2bd0: 20 6c 65 61 76 65 20 74 68 65 20 64 61 74 61 62   leave the datab
2be0: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
2bf0: 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e 20 5b  pen and return [
2c00: 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a  SQLITE_BUSY]..**
2c10: 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6c 6f   ^If sqlite3_clo
2c20: 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  se_v2() is calle
2c30: 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c 69 7a  d with unfinaliz
2c40: 65 64 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ed prepared stat
2c50: 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20 75 6e  ements.** and un
2c60: 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74 65 33  finished sqlite3
2c70: 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e 20 74  _backups, then t
2c80: 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2c90: 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73 0a 2a  ection becomes.*
2ca0: 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20 22 7a  * an unusable "z
2cb0: 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77 69 6c  ombie" which wil
2cc0: 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  l automatically 
2cd0: 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 77  be deallocated w
2ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73 74 20  hen the.** last 
2cf0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d00: 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65 64 20  nt is finalized 
2d10: 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  or the last sqli
2d20: 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a 2a 2a  te3_backup is.**
2d30: 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68 65 20   finished.  The 
2d40: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
2d50: 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  () interface is 
2d60: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
2d70: 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20 6c 61   with.** host la
2d80: 6e 67 75 61 67 65 73 20 74 68 61 74 20 61 72 65  nguages that are
2d90: 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65 63 74   garbage collect
2da0: 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20 74 68  ed, and where th
2db0: 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69 63 68  e order in which
2dc0: 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72 73 20  .** destructors 
2dd0: 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20 61 72  are called is ar
2de0: 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 41  bitrary..**.** A
2df0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
2e00: 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ld [sqlite3_fina
2e10: 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a 65 5d  lize | finalize]
2e20: 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73   all [prepared s
2e30: 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a 20 5b  tatements],.** [
2e40: 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f  sqlite3_blob_clo
2e50: 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20  se | close] all 
2e60: 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20  [BLOB handles], 
2e70: 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  and .** [sqlite3
2e80: 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68 20 7c  _backup_finish |
2e90: 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b 73 71   finish] all [sq
2ea0: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62  lite3_backup] ob
2eb0: 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74 65 64  jects associated
2ec0: 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 73 71  .** with the [sq
2ed0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 72  lite3] object pr
2ee0: 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74 69 6e  ior to attemptin
2ef0: 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65 20 6f  g to close the o
2f00: 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a 20 73  bject.  ^If.** s
2f10: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28  qlite3_close_v2(
2f20: 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61  ) is called on a
2f30: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
2f40: 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c  ction] that stil
2f50: 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e  l has.** outstan
2f60: 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73  ding [prepared s
2f70: 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f  tatements], [BLO
2f80: 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e 64 2f  B handles], and/
2f90: 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  or.** [sqlite3_b
2fa0: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 74  ackup] objects t
2fb0: 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73 20 53  hen it returns S
2fc0: 51 4c 49 54 45 5f 4f 4b 20 62 75 74 20 74 68 65  QLITE_OK but the
2fd0: 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a   deallocation.**
2fe0: 20 6f 66 20 72 65 73 6f 75 72 63 65 73 20 69 73   of resources is
2ff0: 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c 20   deferred until 
3000: 61 6c 6c 20 5b 70 72 65 70 61 72 65 64 20 73 74  all [prepared st
3010: 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42 4c 4f 42  atements], [BLOB
3020: 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a 2a 20 61 6e   handles],.** an
3030: 64 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  d [sqlite3_backu
3040: 70 5d 20 6f 62 6a 65 63 74 73 20 61 72 65 20 61  p] objects are a
3050: 6c 73 6f 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a  lso destroyed..*
3060: 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 5b 73 71 6c  *.** ^If an [sql
3070: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 20  ite3] object is 
3080: 64 65 73 74 72 6f 79 65 64 20 77 68 69 6c 65 20  destroyed while 
3090: 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
30a0: 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72   open,.** the tr
30b0: 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74  ansaction is aut
30c0: 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65  omatically rolle
30d0: 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68  d back..**.** Th
30e0: 65 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f  e C parameter to
30f0: 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
3100: 43 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  C)] and [sqlite3
3110: 5f 63 6c 6f 73 65 5f 76 32 28 43 29 5d 0a 2a 2a  _close_v2(C)].**
3120: 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
3130: 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
3140: 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74 65 33  r or an [sqlite3
3150: 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74 65 72  ] object pointer
3160: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3170: 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  m [sqlite3_open(
3180: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
3190: 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31a0: 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
31b0: 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65 76 69  ], and not previ
31c0: 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a  ously closed..**
31d0: 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65   ^Calling sqlite
31e0: 33 5f 63 6c 6f 73 65 28 29 20 6f 72 20 73 71 6c  3_close() or sql
31f0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
3200: 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  with a NULL poin
3210: 74 65 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  ter.** argument 
3220: 69 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f  is a harmless no
3230: 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  -op..*/.int sqli
3240: 74 65 33 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65  te3_close(sqlite
3250: 33 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  3*);.int sqlite3
3260: 5f 63 6c 6f 73 65 5f 76 32 28 73 71 6c 69 74 65  _close_v2(sqlite
3270: 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20  3*);../*.** The 
3280: 74 79 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62  type for a callb
3290: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ack function..**
32a0: 20 54 68 69 73 20 69 73 20 6c 65 67 61 63 79 20   This is legacy 
32b0: 61 6e 64 20 64 65 70 72 65 63 61 74 65 64 2e 20  and deprecated. 
32c0: 20 49 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20   It is included 
32d0: 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a  for historical.*
32e0: 2a 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  * compatibility 
32f0: 61 6e 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d  and is not docum
3300: 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65  ented..*/.typede
3310: 66 20 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f  f int (*sqlite3_
3320: 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c  callback)(void*,
3330: 69 6e 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72  int,char**, char
3340: 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  **);../*.** CAPI
3350: 33 52 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51  3REF: One-Step Q
3360: 75 65 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49  uery Execution I
3370: 6e 74 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54  nterface.**.** T
3380: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3390: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 61  ) interface is a
33a0: 20 63 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61   convenience wra
33b0: 70 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b  pper around.** [
33c0: 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
33d0: 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
33e0: 73 74 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71  step()], and [sq
33f0: 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
3400: 5d 2c 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77  ],.** that allow
3410: 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
3420: 20 74 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65   to run multiple
3430: 20 73 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53   statements of S
3440: 51 4c 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61  QL.** without ha
3450: 76 69 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f  ving to use a lo
3460: 74 20 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a  t of C code. .**
3470: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
3480: 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61 63  _exec() interfac
3490: 65 20 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d  e runs zero or m
34a0: 6f 72 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65  ore UTF-8 encode
34b0: 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d  d,.** semicolon-
34c0: 73 65 70 61 72 61 74 65 20 53 51 4c 20 73 74 61  separate SQL sta
34d0: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
34e0: 6e 74 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75  nto its 2nd argu
34f0: 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20  ment,.** in the 
3500: 63 6f 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b  context of the [
3510: 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
3520: 69 6f 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61  ion] passed in a
3530: 73 20 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67  s its 1st.** arg
3540: 75 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ument.  ^If the 
3550: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3560: 6e 20 6f 66 20 74 68 65 20 33 72 64 20 61 72 67  n of the 3rd arg
3570: 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69  ument to.** sqli
3580: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
3590: 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20  t NULL, then it 
35a0: 69 73 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65  is invoked for e
35b0: 61 63 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a  ach result row.*
35c0: 2a 20 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20  * coming out of 
35d0: 74 68 65 20 65 76 61 6c 75 61 74 65 64 20 53 51  the evaluated SQ
35e0: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e  L statements.  ^
35f0: 54 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74  The 4th argument
3600: 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65   to.** sqlite3_e
3610: 78 65 63 28 29 20 69 73 20 72 65 6c 61 79 65 64  xec() is relayed
3620: 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
3630: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  1st argument of 
3640: 65 61 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  each.** callback
3650: 20 69 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49   invocation.  ^I
3660: 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70  f the callback p
3670: 6f 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ointer to sqlite
3680: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e  3_exec().** is N
3690: 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c  ULL, then no cal
36a0: 6c 62 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e  lback is ever in
36b0: 76 6f 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74  voked and result
36c0: 20 72 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e   rows are.** ign
36d0: 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ored..**.** ^If 
36e0: 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  an error occurs 
36f0: 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67  while evaluating
3700: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3710: 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a  nts passed into.
3720: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3730: 29 2c 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f  ), then executio
3740: 6e 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74  n of the current
3750: 20 73 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73   statement stops
3760: 20 61 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65   and.** subseque
3770: 6e 74 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  nt statements ar
3780: 65 20 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20  e skipped.  ^If 
3790: 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
37a0: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
37b0: 63 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55  c().** is not NU
37c0: 4c 4c 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f  LL then any erro
37d0: 72 20 6d 65 73 73 61 67 65 20 69 73 20 77 72 69  r message is wri
37e0: 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79  tten into memory
37f0: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
3800: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
3810: 63 28 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20  c()] and passed 
3820: 62 61 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65  back through the
3830: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a   5th parameter..
3840: 2a 2a 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f  ** To avoid memo
3850: 72 79 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70  ry leaks, the ap
3860: 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
3870: 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33   invoke [sqlite3
3880: 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65  _free()].** on e
3890: 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
38a0: 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20 74 68  ings returned th
38b0: 72 6f 75 67 68 20 74 68 65 20 35 74 68 20 70 61  rough the 5th pa
38c0: 72 61 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66  rameter of.** of
38d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
38e0: 61 66 74 65 72 20 74 68 65 20 65 72 72 6f 72 20  after the error 
38f0: 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69  message string i
3900: 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64  s no longer need
3910: 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35  ed..** ^If the 5
3920: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
3930: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3940: 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e  s not NULL and n
3950: 6f 20 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75  o errors.** occu
3960: 72 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  r, then sqlite3_
3970: 65 78 65 63 28 29 20 73 65 74 73 20 74 68 65 20  exec() sets the 
3980: 70 6f 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35  pointer in its 5
3990: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
39a0: 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72  ** NULL before r
39b0: 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  eturning..**.** 
39c0: 5e 49 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65  ^If an sqlite3_e
39d0: 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72  xec() callback r
39e0: 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
39f0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65   the sqlite3_exe
3a00: 63 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  c().** routine r
3a10: 65 74 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42  eturns SQLITE_AB
3a20: 4f 52 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f  ORT without invo
3a30: 6b 69 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63  king the callbac
3a40: 6b 20 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77  k again and.** w
3a50: 69 74 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61  ithout running a
3a60: 6e 79 20 73 75 62 73 65 71 75 65 6e 74 20 53 51  ny subsequent SQ
3a70: 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  L statements..**
3a80: 0a 2a 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67  .** ^The 2nd arg
3a90: 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c  ument to the sql
3aa0: 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c  ite3_exec() call
3ab0: 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73  back function is
3ac0: 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
3ad0: 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
3ae0: 20 72 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33   result.  ^The 3
3af0: 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  rd argument to t
3b00: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
3b10: 29 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73  ).** callback is
3b20: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3b30: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3b40: 20 6f 62 74 61 69 6e 65 64 20 61 73 20 69 66 20   obtained as if 
3b50: 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  from.** [sqlite3
3b60: 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
3b70: 20 6f 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f   one for each co
3b80: 6c 75 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c  lumn.  ^If an el
3b90: 65 6d 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65  ement of a.** re
3ba0: 73 75 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c  sult row is NULL
3bb0: 20 74 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73   then the corres
3bc0: 70 6f 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70  ponding string p
3bd0: 6f 69 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a  ointer for the.*
3be0: 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  * sqlite3_exec()
3bf0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e   callback is a N
3c00: 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54  ULL pointer.  ^T
3c10: 68 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20  he 4th argument 
3c20: 74 6f 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65  to the.** sqlite
3c30: 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63  3_exec() callbac
3c40: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3c50: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3c60: 69 6e 67 73 20 77 68 65 72 65 20 65 61 63 68 0a  ings where each.
3c70: 2a 2a 20 65 6e 74 72 79 20 72 65 70 72 65 73 65  ** entry represe
3c80: 6e 74 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  nts the name of 
3c90: 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65  corresponding re
3ca0: 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f  sult column as o
3cb0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
3cc0: 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
3cd0: 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  name()]..**.** ^
3ce0: 49 66 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  If the 2nd param
3cf0: 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
3d00: 65 78 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c  exec() is a NULL
3d10: 20 70 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e   pointer, a poin
3d20: 74 65 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70  ter.** to an emp
3d30: 74 79 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20  ty string, or a 
3d40: 70 6f 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e  pointer that con
3d50: 74 61 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65  tains only white
3d60: 73 70 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a  space and/or .**
3d70: 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74   SQL comments, t
3d80: 68 65 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65  hen no SQL state
3d90: 6d 65 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61  ments are evalua
3da0: 74 65 64 20 61 6e 64 20 74 68 65 20 64 61 74 61  ted and the data
3db0: 62 61 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63  base.** is not c
3dc0: 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65  hanged..**.** Re
3dd0: 73 74 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a  strictions:.**.*
3de0: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  * <ul>.** <li> T
3df0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e00: 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74 20  ust insure that 
3e10: 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74 65  the 1st paramete
3e20: 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65  r to sqlite3_exe
3e30: 63 28 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61  c().**      is a
3e40: 20 76 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20   valid and open 
3e50: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
3e60: 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54  tion]..** <li> T
3e70: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
3e80: 75 73 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68  ust not close th
3e90: 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
3ea0: 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
3eb0: 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 74 68 65  d by.**      the
3ec0: 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74   1st parameter t
3ed0: 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  o sqlite3_exec()
3ee0: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3ef0: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3f00: 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61 70  ..** <li> The ap
3f10: 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
3f20: 6f 74 20 6d 6f 64 69 66 79 20 74 68 65 20 53 51  ot modify the SQ
3f30: 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
3f40: 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20   passed into.** 
3f50: 20 20 20 20 20 74 68 65 20 32 6e 64 20 70 61 72       the 2nd par
3f60: 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
3f70: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3f80: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3f90: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 2f 75   running..** </u
3fa0: 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l>.*/.int sqlite
3fb0: 33 5f 65 78 65 63 28 0a 20 20 73 71 6c 69 74 65  3_exec(.  sqlite
3fc0: 33 2a 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  3*,             
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
3ff0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
4000: 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 2c 20 20  nst char *sql,  
4010: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4020: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20           /* SQL 
4030: 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64 20  to be evaluated 
4040: 2a 2f 0a 20 20 69 6e 74 20 28 2a 63 61 6c 6c 62  */.  int (*callb
4050: 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63  ack)(void*,int,c
4060: 68 61 72 2a 2a 2c 63 68 61 72 2a 2a 29 2c 20 20  har**,char**),  
4070: 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 66 75 6e 63  /* Callback func
4080: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
4090: 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 2f 2a 20 31 73 74 20 61 72 67 75       /* 1st argu
40c0: 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 62 61 63 6b  ment to callback
40d0: 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 65 72 72   */.  char **err
40e0: 6d 73 67 20 20 20 20 20 20 20 20 20 20 20 20 20  msg             
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72   /* Error msg wr
4110: 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b  itten here */.);
4120: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
4130: 3a 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a 2a  : Result Codes.*
4140: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51 4c 49  * KEYWORDS: SQLI
4150: 54 45 5f 4f 4b 20 7b 65 72 72 6f 72 20 63 6f 64  TE_OK {error cod
4160: 65 7d 20 7b 65 72 72 6f 72 20 63 6f 64 65 73 7d  e} {error codes}
4170: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 72  .** KEYWORDS: {r
4180: 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b 72 65 73  esult code} {res
4190: 75 6c 74 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a  ult codes}.**.**
41a0: 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e   Many SQLite fun
41b0: 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e  ctions return an
41c0: 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20   integer result 
41d0: 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65  code from the se
41e0: 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20  t shown.** here 
41f0: 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69  in order to indi
4200: 63 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20  cate success or 
4210: 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e  failure..**.** N
4220: 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d  ew error codes m
4230: 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
4240: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
4250: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
4260: 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
4270: 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 7c 20 65  E_IOERR_READ | e
4280: 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
4290: 6f 64 65 73 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  odes],.** [sqlit
42a0: 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c  e3_vtab_on_confl
42b0: 69 63 74 28 29 5d 20 5b 53 51 4c 49 54 45 5f 52  ict()] [SQLITE_R
42c0: 4f 4c 4c 42 41 43 4b 20 7c 20 72 65 73 75 6c 74  OLLBACK | result
42d0: 20 63 6f 64 65 73 5d 2e 0a 2a 2f 0a 23 64 65 66   codes]..*/.#def
42e0: 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b 20 20 20  ine SQLITE_OK   
42f0: 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20 53          0   /* S
4300: 75 63 63 65 73 73 66 75 6c 20 72 65 73 75 6c 74  uccessful result
4310: 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e 69 6e 67   */./* beginning
4320: 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20  -of-error-codes 
4330: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4340: 45 5f 45 52 52 4f 52 20 20 20 20 20 20 20 20 31  E_ERROR        1
4350: 20 20 20 2f 2a 20 53 51 4c 20 65 72 72 6f 72 20     /* SQL error 
4360: 6f 72 20 6d 69 73 73 69 6e 67 20 64 61 74 61 62  or missing datab
4370: 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ase */.#define S
4380: 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41 4c 20 20  QLITE_INTERNAL  
4390: 20 20 20 32 20 20 20 2f 2a 20 49 6e 74 65 72 6e     2   /* Intern
43a0: 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f 72 20 69  al logic error i
43b0: 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23 64 65 66  n SQLite */.#def
43c0: 69 6e 65 20 53 51 4c 49 54 45 5f 50 45 52 4d 20  ine SQLITE_PERM 
43d0: 20 20 20 20 20 20 20 20 33 20 20 20 2f 2a 20 41          3   /* A
43e0: 63 63 65 73 73 20 70 65 72 6d 69 73 73 69 6f 6e  ccess permission
43f0: 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66 69   denied */.#defi
4400: 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ne SQLITE_ABORT 
4410: 20 20 20 20 20 20 20 34 20 20 20 2f 2a 20 43 61         4   /* Ca
4420: 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 72  llback routine r
4430: 65 71 75 65 73 74 65 64 20 61 6e 20 61 62 6f 72  equested an abor
4440: 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  t */.#define SQL
4450: 49 54 45 5f 42 55 53 59 20 20 20 20 20 20 20 20  ITE_BUSY        
4460: 20 35 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61   5   /* The data
4470: 62 61 73 65 20 66 69 6c 65 20 69 73 20 6c 6f 63  base file is loc
4480: 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ked */.#define S
4490: 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 20 20 20  QLITE_LOCKED    
44a0: 20 20 20 36 20 20 20 2f 2a 20 41 20 74 61 62 6c     6   /* A tabl
44b0: 65 20 69 6e 20 74 68 65 20 64 61 74 61 62 61 73  e in the databas
44c0: 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23  e is locked */.#
44d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
44e0: 4d 45 4d 20 20 20 20 20 20 20 20 37 20 20 20 2f  MEM        7   /
44f0: 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69  * A malloc() fai
4500: 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  led */.#define S
4510: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 20  QLITE_READONLY  
4520: 20 20 20 38 20 20 20 2f 2a 20 41 74 74 65 6d 70     8   /* Attemp
4530: 74 20 74 6f 20 77 72 69 74 65 20 61 20 72 65 61  t to write a rea
4540: 64 6f 6e 6c 79 20 64 61 74 61 62 61 73 65 20 2a  donly database *
4550: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4560: 5f 49 4e 54 45 52 52 55 50 54 20 20 20 20 39 20  _INTERRUPT    9 
4570: 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 74    /* Operation t
4580: 65 72 6d 69 6e 61 74 65 64 20 62 79 20 73 71 6c  erminated by sql
4590: 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
45a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
45b0: 45 5f 49 4f 45 52 52 20 20 20 20 20 20 20 31 30  E_IOERR       10
45c0: 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69 6e 64 20     /* Some kind 
45d0: 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65 72 72 6f  of disk I/O erro
45e0: 72 20 6f 63 63 75 72 72 65 64 20 2a 2f 0a 23 64  r occurred */.#d
45f0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 52  efine SQLITE_COR
4600: 52 55 50 54 20 20 20 20 20 31 31 20 20 20 2f 2a  RUPT     11   /*
4610: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 64 69   The database di
4620: 73 6b 20 69 6d 61 67 65 20 69 73 20 6d 61 6c 66  sk image is malf
4630: 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ormed */.#define
4640: 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44   SQLITE_NOTFOUND
4650: 20 20 20 20 31 32 20 20 20 2f 2a 20 55 6e 6b 6e      12   /* Unkn
4660: 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e 20 73 71  own opcode in sq
4670: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
4680: 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ol() */.#define 
4690: 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20 20 20 20  SQLITE_FULL     
46a0: 20 20 20 31 33 20 20 20 2f 2a 20 49 6e 73 65 72     13   /* Inser
46b0: 74 69 6f 6e 20 66 61 69 6c 65 64 20 62 65 63 61  tion failed beca
46c0: 75 73 65 20 64 61 74 61 62 61 73 65 20 69 73 20  use database is 
46d0: 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20  full */.#define 
46e0: 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20  SQLITE_CANTOPEN 
46f0: 20 20 20 31 34 20 20 20 2f 2a 20 55 6e 61 62 6c     14   /* Unabl
4700: 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61  e to open the da
4710: 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f 0a 23  tabase file */.#
4720: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
4730: 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20 20 20 2f  OTOCOL    15   /
4740: 2a 20 44 61 74 61 62 61 73 65 20 6c 6f 63 6b 20  * Database lock 
4750: 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f 72 20 2a  protocol error *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 45 4d 50 54 59 20 20 20 20 20 20 20 31 36 20  _EMPTY       16 
4780: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 69 73    /* Database is
4790: 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65 66 69 6e   empty */.#defin
47a0: 65 20 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 20  e SQLITE_SCHEMA 
47b0: 20 20 20 20 20 31 37 20 20 20 2f 2a 20 54 68 65       17   /* The
47c0: 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
47d0: 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23 64 65 66   changed */.#def
47e0: 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f 4f 42 49  ine SQLITE_TOOBI
47f0: 47 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 53  G      18   /* S
4800: 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 65 78  tring or BLOB ex
4810: 63 65 65 64 73 20 73 69 7a 65 20 6c 69 6d 69 74  ceeds size limit
4820: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4830: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 20 31  TE_CONSTRAINT  1
4840: 39 20 20 20 2f 2a 20 41 62 6f 72 74 20 64 75 65  9   /* Abort due
4850: 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e 74 20 76   to constraint v
4860: 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23 64 65 66  iolation */.#def
4870: 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 4d 41  ine SQLITE_MISMA
4880: 54 43 48 20 20 20 20 32 30 20 20 20 2f 2a 20 44  TCH    20   /* D
4890: 61 74 61 20 74 79 70 65 20 6d 69 73 6d 61 74 63  ata type mismatc
48a0: 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  h */.#define SQL
48b0: 49 54 45 5f 4d 49 53 55 53 45 20 20 20 20 20 20  ITE_MISUSE      
48c0: 32 31 20 20 20 2f 2a 20 4c 69 62 72 61 72 79 20  21   /* Library 
48d0: 75 73 65 64 20 69 6e 63 6f 72 72 65 63 74 6c 79  used incorrectly
48e0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48f0: 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20 20 20 32  TE_NOLFS       2
4900: 32 20 20 20 2f 2a 20 55 73 65 73 20 4f 53 20 66  2   /* Uses OS f
4910: 65 61 74 75 72 65 73 20 6e 6f 74 20 73 75 70 70  eatures not supp
4920: 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74 20 2a 2f  orted on host */
4930: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4940: 41 55 54 48 20 20 20 20 20 20 20 20 32 33 20 20  AUTH        23  
4950: 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61 74 69 6f   /* Authorizatio
4960: 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64 65 66  n denied */.#def
4970: 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f 52 4d 41  ine SQLITE_FORMA
4980: 54 20 20 20 20 20 20 32 34 20 20 20 2f 2a 20 41  T      24   /* A
4990: 75 78 69 6c 69 61 72 79 20 64 61 74 61 62 61 73  uxiliary databas
49a0: 65 20 66 6f 72 6d 61 74 20 65 72 72 6f 72 20 2a  e format error *
49b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
49c0: 5f 52 41 4e 47 45 20 20 20 20 20 20 20 32 35 20  _RANGE       25 
49d0: 20 20 2f 2a 20 32 6e 64 20 70 61 72 61 6d 65 74    /* 2nd paramet
49e0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
49f0: 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 20  nd out of range 
4a00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4a10: 45 5f 4e 4f 54 41 44 42 20 20 20 20 20 20 32 36  E_NOTADB      26
4a20: 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70 65 6e 65     /* File opene
4a30: 64 20 74 68 61 74 20 69 73 20 6e 6f 74 20 61 20  d that is not a 
4a40: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a 2f  database file */
4a50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4a60: 4e 4f 54 49 43 45 20 20 20 20 20 20 32 37 20 20  NOTICE      27  
4a70: 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e   /* Notification
4a80: 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6c  s from sqlite3_l
4a90: 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e 65 20  og() */.#define 
4aa0: 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 20  SQLITE_WARNING  
4ab0: 20 20 20 32 38 20 20 20 2f 2a 20 57 61 72 6e 69     28   /* Warni
4ac0: 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ngs from sqlite3
4ad0: 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69 6e  _log() */.#defin
4ae0: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4af0: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4b00: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4b10: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4b20: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4b30: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4b40: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4b50: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4b60: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4b70: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
4b80: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
4b90: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
4ba0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
4bb0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
4bc0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
4bd0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4be0: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4bf0: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4c00: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4c10: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4c20: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4c30: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4c40: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4c50: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4c60: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4c70: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
4c80: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
4c90: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
4ca0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
4cb0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
4cc0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
4cd0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4ce0: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4cf0: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4d00: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4d10: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4d20: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4d30: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4d40: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4d50: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4d60: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4d70: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
4d80: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
4d90: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
4da0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
4db0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
4dc0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
4dd0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4de0: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4df0: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4e00: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4e10: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4e20: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4e30: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4e40: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4e50: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4e60: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4e70: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
4e80: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
4e90: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
4ea0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
4eb0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4ec0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
4ed0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4ee0: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4ef0: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4f00: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 69 6e 63  t codes will inc
4f10: 72 65 61 73 65 0a 2a 2a 20 6f 76 65 72 20 74 69  rease.** over ti
4f20: 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68  me.  Software th
4f30: 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65 64  at uses extended
4f40: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73 68   result codes sh
4f50: 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20 74  ould expect.** t
4f60: 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c 74  o see new result
4f70: 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72 65   codes in future
4f80: 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
4f90: 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  ite..**.** The S
4fa0: 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74 20  QLITE_OK result 
4fb0: 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72 20  code will never 
4fc0: 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49 74  be extended.  It
4fd0: 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a 20   will always.** 
4fe0: 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f 2e  be exactly zero.
4ff0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
5000: 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20  TE_IOERR_READ   
5010: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
5020: 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38  TE_IOERR | (1<<8
5030: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5040: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
5050: 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  AD        (SQLIT
5060: 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29  E_IOERR | (2<<8)
5070: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5080: 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20  _IOERR_WRITE    
5090: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
50a0: 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29  _IOERR | (3<<8))
50b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
50c0: 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20  IOERR_FSYNC     
50d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
50e0: 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a  IOERR | (4<<8)).
50f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5100: 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20  OERR_DIR_FSYNC  
5110: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
5120: 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23  OERR | (5<<8)).#
5130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5140: 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20  ERR_TRUNCATE    
5150: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
5160: 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64  ERR | (6<<8)).#d
5170: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5180: 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20 20  RR_FSTAT        
5190: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
51a0: 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65  RR | (7<<8)).#de
51b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
51c0: 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_UNLOCK        
51d0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
51e0: 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  R | (8<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  _RDLOCK         
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69   | (9<<8)).#defi
5230: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5240: 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20  DELETE          
5250: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5260: 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (10<<8)).#defi
5270: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5280: 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20  BLOCKED         
5290: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52a0: 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (11<<8)).#defi
52b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
52c0: 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20  NOMEM           
52d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
52e0: 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (12<<8)).#defi
52f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5300: 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20 20  ACCESS          
5310: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5320: 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (13<<8)).#defi
5330: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5340: 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43  CHECKRESERVEDLOC
5350: 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20  K (SQLITE_IOERR 
5360: 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (14<<8)).#defi
5370: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5380: 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20 20  LOCK            
5390: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53a0: 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (15<<8)).#defi
53b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
53c0: 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20 20  CLOSE           
53d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
53e0: 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (16<<8)).#defi
53f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5400: 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20  DIR_CLOSE       
5410: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5420: 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69  | (17<<8)).#defi
5430: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5440: 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20  SHMOPEN         
5450: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5460: 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69  | (18<<8)).#defi
5470: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5480: 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20  SHMSIZE         
5490: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54a0: 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69  | (19<<8)).#defi
54b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
54c0: 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20  SHMLOCK         
54d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
54e0: 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69  | (20<<8)).#defi
54f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5500: 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20  SHMMAP          
5510: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5520: 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69  | (21<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5540: 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20 20  SEEK            
5550: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5560: 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69  | (22<<8)).#defi
5570: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5580: 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20  DELETE_NOENT    
5590: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55a0: 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69  | (23<<8)).#defi
55b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
55c0: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
55d0: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
55e0: 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69  | (24<<8)).#defi
55f0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5600: 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20 20  GETTEMPPATH     
5610: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5620: 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69  | (25<<8)).#defi
5630: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5640: 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20 20  CONVPATH        
5650: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5660: 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69  | (26<<8)).#defi
5670: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44  ne SQLITE_LOCKED
5680: 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20 20  _SHAREDCACHE    
5690: 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44    (SQLITE_LOCKED
56a0: 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66   |  (1<<8)).#def
56b0: 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f  ine SQLITE_BUSY_
56c0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 20  RECOVERY        
56d0: 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20     (SQLITE_BUSY 
56e0: 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65    |  (1<<8)).#de
56f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5700: 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20  _SNAPSHOT       
5710: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5720: 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64     |  (2<<8)).#d
5730: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5740: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5750: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5760: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5770: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5780: 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20  ANTOPEN_ISDIR   
5790: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
57a0: 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29  ANTOPEN | (2<<8)
57b0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
57c0: 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41  _CANTOPEN_FULLPA
57d0: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
57e0: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c  _CANTOPEN | (3<<
57f0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5800: 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56  TE_CANTOPEN_CONV
5810: 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49  PATH       (SQLI
5820: 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34  TE_CANTOPEN | (4
5830: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5840: 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41  LITE_CORRUPT_VTA
5850: 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51  B            (SQ
5860: 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28  LITE_CORRUPT | (
5870: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5880: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52  QLITE_READONLY_R
5890: 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28 53  ECOVERY       (S
58a0: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
58b0: 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (1<<8)).#define
58c0: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
58d0: 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20  _CANTLOCK       
58e0: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
58f0: 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69   | (2<<8)).#defi
5900: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5910: 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20  LY_ROLLBACK     
5920: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
5930: 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65  LY | (3<<8)).#de
5940: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
5950: 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20  ONLY_DBMOVED    
5960: 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44      (SQLITE_READ
5970: 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23  ONLY | (4<<8)).#
5980: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42  define SQLITE_AB
5990: 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  ORT_ROLLBACK    
59a0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42        (SQLITE_AB
59b0: 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64  ORT | (2<<8)).#d
59c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
59d0: 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20  STRAINT_CHECK   
59e0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
59f0: 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29  STRAINT | (1<<8)
5a00: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5a10: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d  _CONSTRAINT_COMM
5a20: 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45  ITHOOK   (SQLITE
5a30: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32  _CONSTRAINT | (2
5a40: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5a50: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5a60: 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51  FOREIGNKEY   (SQ
5a70: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5a80: 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (3<<8)).#defin
5a90: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5aa0: 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20  INT_FUNCTION    
5ab0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5ac0: 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  INT | (4<<8)).#d
5ad0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5ae0: 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20  STRAINT_NOTNULL 
5af0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5b00: 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29  STRAINT | (5<<8)
5b10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5b20: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d  _CONSTRAINT_PRIM
5b30: 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45  ARYKEY   (SQLITE
5b40: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36  _CONSTRAINT | (6
5b50: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5b60: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  LITE_CONSTRAINT_
5b70: 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53 51  TRIGGER      (SQ
5b80: 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20  LITE_CONSTRAINT 
5b90: 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (7<<8)).#defin
5ba0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
5bb0: 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20  INT_UNIQUE      
5bc0: 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41   (SQLITE_CONSTRA
5bd0: 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  INT | (8<<8)).#d
5be0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
5bf0: 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20  STRAINT_VTAB    
5c00: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e       (SQLITE_CON
5c10: 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29  STRAINT | (9<<8)
5c20: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5c30: 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49  _CONSTRAINT_ROWI
5c40: 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  D        (SQLITE
5c50: 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30  _CONSTRAINT |(10
5c60: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5c70: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5c80: 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51  VER_WAL      (SQ
5c90: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31  LITE_NOTICE | (1
5ca0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cb0: 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f  LITE_NOTICE_RECO
5cc0: 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51  VER_ROLLBACK (SQ
5cd0: 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32  LITE_NOTICE | (2
5ce0: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5cf0: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54  LITE_WARNING_AUT
5d00: 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53 51  OINDEX       (SQ
5d10: 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28  LITE_WARNING | (
5d20: 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  1<<8))../*.** CA
5d30: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
5d40: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
5d50: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
5d60: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
5d70: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
5d80: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5d90: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5da0: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5db0: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5dc0: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5dd0: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5de0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5df0: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5e00: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e10: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5e20: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e30: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
5e40: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5e50: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5e60: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
5e70: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5e80: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5e90: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ea0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5eb0: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5ec0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5ed0: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5ee0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5ef0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f00: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5f10: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5f20: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
5f30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f40: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
5f50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5f60: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5f70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5f80: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5f90: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5fa0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5fb0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5fc0: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5fd0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5fe0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5ff0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6000: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6010: 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20  _OPEN_MEMORY    
6020: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6030: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6040: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6050: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6060: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
6070: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
6080: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6090: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60a0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
60b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
60c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
60d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
60e0: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
60f0: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
6100: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6110: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6120: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
6130: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
6140: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6150: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6160: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
6170: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
6180: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6190: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61a0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
61b0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
61c0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
61d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
61e0: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
61f0: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
6200: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6210: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6220: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
6230: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
6240: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6250: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6270: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
6280: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
6290: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62a0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
62b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
62c0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
62d0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
62e0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
62f0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6300: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6310: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
6320: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
6330: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
6340: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
6350: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
6360: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
6370: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
6380: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
6390: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
63a0: 5f 4f 50 45 4e 5f 46 49 4c 45 50 52 4f 54 45 43  _OPEN_FILEPROTEC
63b0: 54 49 4f 4e 5f 4d 41 53 4b 20 20 20 20 20 20 20  TION_MASK       
63c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
63d0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 37 30            0x0070
63e0: 30 30 30 30 0a 0a 2f 2a 20 52 65 73 65 72 76 65  0000../* Reserve
63f0: 64 3a 20 20 20 20 20 20 20 20 20 20 20 20 20 20  d:              
6400: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 46             0x00F
6410: 30 30 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  00000 */../*.** 
6420: 43 41 50 49 33 52 45 46 3a 20 44 65 76 69 63 65  CAPI3REF: Device
6430: 20 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73   Characteristics
6440: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69  .**.** The xDevi
6450: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
6460: 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
6470: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6480: 6f 64 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72  ods].** object r
6490: 65 74 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65  eturns an intege
64a0: 72 20 77 68 69 63 68 20 69 73 20 61 20 76 65 63  r which is a vec
64b0: 74 6f 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  tor of these.** 
64c0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
64d0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
64e0: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
64f0: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
6500: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
6510: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
6520: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
6530: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
6540: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
6550: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6560: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
6570: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
6580: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
6590: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
65a0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
65b0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
65c0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
65d0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
65e0: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
65f0: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
6600: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
6610: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
6620: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
6630: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
6640: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
6650: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6660: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
6670: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
6680: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
6690: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
66a0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
66b0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
66c0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
66d0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
66e0: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
66f0: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
6700: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
6710: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
6720: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
6730: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
6740: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
6750: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
6760: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
6770: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
6780: 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45  e().  The SQLITE
6790: 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45  _IOCAP_POWERSAFE
67a0: 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70 65  _OVERWRITE prope
67b0: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
67c0: 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66  * after reboot f
67d0: 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68  ollowing a crash
67e0: 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20   or power loss, 
67f0: 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69  the only bytes i
6800: 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74  n a.** file that
6810: 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61 74   were written at
6820: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
6830: 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76   level might hav
6840: 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64  e changed.** and
6850: 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62   that adjacent b
6860: 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73  ytes, even bytes
6870: 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
6880: 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67   sector are.** g
6890: 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20  uaranteed to be 
68a0: 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20  unchanged.  The 
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44  SQLITE_IOCAP_UND
68c0: 45 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50  ELETABLE_WHEN_OP
68d0: 45 4e 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63  EN.** flag indic
68e0: 61 74 65 20 74 68 61 74 20 61 20 66 69 6c 65 20  ate that a file 
68f0: 63 61 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65  cannot be delete
6900: 64 20 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68  d when open.  Th
6910: 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41  e.** SQLITE_IOCA
6920: 50 5f 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67  P_IMMUTABLE flag
6930: 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20   indicates that 
6940: 74 68 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a  the file is on.*
6950: 2a 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69  * read-only medi
6960: 61 20 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20  a and cannot be 
6970: 63 68 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20  changed even by 
6980: 70 72 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a  processes with.*
6990: 2a 20 65 6c 65 76 61 74 65 64 20 70 72 69 76 69  * elevated privi
69a0: 6c 65 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e  leges..*/.#defin
69b0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
69c0: 54 4f 4d 49 43 20 20 20 20 20 20 20 20 20 20 20  TOMIC           
69d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
69e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
69f0: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20  IOCAP_ATOMIC512 
6a00: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
6a10: 30 30 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20  0000002.#define 
6a20: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6a30: 4d 49 43 31 4b 20 20 20 20 20 20 20 20 20 20 20  MIC1K           
6a40: 20 20 20 20 30 78 30 30 30 30 30 30 30 34 0a 23      0x00000004.#
6a50: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
6a60: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20  CAP_ATOMIC2K    
6a70: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6a80: 30 30 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51  00008.#define SQ
6a90: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6aa0: 43 34 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C4K             
6ab0: 20 20 30 78 30 30 30 30 30 30 31 30 0a 23 64 65    0x00000010.#de
6ac0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6ad0: 50 5f 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20  P_ATOMIC8K      
6ae0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6af0: 30 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  020.#define SQLI
6b00: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31  TE_IOCAP_ATOMIC1
6b10: 36 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  6K              
6b20: 30 78 30 30 30 30 30 30 34 30 0a 23 64 65 66 69  0x00000040.#defi
6b30: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
6b40: 41 54 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20  ATOMIC32K       
6b50: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 38         0x0000008
6b60: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6b70: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b  _IOCAP_ATOMIC64K
6b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6b90: 30 30 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65  00000100.#define
6ba0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41   SQLITE_IOCAP_SA
6bb0: 46 45 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20  FE_APPEND       
6bc0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 0a       0x00000200.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6be0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20  OCAP_SEQUENTIAL 
6bf0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6c00: 30 30 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53  000400.#define S
6c10: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45  QLITE_IOCAP_UNDE
6c20: 4c 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45  LETABLE_WHEN_OPE
6c30: 4e 20 20 30 78 30 30 30 30 30 38 30 30 0a 23 64  N  0x00000800.#d
6c40: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
6c50: 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  AP_POWERSAFE_OVE
6c60: 52 57 52 49 54 45 20 20 20 20 30 78 30 30 30 30  RWRITE    0x0000
6c70: 31 30 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  1000.#define SQL
6c80: 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
6c90: 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 20 20  BLE             
6ca0: 20 30 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a   0x00002000../*.
6cb0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
6cc0: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
6cd0: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
6ce0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
6cf0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
6d00: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
6d10: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
6d20: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
6d30: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
6d40: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
6d50: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
6d60: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
6d70: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
6d80: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
6d90: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
6da0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
6db0: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
6dc0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6dd0: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
6de0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
6df0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
6e00: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
6e10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
6e20: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
6e30: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
6e40: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
6e50: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
6e60: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6e70: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6e80: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6e90: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6ea0: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6eb0: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6ec0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6ed0: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6ee0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6ef0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6f00: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
6f10: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
6f20: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
6f30: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
6f40: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
6f50: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
6f60: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6f70: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6f80: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6f90: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6fa0: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6fb0: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6fc0: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6fd0: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6fe0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6ff0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
7000: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
7010: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
7020: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
7030: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
7040: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
7050: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
7060: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
7070: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
7080: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
7090: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
70a0: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
70b0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
70c0: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
70d0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
70e0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
70f0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
7100: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
7110: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
7120: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
7130: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
7140: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
7150: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
7160: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
7170: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
7180: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
7190: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
71a0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
71b0: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
71c0: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
71d0: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
71e0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
71f0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
7200: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
7210: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
7220: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
7230: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
7240: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
7250: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
7260: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
7270: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
7280: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
7290: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
72a0: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
72b0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
72c0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
72d0: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
72e0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
72f0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
7300: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
7310: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
7320: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
7330: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
7340: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
7350: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
7360: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
7370: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
7380: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
7390: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
73a0: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
73b0: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
73c0: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
73d0: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
73e0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
73f0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
7400: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
7410: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
7420: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
7430: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
7440: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
7450: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
7460: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
7470: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
7480: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
7490: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
74a0: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
74b0: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
74c0: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
74d0: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
74e0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
74f0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
7500: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
7510: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
7520: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
7530: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
7540: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
7550: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
7560: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
7570: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
7580: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
7590: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
75a0: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
75b0: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
75c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
75d0: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
75e0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
75f0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
7600: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
7610: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
7620: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
7630: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
7640: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
7650: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
7660: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
7670: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
7680: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
7690: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
76a0: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
76b0: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
76c0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
76d0: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
76e0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
76f0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
7700: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
7710: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
7720: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
7730: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
7740: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
7750: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
7760: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
7770: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
7780: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
7790: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
77a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
77b0: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
77c0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
77d0: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
77e0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
77f0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
7800: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
7810: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
7820: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
7830: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
7840: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
7850: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
7860: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
7870: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
7880: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
7890: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
78a0: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
78b0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
78c0: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
78d0: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
78e0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
78f0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
7900: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
7910: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
7920: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
7930: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
7940: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
7950: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
7960: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
7970: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
7980: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
7990: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
79a0: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
79b0: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
79c0: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
79d0: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
79e0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
79f0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
7a00: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
7a10: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
7a20: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
7a30: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
7a40: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
7a50: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
7a60: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
7a70: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
7a80: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
7a90: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
7aa0: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7ab0: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
7ac0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7ad0: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
7ae0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
7af0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
7b00: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
7b10: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
7b20: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
7b30: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
7b40: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
7b50: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
7b60: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
7b70: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
7b80: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
7b90: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
7ba0: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
7bb0: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
7bc0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
7bd0: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
7be0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
7bf0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
7c00: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
7c10: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
7c20: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
7c30: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
7c40: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
7c50: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
7c60: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
7c70: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
7c80: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
7c90: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
7ca0: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
7cb0: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
7cc0: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
7cd0: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
7ce0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
7cf0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
7d00: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
7d10: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
7d20: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
7d30: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
7d40: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
7d50: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
7d60: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
7d70: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
7d80: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
7d90: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
7da0: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
7db0: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
7dc0: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
7dd0: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
7de0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
7df0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
7e00: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
7e10: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
7e20: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
7e30: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
7e40: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
7e50: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
7e60: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
7e70: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
7e80: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7e90: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7ea0: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7eb0: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7ec0: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7ed0: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
7ee0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
7ef0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
7f00: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
7f10: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
7f20: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
7f30: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
7f40: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
7f50: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7f60: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7f70: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7f80: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7f90: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7fa0: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7fb0: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7fc0: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7fd0: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
7fe0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
7ff0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
8000: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
8010: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
8020: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
8030: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
8040: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
8050: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
8060: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
8070: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
8080: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
8090: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
80a0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
80b0: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
80c0: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
80d0: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
80e0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
80f0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
8100: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
8110: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
8120: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
8130: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
8140: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
8150: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
8160: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
8170: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
8180: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
8190: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
81a0: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
81b0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
81c0: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
81d0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
81e0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
81f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8200: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
8210: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8220: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
8230: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8240: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
8250: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8260: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
8270: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
8280: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
8290: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
82a0: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
82b0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
82c0: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
82d0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
82e0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
82f0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
8300: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
8310: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
8320: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
8330: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
8340: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
8350: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
8360: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
8370: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8380: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
8390: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
83a0: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
83b0: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
83c0: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
83d0: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
83e0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
83f0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
8400: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
8410: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
8420: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
8430: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
8440: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
8450: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
8460: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
8470: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
8480: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
8490: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
84a0: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
84b0: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
84c0: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
84d0: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
84e0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
84f0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
8500: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
8510: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
8520: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
8530: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
8540: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
8550: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
8560: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
8570: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
8580: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
8590: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
85a0: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
85b0: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
85c0: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
85d0: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
85e0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
85f0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
8600: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
8610: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
8620: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
8630: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
8640: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
8650: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
8660: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
8670: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
8680: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
8690: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
86a0: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
86b0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
86c0: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
86d0: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
86e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
86f0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
8700: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8710: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
8720: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8730: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
8740: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
8750: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
8760: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8770: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8780: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
8790: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
87a0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
87b0: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
87c0: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
87d0: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
87e0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
87f0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
8800: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
8810: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
8820: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
8830: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
8840: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
8850: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
8860: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
8870: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
8880: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
8890: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
88a0: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
88b0: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
88d0: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
88e0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
88f0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8900: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
8910: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
8920: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
8930: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
8940: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
8950: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
8960: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
8970: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8980: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
8990: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
89a0: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
89b0: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
89c0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
89d0: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
89e0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
89f0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
8a00: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
8a10: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
8a20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8a30: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
8a40: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
8a50: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
8a60: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
8a70: 20 20 69 6e 74 20 28 2a 78 46 65 74 63 68 29 28    int (*xFetch)(
8a80: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73  sqlite3_file*, s
8a90: 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66  qlite3_int64 iOf
8aa0: 73 74 2c 20 69 6e 74 20 69 41 6d 74 2c 20 76 6f  st, int iAmt, vo
8ab0: 69 64 20 2a 2a 70 70 29 3b 0a 20 20 69 6e 74 20  id **pp);.  int 
8ac0: 28 2a 78 55 6e 66 65 74 63 68 29 28 73 71 6c 69  (*xUnfetch)(sqli
8ad0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8ae0: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8af0: 76 6f 69 64 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d  void *p);.  /* M
8b00: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
8b10: 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72 73 69   valid for versi
8b20: 6f 6e 20 33 20 2a 2f 0a 20 20 2f 2a 20 41 64 64  on 3 */.  /* Add
8b30: 69 74 69 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20  itional methods 
8b40: 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
8b50: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
8b60: 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
8b70: 49 33 52 45 46 3a 20 53 74 61 6e 64 61 72 64 20  I3REF: Standard 
8b80: 46 69 6c 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63  File Control Opc
8b90: 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  odes.**.** These
8ba0: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
8bb0: 74 73 20 61 72 65 20 6f 70 63 6f 64 65 73 20 66  ts are opcodes f
8bc0: 6f 72 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74  or the xFileCont
8bd0: 72 6f 6c 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66  rol method.** of
8be0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
8bf0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
8c00: 20 61 6e 64 20 66 6f 72 20 74 68 65 20 5b 73 71   and for the [sq
8c10: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
8c20: 6f 6c 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61  ol()].** interfa
8c30: 63 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ce..**.** The [S
8c40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b  QLITE_FCNTL_LOCK
8c50: 53 54 41 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  STATE] opcode is
8c60: 20 75 73 65 64 20 66 6f 72 20 64 65 62 75 67 67   used for debugg
8c70: 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70  ing.  This.** op
8c80: 63 6f 64 65 20 63 61 75 73 65 73 20 74 68 65 20  code causes the 
8c90: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
8ca0: 68 6f 64 20 74 6f 20 77 72 69 74 65 20 74 68 65  hod to write the
8cb0: 20 63 75 72 72 65 6e 74 20 73 74 61 74 65 20 6f   current state o
8cc0: 66 0a 2a 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f  f.** the lock (o
8cd0: 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f  ne of [SQLITE_LO
8ce0: 43 4b 5f 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54  CK_NONE], [SQLIT
8cf0: 45 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a  E_LOCK_SHARED],.
8d00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ** [SQLITE_LOCK_
8d10: 52 45 53 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49  RESERVED], [SQLI
8d20: 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d  TE_LOCK_PENDING]
8d30: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  , or [SQLITE_LOC
8d40: 4b 5f 45 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a  K_EXCLUSIVE]).**
8d50: 20 69 6e 74 6f 20 61 6e 20 69 6e 74 65 67 65 72   into an integer
8d60: 20 74 68 61 74 20 74 68 65 20 70 41 72 67 20 61   that the pArg a
8d70: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74  rgument points t
8d80: 6f 2e 20 54 68 69 73 20 63 61 70 61 62 69 6c 69  o. This capabili
8d90: 74 79 0a 2a 2a 20 69 73 20 75 73 65 64 20 64 75  ty.** is used du
8da0: 72 69 6e 67 20 74 65 73 74 69 6e 67 20 61 6e 64  ring testing and
8db0: 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62   only needs to b
8dc0: 65 20 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e  e supported when
8dd0: 20 53 51 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20   SQLITE_TEST.** 
8de0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c  is defined..** <
8df0: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  ul>.** <li>[[SQL
8e00: 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48  ITE_FCNTL_SIZE_H
8e10: 49 4e 54 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51  INT]].** The [SQ
8e20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
8e30: 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73 20  HINT] opcode is 
8e40: 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20 74  used by SQLite t
8e50: 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a 2a  o give the VFS.*
8e60: 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20 6f  * layer a hint o
8e70: 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65 20  f how large the 
8e80: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69  database file wi
8e90: 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64 75  ll grow to be du
8ea0: 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72 72  ring the.** curr
8eb0: 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e  ent transaction.
8ec0: 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20 6e    This hint is n
8ed0: 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74 6f  ot guaranteed to
8ee0: 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75 74   be accurate but
8ef0: 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e 20   it.** is often 
8f00: 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64 65  close.  The unde
8f10: 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68 74  rlying VFS might
8f20: 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61 6c   choose to preal
8f30: 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65 0a  locate database.
8f40: 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62 61  ** file space ba
8f50: 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e 74  sed on this hint
8f60: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65 6c   in order to hel
8f70: 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65 20  p writes to the 
8f80: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
8f90: 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a 0a   run faster..**.
8fa0: 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f  ** <li>[[SQLITE_
8fb0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
8fc0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
8fd0: 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49  E_FCNTL_CHUNK_SI
8fe0: 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  ZE] opcode is us
8ff0: 65 64 20 74 6f 20 72 65 71 75 65 73 74 20 74 68  ed to request th
9000: 61 74 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78  at the VFS.** ex
9010: 74 65 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61  tends and trunca
9020: 74 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  tes the database
9030: 20 66 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20   file in chunks 
9040: 6f 66 20 61 20 73 69 7a 65 20 73 70 65 63 69 66  of a size specif
9050: 69 65 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73  ied.** by the us
9060: 65 72 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61  er. The fourth a
9070: 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69  rgument to [sqli
9080: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9090: 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70  ()] should .** p
90a0: 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67  oint to an integ
90b0: 65 72 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f  er (type int) co
90c0: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77  ntaining the new
90d0: 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75   chunk-size to u
90e0: 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f  se.** for the no
90f0: 6d 69 6e 61 74 65 64 20 64 61 74 61 62 61 73 65  minated database
9100: 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74  . Allocating dat
9110: 61 62 61 73 65 20 66 69 6c 65 20 73 70 61 63 65  abase file space
9120: 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75   in large.** chu
9130: 6e 6b 73 20 28 73 61 79 20 31 4d 42 20 61 74 20  nks (say 1MB at 
9140: 61 20 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64  a time), may red
9150: 75 63 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20  uce file-system 
9160: 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  fragmentation an
9170: 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72  d.** improve per
9180: 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65  formance on some
9190: 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20   systems..**.** 
91a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
91b0: 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d  TL_FILE_POINTER]
91c0: 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  ].** The [SQLITE
91d0: 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e  _FCNTL_FILE_POIN
91e0: 54 45 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  TER] opcode is u
91f0: 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20  sed to obtain a 
9200: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68  pointer.** to th
9210: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
9220: 20 6f 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74   object associat
9230: 65 64 20 77 69 74 68 20 61 20 70 61 72 74 69 63  ed with a partic
9240: 75 6c 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a  ular database.**
9250: 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65   connection.  Se
9260: 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  e the [sqlite3_f
9270: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64  ile_control()] d
9280: 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
9290: 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69  .** additional i
92a0: 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
92b0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
92c0: 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45  CNTL_SYNC_OMITTE
92d0: 44 5d 5d 0a 2a 2a 20 4e 6f 20 6c 6f 6e 67 65 72  D]].** No longer
92e0: 20 69 6e 20 75 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c   in use..**.** <
92f0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
9300: 4c 5f 53 59 4e 43 5d 5d 0a 2a 2a 20 54 68 65 20  L_SYNC]].** The 
9310: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59  [SQLITE_FCNTL_SY
9320: 4e 43 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  NC] opcode is ge
9330: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
9340: 6c 79 20 62 79 20 53 51 4c 69 74 65 20 61 6e 64  ly by SQLite and
9350: 0a 2a 2a 20 73 65 6e 74 20 74 6f 20 74 68 65 20  .** sent to the 
9360: 56 46 53 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  VFS immediately 
9370: 62 65 66 6f 72 65 20 74 68 65 20 78 53 79 6e 63  before the xSync
9380: 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b   method is invok
9390: 65 64 20 6f 6e 20 61 0a 2a 2a 20 64 61 74 61 62  ed on a.** datab
93a0: 61 73 65 20 66 69 6c 65 20 64 65 73 63 72 69 70  ase file descrip
93b0: 74 6f 72 2e 20 4f 72 2c 20 69 66 20 74 68 65 20  tor. Or, if the 
93c0: 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73 20  xSync method is 
93d0: 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 0a 2a 2a 20  not invoked .** 
93e0: 62 65 63 61 75 73 65 20 74 68 65 20 75 73 65 72  because the user
93f0: 20 68 61 73 20 63 6f 6e 66 69 67 75 72 65 64 20   has configured 
9400: 53 51 4c 69 74 65 20 77 69 74 68 20 0a 2a 2a 20  SQLite with .** 
9410: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
9420: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
9430: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 74  chronous=OFF] it
9440: 20 69 73 20 69 6e 76 6f 6b 65 64 20 69 6e 20 70   is invoked in p
9450: 6c 61 63 65 20 0a 2a 2a 20 6f 66 20 74 68 65 20  lace .** of the 
9460: 78 53 79 6e 63 20 6d 65 74 68 6f 64 2e 20 49 6e  xSync method. In
9470: 20 6d 6f 73 74 20 63 61 73 65 73 2c 20 74 68 65   most cases, the
9480: 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d 65 6e   pointer argumen
9490: 74 20 70 61 73 73 65 64 20 77 69 74 68 0a 2a 2a  t passed with.**
94a0: 20 74 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72   this file-contr
94b0: 6f 6c 20 69 73 20 4e 55 4c 4c 2e 20 48 6f 77 65  ol is NULL. Howe
94c0: 76 65 72 2c 20 69 66 20 74 68 65 20 64 61 74 61  ver, if the data
94d0: 62 61 73 65 20 66 69 6c 65 20 69 73 20 62 65 69  base file is bei
94e0: 6e 67 20 73 79 6e 63 65 64 0a 2a 2a 20 61 73 20  ng synced.** as 
94f0: 70 61 72 74 20 6f 66 20 61 20 6d 75 6c 74 69 2d  part of a multi-
9500: 64 61 74 61 62 61 73 65 20 63 6f 6d 6d 69 74 2c  database commit,
9510: 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 70 6f   the argument po
9520: 69 6e 74 73 20 74 6f 20 61 20 6e 75 6c 2d 74 65  ints to a nul-te
9530: 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
9540: 6e 67 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ng containing th
9550: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 73 20 6d  e transactions m
9560: 61 73 74 65 72 2d 6a 6f 75 72 6e 61 6c 20 66 69  aster-journal fi
9570: 6c 65 20 6e 61 6d 65 2e 20 56 46 53 65 73 20 74  le name. VFSes t
9580: 68 61 74 20 0a 2a 2a 20 64 6f 20 6e 6f 74 20 6e  hat .** do not n
9590: 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20  eed this signal 
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
95d0: 20 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74 20   .** should not 
95e0: 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f 66 69  call [sqlite3_fi
95f0: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69  le_control()] wi
9600: 74 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61  th this opcode a
9610: 73 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 0a  s doing so may .
9620: 2a 2a 20 64 69 73 72 75 70 74 20 74 68 65 20 6f  ** disrupt the o
9630: 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  peration of the 
9640: 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65  specialized VFSe
9650: 73 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72  s that do requir
9660: 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c  e it.  .**.** <l
9670: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
9680: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
9690: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
96a0: 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50  E_FCNTL_COMMIT_P
96b0: 48 41 53 45 54 57 4f 5d 20 6f 70 63 6f 64 65 20  HASETWO] opcode 
96c0: 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e 74  is generated int
96d0: 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69 74  ernally by SQLit
96e0: 65 0a 2a 2a 20 61 6e 64 20 73 65 6e 74 20 74 6f  e.** and sent to
96f0: 20 74 68 65 20 56 46 53 20 61 66 74 65 72 20 61   the VFS after a
9700: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 68 61 73   transaction has
9710: 20 62 65 65 6e 20 63 6f 6d 6d 69 74 74 65 64 20   been committed 
9720: 69 6d 6d 65 64 69 61 74 65 6c 79 0a 2a 2a 20 62  immediately.** b
9730: 75 74 20 62 65 66 6f 72 65 20 74 68 65 20 64 61  ut before the da
9740: 74 61 62 61 73 65 20 69 73 20 75 6e 6c 6f 63 6b  tabase is unlock
9750: 65 64 2e 20 56 46 53 65 73 20 74 68 61 74 20 64  ed. VFSes that d
9760: 6f 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20  o not need this 
9770: 73 69 67 6e 61 6c 0a 2a 2a 20 73 68 6f 75 6c 64  signal.** should
9780: 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65   silently ignore
9790: 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41 70   this opcode. Ap
97a0: 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c  plications shoul
97b0: 64 20 6e 6f 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73  d not call.** [s
97c0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
97d0: 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73  rol()] with this
97e0: 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67   opcode as doing
97f0: 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20   so may disrupt 
9800: 74 68 65 20 0a 2a 2a 20 6f 70 65 72 61 74 69 6f  the .** operatio
9810: 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69 61 6c  n of the special
9820: 69 7a 65 64 20 56 46 53 65 73 20 74 68 61 74 20  ized VFSes that 
9830: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
9840: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
9850: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
9860: 41 56 5f 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54  AV_RETRY]].** ^T
9870: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9880: 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d  _WIN32_AV_RETRY]
9890: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
98a0: 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 61 75 74  to configure aut
98b0: 6f 6d 61 74 69 63 0a 2a 2a 20 72 65 74 72 79 20  omatic.** retry 
98c0: 63 6f 75 6e 74 73 20 61 6e 64 20 69 6e 74 65 72  counts and inter
98d0: 76 61 6c 73 20 66 6f 72 20 63 65 72 74 61 69 6e  vals for certain
98e0: 20 64 69 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74   disk I/O operat
98f0: 69 6f 6e 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  ions for the.** 
9900: 77 69 6e 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e  windows [VFS] in
9910: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
9920: 65 20 72 6f 62 75 73 74 6e 65 73 73 20 69 6e 20  e robustness in 
9930: 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 0a  the presence of.
9940: 2a 2a 20 61 6e 74 69 2d 76 69 72 75 73 20 70 72  ** anti-virus pr
9950: 6f 67 72 61 6d 73 2e 20 20 42 79 20 64 65 66 61  ograms.  By defa
9960: 75 6c 74 2c 20 74 68 65 20 77 69 6e 64 6f 77 73  ult, the windows
9970: 20 56 46 53 20 77 69 6c 6c 20 72 65 74 72 79 20   VFS will retry 
9980: 66 69 6c 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69  file read,.** fi
9990: 6c 65 20 77 72 69 74 65 2c 20 61 6e 64 20 66 69  le write, and fi
99a0: 6c 65 20 64 65 6c 65 74 65 20 6f 70 65 72 61 74  le delete operat
99b0: 69 6f 6e 73 20 75 70 20 74 6f 20 31 30 20 74 69  ions up to 10 ti
99c0: 6d 65 73 2c 20 77 69 74 68 20 61 20 64 65 6c 61  mes, with a dela
99d0: 79 0a 2a 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69  y.** of 25 milli
99e0: 73 65 63 6f 6e 64 73 20 62 65 66 6f 72 65 20 74  seconds before t
99f0: 68 65 20 66 69 72 73 74 20 72 65 74 72 79 20 61  he first retry a
9a00: 6e 64 20 77 69 74 68 20 74 68 65 20 64 65 6c 61  nd with the dela
9a10: 79 20 69 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20  y increasing.** 
9a20: 62 79 20 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c  by an additional
9a30: 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   25 milliseconds
9a40: 20 77 69 74 68 20 65 61 63 68 20 73 75 62 73 65   with each subse
9a50: 71 75 65 6e 74 20 72 65 74 72 79 2e 20 20 54 68  quent retry.  Th
9a60: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c  is.** opcode all
9a70: 6f 77 73 20 74 68 65 73 65 20 74 77 6f 20 76 61  ows these two va
9a80: 6c 75 65 73 20 28 31 30 20 72 65 74 72 69 65 73  lues (10 retries
9a90: 20 61 6e 64 20 32 35 20 6d 69 6c 6c 69 73 65 63   and 25 millisec
9aa0: 6f 6e 64 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a  onds of delay).*
9ab0: 2a 20 74 6f 20 62 65 20 61 64 6a 75 73 74 65 64  * to be adjusted
9ac0: 2e 20 20 54 68 65 20 76 61 6c 75 65 73 20 61 72  .  The values ar
9ad0: 65 20 63 68 61 6e 67 65 64 20 66 6f 72 20 61 6c  e changed for al
9ae0: 6c 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  l database conne
9af0: 63 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e  ctions.** within
9b00: 20 74 68 65 20 73 61 6d 65 20 70 72 6f 63 65 73   the same proces
9b10: 73 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74  s.  The argument
9b20: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
9b30: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f   an array of two
9b40: 0a 2a 2a 20 69 6e 74 65 67 65 72 73 20 77 68 65  .** integers whe
9b50: 72 65 20 74 68 65 20 66 69 72 73 74 20 69 6e 74  re the first int
9b60: 65 67 65 72 20 69 20 74 68 65 20 6e 65 77 20 72  eger i the new r
9b70: 65 74 72 79 20 63 6f 75 6e 74 20 61 6e 64 20 74  etry count and t
9b80: 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74  he second.** int
9b90: 65 67 65 72 20 69 73 20 74 68 65 20 64 65 6c 61  eger is the dela
9ba0: 79 2e 20 20 49 66 20 65 69 74 68 65 72 20 69 6e  y.  If either in
9bb0: 74 65 67 65 72 20 69 73 20 6e 65 67 61 74 69 76  teger is negativ
9bc0: 65 2c 20 74 68 65 6e 20 74 68 65 20 73 65 74 74  e, then the sett
9bd0: 69 6e 67 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68  ing.** is not ch
9be0: 61 6e 67 65 64 20 62 75 74 20 69 6e 73 74 65 61  anged but instea
9bf0: 64 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75  d the prior valu
9c00: 65 20 6f 66 20 74 68 61 74 20 73 65 74 74 69 6e  e of that settin
9c10: 67 20 69 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20  g is written.** 
9c20: 69 6e 74 6f 20 74 68 65 20 61 72 72 61 79 20 65  into the array e
9c30: 6e 74 72 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74  ntry, allowing t
9c40: 68 65 20 63 75 72 72 65 6e 74 20 72 65 74 72 79  he current retry
9c50: 20 73 65 74 74 69 6e 67 73 20 74 6f 20 62 65 0a   settings to be.
9c60: 2a 2a 20 69 6e 74 65 72 72 6f 67 61 74 65 64 2e  ** interrogated.
9c70: 20 20 54 68 65 20 7a 44 62 4e 61 6d 65 20 70 61    The zDbName pa
9c80: 72 61 6d 65 74 65 72 20 69 73 20 69 67 6e 6f 72  rameter is ignor
9c90: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  ed..**.** <li>[[
9ca0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52  SQLITE_FCNTL_PER
9cb0: 53 49 53 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54  SIST_WAL]].** ^T
9cc0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
9cd0: 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70  _PERSIST_WAL] op
9ce0: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
9cf0: 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68 65  set or query the
9d00: 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20 5b  .** persistent [
9d10: 57 41 4c 20 7c 20 57 72 69 74 65 20 41 68 65 61  WAL | Write Ahea
9d20: 64 20 4c 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20  d Log] setting. 
9d30: 20 42 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65   By default, the
9d40: 20 61 75 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72   auxiliary.** wr
9d50: 69 74 65 20 61 68 65 61 64 20 6c 6f 67 20 61 6e  ite ahead log an
9d60: 64 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20  d shared memory 
9d70: 66 69 6c 65 73 20 75 73 65 64 20 66 6f 72 20 74  files used for t
9d80: 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
9d90: 6f 6c 0a 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61  ol.** are automa
9da0: 74 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20  tically deleted 
9db0: 77 68 65 6e 20 74 68 65 20 6c 61 74 65 73 74 20  when the latest 
9dc0: 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68  connection to th
9dd0: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c  e database.** cl
9de0: 6f 73 65 73 2e 20 20 53 65 74 74 69 6e 67 20 70  oses.  Setting p
9df0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9e00: 64 65 20 63 61 75 73 65 73 20 74 68 6f 73 65 20  de causes those 
9e10: 66 69 6c 65 73 20 74 6f 20 70 65 72 73 69 73 74  files to persist
9e20: 20 61 66 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e   after.** close.
9e30: 20 20 50 65 72 73 69 73 74 69 6e 67 20 74 68 65    Persisting the
9e40: 20 66 69 6c 65 73 20 69 73 20 75 73 65 66 75 6c   files is useful
9e50: 20 77 68 65 6e 20 6f 74 68 65 72 20 70 72 6f 63   when other proc
9e60: 65 73 73 65 73 20 74 68 61 74 20 64 6f 20 6e 6f  esses that do no
9e70: 74 0a 2a 2a 20 68 61 76 65 20 77 72 69 74 65 20  t.** have write 
9e80: 70 65 72 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68  permission on th
9e90: 65 20 64 69 72 65 63 74 6f 72 79 20 63 6f 6e 74  e directory cont
9ea0: 61 69 6e 69 6e 67 20 74 68 65 20 64 61 74 61 62  aining the datab
9eb0: 61 73 65 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a  ase file want.**
9ec0: 20 74 6f 20 72 65 61 64 20 74 68 65 20 64 61 74   to read the dat
9ed0: 61 62 61 73 65 20 66 69 6c 65 2c 20 61 73 20 74  abase file, as t
9ee0: 68 65 20 57 41 4c 20 61 6e 64 20 73 68 61 72 65  he WAL and share
9ef0: 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d  d memory files m
9f00: 75 73 74 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20  ust exist.** in 
9f10: 6f 72 64 65 72 20 66 6f 72 20 74 68 65 20 64 61  order for the da
9f20: 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 61  tabase to be rea
9f30: 64 61 62 6c 65 2e 20 20 54 68 65 20 66 6f 75 72  dable.  The four
9f40: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  th parameter to.
9f50: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  ** [sqlite3_file
9f60: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20  _control()] for 
9f70: 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f 75  this opcode shou
9f80: 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20  ld be a pointer 
9f90: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a  to an integer..*
9fa0: 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20 69  * That integer i
9fb0: 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 70  s 0 to disable p
9fc0: 65 72 73 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f  ersistent WAL mo
9fd0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
9fe0: 65 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20  e persistent.** 
9ff0: 57 41 4c 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  WAL mode.  If th
a000: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a010: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a020: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a030: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20   current.** WAL 
a040: 70 65 72 73 69 73 74 65 6e 63 65 20 73 65 74 74  persistence sett
a050: 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ing..**.** <li>[
a060: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f  [SQLITE_FCNTL_PO
a070: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
a080: 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  E]].** ^The [SQL
a090: 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53  ITE_FCNTL_POWERS
a0a0: 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f  AFE_OVERWRITE] o
a0b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
a0c0: 20 73 65 74 20 6f 72 20 71 75 65 72 79 20 74 68   set or query th
a0d0: 65 0a 2a 2a 20 70 65 72 73 69 73 74 65 6e 74 20  e.** persistent 
a0e0: 22 70 6f 77 65 72 73 61 66 65 2d 6f 76 65 72 77  "powersafe-overw
a0f0: 72 69 74 65 22 20 6f 72 20 22 50 53 4f 57 22 20  rite" or "PSOW" 
a100: 73 65 74 74 69 6e 67 2e 20 20 54 68 65 20 50 53  setting.  The PS
a110: 4f 57 20 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65  OW setting.** de
a120: 74 65 72 6d 69 6e 65 73 20 74 68 65 20 5b 53 51  termines the [SQ
a130: 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52  LITE_IOCAP_POWER
a140: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 20  SAFE_OVERWRITE] 
a150: 62 69 74 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44  bit of the.** xD
a160: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
a170: 74 69 63 73 20 6d 65 74 68 6f 64 73 2e 20 54 68  tics methods. Th
a180: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
a190: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
a1a0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
a1b0: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
a1c0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
a1d0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
a1e0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
a1f0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
a200: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a210: 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f 20 65 6e   mode or 1 to en
a220: 61 62 6c 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65  able zero-damage
a230: 0a 2a 2a 20 6d 6f 64 65 2e 20 20 49 66 20 74 68  .** mode.  If th
a240: 65 20 69 6e 74 65 67 65 72 20 69 73 20 2d 31 2c  e integer is -1,
a250: 20 74 68 65 6e 20 69 74 20 69 73 20 6f 76 65 72   then it is over
a260: 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68 65  written with the
a270: 20 63 75 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f   current.** zero
a280: 2d 64 61 6d 61 67 65 20 6d 6f 64 65 20 73 65 74  -damage mode set
a290: 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  ting..**.** <li>
a2a0: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f  [[SQLITE_FCNTL_O
a2b0: 56 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54  VERWRITE]].** ^T
a2c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
a2d0: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
a2e0: 64 65 20 69 73 20 69 6e 76 6f 6b 65 64 20 62 79  de is invoked by
a2f0: 20 53 51 4c 69 74 65 20 61 66 74 65 72 20 6f 70   SQLite after op
a300: 65 6e 69 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65  ening.** a write
a310: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20   transaction to 
a320: 69 6e 64 69 63 61 74 65 20 74 68 61 74 2c 20 75  indicate that, u
a330: 6e 6c 65 73 73 20 69 74 20 69 73 20 72 6f 6c 6c  nless it is roll
a340: 65 64 20 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65  ed back for some
a350: 0a 2a 2a 20 72 65 61 73 6f 6e 2c 20 74 68 65 20  .** reason, the 
a360: 65 6e 74 69 72 65 20 64 61 74 61 62 61 73 65 20  entire database 
a370: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 6f 76 65  file will be ove
a380: 72 77 72 69 74 74 65 6e 20 62 79 20 74 68 65 20  rwritten by the 
a390: 63 75 72 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e  current .** tran
a3a0: 73 61 63 74 69 6f 6e 2e 20 54 68 69 73 20 69 73  saction. This is
a3b0: 20 75 73 65 64 20 62 79 20 56 41 43 55 55 4d 20   used by VACUUM 
a3c0: 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
a3d0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a3e0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a  CNTL_VFSNAME]].*
a3f0: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
a400: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70  CNTL_VFSNAME] op
a410: 63 6f 64 65 20 63 61 6e 20 62 65 20 75 73 65 64  code can be used
a420: 20 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6e   to obtain the n
a430: 61 6d 65 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b  ames of.** all [
a440: 56 46 53 65 73 5d 20 69 6e 20 74 68 65 20 56 46  VFSes] in the VF
a450: 53 20 73 74 61 63 6b 2e 20 20 54 68 65 20 6e 61  S stack.  The na
a460: 6d 65 73 20 61 72 65 20 6f 66 20 61 6c 6c 20 56  mes are of all V
a470: 46 53 20 73 68 69 6d 73 20 61 6e 64 20 74 68 65  FS shims and the
a480: 0a 2a 2a 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d  .** final bottom
a490: 2d 6c 65 76 65 6c 20 56 46 53 20 61 72 65 20 77  -level VFS are w
a4a0: 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f  ritten into memo
a4b0: 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  ry obtained from
a4c0: 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61   .** [sqlite3_ma
a4d0: 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 74 68 65 20  lloc()] and the 
a4e0: 72 65 73 75 6c 74 20 69 73 20 73 74 6f 72 65 64  result is stored
a4f0: 20 69 6e 20 74 68 65 20 63 68 61 72 2a 20 76 61   in the char* va
a500: 72 69 61 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74  riable.** that t
a510: 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
a520: 74 65 72 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ter of [sqlite3_
a530: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
a540: 70 6f 69 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68  points to..** Th
a550: 65 20 63 61 6c 6c 65 72 20 69 73 20 72 65 73 70  e caller is resp
a560: 6f 6e 73 69 62 6c 65 20 66 6f 72 20 66 72 65 65  onsible for free
a570: 69 6e 67 20 74 68 65 20 6d 65 6d 6f 72 79 20 77  ing the memory w
a580: 68 65 6e 20 64 6f 6e 65 2e 20 20 41 73 20 77 69  hen done.  As wi
a590: 74 68 0a 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63  th.** all file-c
a5a0: 6f 6e 74 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20  ontrol actions, 
a5b0: 74 68 65 72 65 20 69 73 20 6e 6f 20 67 75 61 72  there is no guar
a5c0: 61 6e 74 65 65 20 74 68 61 74 20 74 68 69 73 20  antee that this 
a5d0: 77 69 6c 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a  will actually.**
a5e0: 20 64 6f 20 61 6e 79 74 68 69 6e 67 2e 20 20 43   do anything.  C
a5f0: 61 6c 6c 65 72 73 20 73 68 6f 75 6c 64 20 69 6e  allers should in
a600: 69 74 69 61 6c 69 7a 65 20 74 68 65 20 63 68 61  itialize the cha
a610: 72 2a 20 76 61 72 69 61 62 6c 65 20 74 6f 20 61  r* variable to a
a620: 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72   NULL.** pointer
a630: 20 69 6e 20 63 61 73 65 20 74 68 69 73 20 66 69   in case this fi
a640: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f  le-control is no
a650: 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20  t implemented.  
a660: 54 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f  This file-contro
a670: 6c 0a 2a 2a 20 69 73 20 69 6e 74 65 6e 64 65 64  l.** is intended
a680: 20 66 6f 72 20 64 69 61 67 6e 6f 73 74 69 63 20   for diagnostic 
a690: 75 73 65 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20  use only..**.** 
a6a0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
a6b0: 54 4c 5f 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e  TL_PRAGMA]].** ^
a6c0: 57 68 65 6e 65 76 65 72 20 61 20 5b 50 52 41 47  Whenever a [PRAG
a6d0: 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73  MA] statement is
a6e0: 20 70 61 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c   parsed, an [SQL
a6f0: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a700: 5d 20 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  ] .** file contr
a710: 6f 6c 20 69 73 20 73 65 6e 74 20 74 6f 20 74 68  ol is sent to th
a720: 65 20 6f 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f  e open [sqlite3_
a730: 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72  file] object cor
a740: 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f  responding.** to
a750: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
a760: 6c 65 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  le to which the 
a770: 70 72 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74  pragma statement
a780: 20 72 65 66 65 72 73 2e 20 5e 54 68 65 20 61 72   refers. ^The ar
a790: 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65  gument.** to the
a7a0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50   [SQLITE_FCNTL_P
a7b0: 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74  RAGMA] file cont
a7c0: 72 6f 6c 20 69 73 20 61 6e 20 61 72 72 61 79 20  rol is an array 
a7d0: 6f 66 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74  of.** pointers t
a7e0: 6f 20 73 74 72 69 6e 67 73 20 28 63 68 61 72 2a  o strings (char*
a7f0: 2a 29 20 69 6e 20 77 68 69 63 68 20 74 68 65 20  *) in which the 
a800: 73 65 63 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f  second element o
a810: 66 20 74 68 65 20 61 72 72 61 79 0a 2a 2a 20 69  f the array.** i
a820: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
a830: 65 20 70 72 61 67 6d 61 20 61 6e 64 20 74 68 65  e pragma and the
a840: 20 74 68 69 72 64 20 65 6c 65 6d 65 6e 74 20 69   third element i
a850: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
a860: 6f 20 74 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20  o the.** pragma 
a870: 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 70  or NULL if the p
a880: 72 61 67 6d 61 20 68 61 73 20 6e 6f 20 61 72 67  ragma has no arg
a890: 75 6d 65 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e  ument.  ^The han
a8a0: 64 6c 65 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b  dler for an.** [
a8b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41  SQLITE_FCNTL_PRA
a8c0: 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  GMA] file contro
a8d0: 6c 20 63 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79  l can optionally
a8e0: 20 6d 61 6b 65 20 74 68 65 20 66 69 72 73 74 20   make the first 
a8f0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68  element.** of th
a900: 65 20 63 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e  e char** argumen
a910: 74 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72  t point to a str
a920: 69 6e 67 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ing obtained fro
a930: 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  m [sqlite3_mprin
a940: 74 66 28 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20  tf()].** or the 
a950: 65 71 75 69 76 61 6c 65 6e 74 20 61 6e 64 20 74  equivalent and t
a960: 68 61 74 20 73 74 72 69 6e 67 20 77 69 6c 6c 20  hat string will 
a970: 62 65 63 6f 6d 65 20 74 68 65 20 72 65 73 75 6c  become the resul
a980: 74 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20  t of the pragma 
a990: 6f 72 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  or.** the error 
a9a0: 6d 65 73 73 61 67 65 20 69 66 20 74 68 65 20 70  message if the p
a9b0: 72 61 67 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66  ragma fails. ^If
a9c0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
a9d0: 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69  FCNTL_PRAGMA] fi
a9e0: 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72  le control retur
a9f0: 6e 73 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ns [SQLITE_NOTFO
aa00: 55 4e 44 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61  UND], then norma
aa10: 6c 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70  l .** [PRAGMA] p
aa20: 72 6f 63 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e  rocessing contin
aa30: 75 65 73 2e 20 20 5e 49 66 20 74 68 65 20 5b 53  ues.  ^If the [S
aa40: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
aa50: 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74  MA].** file cont
aa60: 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  rol returns [SQL
aa70: 49 54 45 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68  ITE_OK], then th
aa80: 65 20 70 61 72 73 65 72 20 61 73 73 75 6d 65 73  e parser assumes
aa90: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 56 46 53   that the.** VFS
aaa0: 20 68 61 73 20 68 61 6e 64 6c 65 64 20 74 68 65   has handled the
aab0: 20 50 52 41 47 4d 41 20 69 74 73 65 6c 66 20 61   PRAGMA itself a
aac0: 6e 64 20 74 68 65 20 70 61 72 73 65 72 20 67 65  nd the parser ge
aad0: 6e 65 72 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a  nerates a no-op.
aae0: 2a 2a 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ** prepared stat
aaf0: 65 6d 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20  ement.  ^If the 
ab00: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
ab10: 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72  AGMA] file contr
ab20: 6f 6c 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e  ol returns.** an
ab30: 79 20 72 65 73 75 6c 74 20 63 6f 64 65 20 6f 74  y result code ot
ab40: 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45  her than [SQLITE
ab50: 5f 4f 4b 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  _OK] or [SQLITE_
ab60: 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20  NOTFOUND], that 
ab70: 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68  means.** that th
ab80: 65 20 56 46 53 20 65 6e 63 6f 75 6e 74 65 72 65  e VFS encountere
ab90: 64 20 61 6e 20 65 72 72 6f 72 20 77 68 69 6c 65  d an error while
aba0: 20 68 61 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50   handling the [P
abb0: 52 41 47 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a  RAGMA] and the.*
abc0: 2a 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66  * compilation of
abd0: 20 74 68 65 20 50 52 41 47 4d 41 20 66 61 69 6c   the PRAGMA fail
abe0: 73 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  s with an error.
abf0: 20 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46    ^The [SQLITE_F
ac00: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20  CNTL_PRAGMA].** 
ac10: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63  file control occ
ac20: 75 72 73 20 61 74 20 74 68 65 20 62 65 67 69 6e  urs at the begin
ac30: 6e 69 6e 67 20 6f 66 20 70 72 61 67 6d 61 20 73  ning of pragma s
ac40: 74 61 74 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69  tatement analysi
ac50: 73 20 61 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69  s and so.** it i
ac60: 73 20 61 62 6c 65 20 74 6f 20 6f 76 65 72 72 69  s able to overri
ac70: 64 65 20 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41  de built-in [PRA
ac80: 47 4d 41 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e  GMA] statements.
ac90: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
aca0: 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41  ITE_FCNTL_BUSYHA
acb0: 4e 44 4c 45 52 5d 5d 0a 2a 2a 20 5e 54 68 65 20  NDLER]].** ^The 
acc0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55  [SQLITE_FCNTL_BU
acd0: 53 59 48 41 4e 44 4c 45 52 5d 0a 2a 2a 20 66 69  SYHANDLER].** fi
ace0: 6c 65 2d 63 6f 6e 74 72 6f 6c 20 6d 61 79 20 62  le-control may b
acf0: 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c  e invoked by SQL
ad00: 69 74 65 20 6f 6e 20 74 68 65 20 64 61 74 61 62  ite on the datab
ad10: 61 73 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 0a  ase file handle.
ad20: 2a 2a 20 73 68 6f 72 74 6c 79 20 61 66 74 65 72  ** shortly after
ad30: 20 69 74 20 69 73 20 6f 70 65 6e 65 64 20 69 6e   it is opened in
ad40: 20 6f 72 64 65 72 20 74 6f 20 70 72 6f 76 69 64   order to provid
ad50: 65 20 61 20 63 75 73 74 6f 6d 20 56 46 53 20 77  e a custom VFS w
ad60: 69 74 68 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f  ith access.** to
ad70: 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73   the connections
ad80: 20 62 75 73 79 2d 68 61 6e 64 6c 65 72 20 63 61   busy-handler ca
ad90: 6c 6c 62 61 63 6b 2e 20 54 68 65 20 61 72 67 75  llback. The argu
ada0: 6d 65 6e 74 20 69 73 20 6f 66 20 74 79 70 65 20  ment is of type 
adb0: 28 76 6f 69 64 20 2a 2a 29 0a 2a 2a 20 2d 20 61  (void **).** - a
adc0: 6e 20 61 72 72 61 79 20 6f 66 20 74 77 6f 20 28  n array of two (
add0: 76 6f 69 64 20 2a 29 20 76 61 6c 75 65 73 2e 20  void *) values. 
ade0: 54 68 65 20 66 69 72 73 74 20 28 76 6f 69 64 20  The first (void 
adf0: 2a 29 20 61 63 74 75 61 6c 6c 79 20 70 6f 69 6e  *) actually poin
ae00: 74 73 0a 2a 2a 20 74 6f 20 61 20 66 75 6e 63 74  ts.** to a funct
ae10: 69 6f 6e 20 6f 66 20 74 79 70 65 20 28 69 6e 74  ion of type (int
ae20: 20 28 2a 29 28 76 6f 69 64 20 2a 29 29 2e 20 49   (*)(void *)). I
ae30: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 76 6f 6b  n order to invok
ae40: 65 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  e the connection
ae50: 73 0a 2a 2a 20 62 75 73 79 2d 68 61 6e 64 6c 65  s.** busy-handle
ae60: 72 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  r, this function
ae70: 20 73 68 6f 75 6c 64 20 62 65 20 69 6e 76 6f 6b   should be invok
ae80: 65 64 20 77 69 74 68 20 74 68 65 20 73 65 63 6f  ed with the seco
ae90: 6e 64 20 28 76 6f 69 64 20 2a 29 20 69 6e 0a 2a  nd (void *) in.*
aea0: 2a 20 74 68 65 20 61 72 72 61 79 20 61 73 20 74  * the array as t
aeb0: 68 65 20 6f 6e 6c 79 20 61 72 67 75 6d 65 6e 74  he only argument
aec0: 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73 20  . If it returns 
aed0: 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74  non-zero, then t
aee0: 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20  he operation.** 
aef0: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 72 69 65  should be retrie
af00: 64 2e 20 49 66 20 69 74 20 72 65 74 75 72 6e 73  d. If it returns
af10: 20 7a 65 72 6f 2c 20 74 68 65 20 63 75 73 74 6f   zero, the custo
af20: 6d 20 56 46 53 20 73 68 6f 75 6c 64 20 61 62 61  m VFS should aba
af30: 6e 64 6f 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  ndon the.** curr
af40: 65 6e 74 20 6f 70 65 72 61 74 69 6f 6e 2e 0a 2a  ent operation..*
af50: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
af60: 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45  E_FCNTL_TEMPFILE
af70: 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 41 70 70 6c 69  NAME]].** ^Appli
af80: 63 61 74 69 6f 6e 20 63 61 6e 20 69 6e 76 6f 6b  cation can invok
af90: 65 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  e the [SQLITE_FC
afa0: 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45  NTL_TEMPFILENAME
afb0: 5d 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  ] file-control.*
afc0: 2a 20 74 6f 20 68 61 76 65 20 53 51 4c 69 74 65  * to have SQLite
afd0: 20 67 65 6e 65 72 61 74 65 20 61 0a 2a 2a 20 74   generate a.** t
afe0: 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e 61 6d  emporary filenam
aff0: 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
b000: 20 61 6c 67 6f 72 69 74 68 6d 20 74 68 61 74 20   algorithm that 
b010: 69 73 20 66 6f 6c 6c 6f 77 65 64 20 74 6f 20 67  is followed to g
b020: 65 6e 65 72 61 74 65 0a 2a 2a 20 74 65 6d 70 6f  enerate.** tempo
b030: 72 61 72 79 20 66 69 6c 65 6e 61 6d 65 73 20 66  rary filenames f
b040: 6f 72 20 54 45 4d 50 20 74 61 62 6c 65 73 20 61  or TEMP tables a
b050: 6e 64 20 6f 74 68 65 72 20 69 6e 74 65 72 6e 61  nd other interna
b060: 6c 20 75 73 65 73 2e 20 20 54 68 65 0a 2a 2a 20  l uses.  The.** 
b070: 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20  argument should 
b080: 62 65 20 61 20 63 68 61 72 2a 2a 20 77 68 69 63  be a char** whic
b090: 68 20 77 69 6c 6c 20 62 65 20 66 69 6c 6c 65 64  h will be filled
b0a0: 20 77 69 74 68 20 74 68 65 20 66 69 6c 65 6e 61   with the filena
b0b0: 6d 65 0a 2a 2a 20 77 72 69 74 74 65 6e 20 69 6e  me.** written in
b0c0: 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
b0d0: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
b0e0: 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 20 54 68 65  _malloc()].  The
b0f0: 20 63 61 6c 6c 65 72 20 73 68 6f 75 6c 64 0a 2a   caller should.*
b100: 2a 20 69 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65  * invoke [sqlite
b110: 33 5f 66 72 65 65 28 29 5d 20 6f 6e 20 74 68 65  3_free()] on the
b120: 20 72 65 73 75 6c 74 20 74 6f 20 61 76 6f 69 64   result to avoid
b130: 20 61 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 2e 0a   a memory leak..
b140: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b150: 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49  TE_FCNTL_MMAP_SI
b160: 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ZE]].** The [SQL
b170: 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53  ITE_FCNTL_MMAP_S
b180: 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  IZE] file contro
b190: 6c 20 69 73 20 75 73 65 64 20 74 6f 20 71 75 65  l is used to que
b1a0: 72 79 20 6f 72 20 73 65 74 20 74 68 65 0a 2a 2a  ry or set the.**
b1b0: 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
b1c0: 6f 66 20 62 79 74 65 73 20 74 68 61 74 20 77 69  of bytes that wi
b1d0: 6c 6c 20 62 65 20 75 73 65 64 20 66 6f 72 20 6d  ll be used for m
b1e0: 65 6d 6f 72 79 2d 6d 61 70 70 65 64 20 49 2f 4f  emory-mapped I/O
b1f0: 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65 6e  ..** The argumen
b200: 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  t is a pointer t
b210: 6f 20 61 20 76 61 6c 75 65 20 6f 66 20 74 79 70  o a value of typ
b220: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  e sqlite3_int64 
b230: 74 68 61 74 0a 2a 2a 20 69 73 20 61 6e 20 61 64  that.** is an ad
b240: 76 69 73 6f 72 79 20 6d 61 78 69 6d 75 6d 20 6e  visory maximum n
b250: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
b260: 6e 20 74 68 65 20 66 69 6c 65 20 74 6f 20 6d 65  n the file to me
b270: 6d 6f 72 79 20 6d 61 70 2e 20 20 54 68 65 0a 2a  mory map.  The.*
b280: 2a 20 70 6f 69 6e 74 65 72 20 69 73 20 6f 76 65  * pointer is ove
b290: 72 77 72 69 74 74 65 6e 20 77 69 74 68 20 74 68  rwritten with th
b2a0: 65 20 6f 6c 64 20 76 61 6c 75 65 2e 20 20 54 68  e old value.  Th
b2b0: 65 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  e limit is not c
b2c0: 68 61 6e 67 65 64 20 69 66 0a 2a 2a 20 74 68 65  hanged if.** the
b2d0: 20 76 61 6c 75 65 20 6f 72 69 67 69 6e 61 6c 6c   value originall
b2e0: 79 20 70 6f 69 6e 74 65 64 20 74 6f 20 69 73 20  y pointed to is 
b2f0: 6e 65 67 61 74 69 76 65 2c 20 61 6e 64 20 73 6f  negative, and so
b300: 20 74 68 65 20 63 75 72 72 65 6e 74 20 6c 69 6d   the current lim
b310: 69 74 20 0a 2a 2a 20 63 61 6e 20 62 65 20 71 75  it .** can be qu
b320: 65 72 69 65 64 20 62 79 20 70 61 73 73 69 6e 67  eried by passing
b330: 20 69 6e 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   in a pointer to
b340: 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
b350: 65 72 2e 20 20 54 68 69 73 0a 2a 2a 20 66 69 6c  er.  This.** fil
b360: 65 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65  e-control is use
b370: 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f 20  d internally to 
b380: 69 6d 70 6c 65 6d 65 6e 74 20 5b 50 52 41 47 4d  implement [PRAGM
b390: 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 2e 0a 2a 2a  A mmap_size]..**
b3a0: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
b3b0: 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 5d 0a 2a  _FCNTL_TRACE]].*
b3c0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
b3d0: 4e 54 4c 5f 54 52 41 43 45 5d 20 66 69 6c 65 20  NTL_TRACE] file 
b3e0: 63 6f 6e 74 72 6f 6c 20 70 72 6f 76 69 64 65 73  control provides
b3f0: 20 61 64 76 69 73 6f 72 79 20 69 6e 66 6f 72 6d   advisory inform
b400: 61 74 69 6f 6e 0a 2a 2a 20 74 6f 20 74 68 65 20  ation.** to the 
b410: 56 46 53 20 61 62 6f 75 74 20 77 68 61 74 20 74  VFS about what t
b420: 68 65 20 68 69 67 68 65 72 20 6c 61 79 65 72 73  he higher layers
b430: 20 6f 66 20 74 68 65 20 53 51 4c 69 74 65 20 73   of the SQLite s
b440: 74 61 63 6b 20 61 72 65 20 64 6f 69 6e 67 2e 0a  tack are doing..
b450: 2a 2a 20 54 68 69 73 20 66 69 6c 65 20 63 6f 6e  ** This file con
b460: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 62 79 20  trol is used by 
b470: 73 6f 6d 65 20 56 46 53 20 61 63 74 69 76 69 74  some VFS activit
b480: 79 20 74 72 61 63 69 6e 67 20 5b 73 68 69 6d 73  y tracing [shims
b490: 5d 2e 0a 2a 2a 20 54 68 65 20 61 72 67 75 6d 65  ]..** The argume
b4a0: 6e 74 20 69 73 20 61 20 7a 65 72 6f 2d 74 65 72  nt is a zero-ter
b4b0: 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 2e 20  minated string. 
b4c0: 20 48 69 67 68 65 72 20 6c 61 79 65 72 73 20 69   Higher layers i
b4d0: 6e 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20  n the.** SQLite 
b4e0: 73 74 61 63 6b 20 6d 61 79 20 67 65 6e 65 72 61  stack may genera
b4f0: 74 65 20 69 6e 73 74 61 6e 63 65 73 20 6f 66 20  te instances of 
b500: 74 68 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f  this file contro
b510: 6c 20 69 66 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  l if.** the [SQL
b520: 49 54 45 5f 55 53 45 5f 46 43 4e 54 4c 5f 54 52  ITE_USE_FCNTL_TR
b530: 41 43 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ACE] compile-tim
b540: 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
b550: 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  led..**.** <li>[
b560: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41  [SQLITE_FCNTL_HA
b570: 53 5f 4d 4f 56 45 44 5d 5d 0a 2a 2a 20 54 68 65  S_MOVED]].** The
b580: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48   [SQLITE_FCNTL_H
b590: 41 53 5f 4d 4f 56 45 44 5d 20 66 69 6c 65 20 63  AS_MOVED] file c
b5a0: 6f 6e 74 72 6f 6c 20 69 6e 74 65 72 70 72 65 74  ontrol interpret
b5b0: 73 20 69 74 73 20 61 72 67 75 6d 65 6e 74 20 61  s its argument a
b5c0: 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74  s a.** pointer t
b5d0: 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 61 6e 64  o an integer and
b5e0: 20 69 74 20 77 72 69 74 65 73 20 61 20 62 6f 6f   it writes a boo
b5f0: 6c 65 61 6e 20 69 6e 74 6f 20 74 68 61 74 20 69  lean into that i
b600: 6e 74 65 67 65 72 20 64 65 70 65 6e 64 69 6e 67  nteger depending
b610: 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 6f  .** on whether o
b620: 72 20 6e 6f 74 20 74 68 65 20 66 69 6c 65 20 68  r not the file h
b630: 61 73 20 62 65 65 6e 20 72 65 6e 61 6d 65 64 2c  as been renamed,
b640: 20 6d 6f 76 65 64 2c 20 6f 72 20 64 65 6c 65 74   moved, or delet
b650: 65 64 20 73 69 6e 63 65 20 69 74 0a 2a 2a 20 77  ed since it.** w
b660: 61 73 20 66 69 72 73 74 20 6f 70 65 6e 65 64 2e  as first opened.
b670: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
b680: 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f  ITE_FCNTL_WIN32_
b690: 53 45 54 5f 48 41 4e 44 4c 45 5d 5d 0a 2a 2a 20  SET_HANDLE]].** 
b6a0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
b6b0: 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44  L_WIN32_SET_HAND
b6c0: 4c 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  LE] opcode is us
b6d0: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
b6e0: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
b6f0: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
b700: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
b710: 20 74 6f 20 73 77 61 70 20 74 68 65 20 66 69 6c   to swap the fil
b720: 65 20 68 61 6e 64 6c 65 20 77 69 74 68 20 74 68  e handle with th
b730: 65 20 6f 6e 65 0a 2a 2a 20 70 6f 69 6e 74 65 64  e one.** pointed
b740: 20 74 6f 20 62 79 20 74 68 65 20 70 41 72 67 20   to by the pArg 
b750: 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 69 73 20  argument.  This 
b760: 63 61 70 61 62 69 6c 69 74 79 20 69 73 20 75 73  capability is us
b770: 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
b780: 67 0a 2a 2a 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  g.** and only ne
b790: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
b7a0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
b7b0: 54 45 53 54 20 69 73 20 64 65 66 69 6e 65 64 2e  TEST is defined.
b7c0: 0a 2a 2a 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  .**.** </ul>.*/.
b7d0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7e0: 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 20  CNTL_LOCKSTATE  
b7f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23               1.#
b800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b810: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
b820: 59 46 49 4c 45 20 20 20 20 20 20 20 32 0a 23 64  YFILE       2.#d
b830: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b840: 54 4c 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TL_SET_LOCKPROXY
b850: 46 49 4c 45 20 20 20 20 20 20 20 33 0a 23 64 65  FILE       3.#de
b860: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b870: 4c 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  L_LAST_ERRNO    
b880: 20 20 20 20 20 20 20 20 20 20 34 0a 23 64 65 66            4.#def
b890: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b8a0: 5f 53 49 5a 45 5f 48 49 4e 54 20 20 20 20 20 20  _SIZE_HINT      
b8b0: 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
b8c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b8d0: 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20  CHUNK_SIZE      
b8e0: 20 20 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e          6.#defin
b8f0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46  e SQLITE_FCNTL_F
b900: 49 4c 45 5f 50 4f 49 4e 54 45 52 20 20 20 20 20  ILE_POINTER     
b910: 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
b920: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
b930: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 20  NC_OMITTED      
b940: 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20        8.#define 
b950: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b960: 33 32 5f 41 56 5f 52 45 54 52 59 20 20 20 20 20  32_AV_RETRY     
b970: 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53       9.#define S
b980: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
b990: 49 53 54 5f 57 41 4c 20 20 20 20 20 20 20 20 20  IST_WAL         
b9a0: 20 20 20 31 30 0a 23 64 65 66 69 6e 65 20 53 51     10.#define SQ
b9b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57  LITE_FCNTL_OVERW
b9c0: 52 49 54 45 20 20 20 20 20 20 20 20 20 20 20 20  RITE            
b9d0: 20 20 31 31 0a 23 64 65 66 69 6e 65 20 53 51 4c    11.#define SQL
b9e0: 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41 4d  ITE_FCNTL_VFSNAM
b9f0: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
ba00: 20 31 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   12.#define SQLI
ba10: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
ba20: 46 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20  FE_OVERWRITE    
ba30: 31 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  13.#define SQLIT
ba40: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 20 20  E_FCNTL_PRAGMA  
ba50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
ba60: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
ba70: 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c  _FCNTL_BUSYHANDL
ba80: 45 52 20 20 20 20 20 20 20 20 20 20 20 20 31 35  ER            15
ba90: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
baa0: 46 43 4e 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41  FCNTL_TEMPFILENA
bab0: 4d 45 20 20 20 20 20 20 20 20 20 20 20 31 36 0a  ME           16.
bac0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
bad0: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 20 20  CNTL_MMAP_SIZE  
bae0: 20 20 20 20 20 20 20 20 20 20 20 20 31 38 0a 23              18.#
baf0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
bb00: 4e 54 4c 5f 54 52 41 43 45 20 20 20 20 20 20 20  NTL_TRACE       
bb10: 20 20 20 20 20 20 20 20 20 20 20 31 39 0a 23 64             19.#d
bb20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
bb30: 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 20 20 20 20  TL_HAS_MOVED    
bb40: 20 20 20 20 20 20 20 20 20 20 32 30 0a 23 64 65            20.#de
bb50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
bb60: 4c 5f 53 59 4e 43 20 20 20 20 20 20 20 20 20 20  L_SYNC          
bb70: 20 20 20 20 20 20 20 20 20 32 31 0a 23 64 65 66           21.#def
bb80: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
bb90: 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f  _COMMIT_PHASETWO
bba0: 20 20 20 20 20 20 20 20 32 32 0a 23 64 65 66 69          22.#defi
bbb0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
bbc0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
bbd0: 20 20 20 20 20 20 20 32 33 0a 2f 2a 20 64 65 70         23./* dep
bbe0: 72 65 63 61 74 65 64 20 6e 61 6d 65 73 20 2a 2f  recated names */
bbf0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
bc00: 47 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  GET_LOCKPROXYFIL
bc10: 45 20 20 20 20 20 20 53 51 4c 49 54 45 5f 46 43  E      SQLITE_FC
bc20: 4e 54 4c 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  NTL_GET_LOCKPROX
bc30: 59 46 49 4c 45 0a 23 64 65 66 69 6e 65 20 53 51  YFILE.#define SQ
bc40: 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f  LITE_SET_LOCKPRO
bc50: 58 59 46 49 4c 45 20 20 20 20 20 20 53 51 4c 49  XYFILE      SQLI
bc60: 54 45 5f 46 43 4e 54 4c 5f 53 45 54 5f 4c 4f 43  TE_FCNTL_SET_LOC
bc70: 4b 50 52 4f 58 59 46 49 4c 45 0a 23 64 65 66 69  KPROXYFILE.#defi
bc80: 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45  ne SQLITE_LAST_E
bc90: 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20  RRNO            
bca0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 41   SQLITE_FCNTL_LA
bcb0: 53 54 5f 45 52 52 4e 4f 0a 0a 2f 2a 0a 2a 2a 20  ST_ERRNO../*.** 
bcc0: 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78 20  CAPI3REF: Mutex 
bcd0: 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65  Handle.**.** The
bce0: 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77 69   mutex module wi
bcf0: 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66 69  thin SQLite defi
bd00: 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  nes [sqlite3_mut
bd10: 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a 20  ex] to be an.** 
bd20: 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66 6f  abstract type fo
bd30: 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63 74  r a mutex object
bd40: 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f  .  The SQLite co
bd50: 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a  re never looks.*
bd60: 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e 61  * at the interna
bd70: 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  l representation
bd80: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
bd90: 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c 79  mutex].  It only
bda0: 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20 70  .** deals with p
bdb0: 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20 5b  ointers to the [
bdc0: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20 6f  sqlite3_mutex] o
bdd0: 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74  bject..**.** Mut
bde0: 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65 64  exes are created
bdf0: 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
be00: 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a  mutex_alloc()]..
be10: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
be20: 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 20  t sqlite3_mutex 
be30: 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a 0a  sqlite3_mutex;..
be40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
be50: 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62 6a  OS Interface Obj
be60: 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73  ect.**.** An ins
be70: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71 6c  tance of the sql
be80: 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20  ite3_vfs object 
be90: 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65  defines the inte
bea0: 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a 2a  rface between.**
beb0: 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   the SQLite core
bec0: 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79   and the underly
bed0: 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73 79  ing operating sy
bee0: 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73 22  stem.  The "vfs"
bef0: 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65 20  .** in the name 
bf00: 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73 74  of the object st
bf10: 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75 61  ands for "virtua
bf20: 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e 20  l file system". 
bf30: 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46 53   See.** the [VFS
bf40: 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74 61   | VFS documenta
bf50: 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68 65  tion] for furthe
bf60: 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  r information..*
bf70: 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20 6f  *.** The value o
bf80: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66  f the iVersion f
bf90: 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c 6c  ield is initiall
bfa0: 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20 6c  y 1 but may be l
bfb0: 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74 75  arger in.** futu
bfc0: 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
bfd0: 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f 6e  QLite.  Addition
bfe0: 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62 65  al fields may be
bff0: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68 69   appended to thi
c000: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65 6e  s.** object when
c010: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76 61   the iVersion va
c020: 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65 64  lue is increased
c030: 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  .  Note that the
c040: 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f 66   structure.** of
c050: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c060: 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73 20   object changes 
c070: 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74 69  in the transacti
c080: 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53 51  on between.** SQ
c090: 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35  Lite version 3.5
c0a0: 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e 64  .9 and 3.6.0 and
c0b0: 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69 6f   yet the iVersio
c0c0: 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74 0a  n field was not.
c0d0: 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a  ** modified..**.
c0e0: 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65 20  ** The szOsFile 
c0f0: 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69 7a  field is the siz
c100: 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61 73  e of the subclas
c110: 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  sed [sqlite3_fil
c120: 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20  e].** structure 
c130: 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46 53  used by this VFS
c140: 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69 73  .  mxPathname is
c150: 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e   the maximum len
c160: 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74 68  gth of.** a path
c170: 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46 53  name in this VFS
c180: 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65 72  ..**.** Register
c190: 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f  ed sqlite3_vfs o
c1a0: 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74 20  bjects are kept 
c1b0: 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73 74  on a linked list
c1c0: 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74 68   formed by.** th
c1d0: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c1e0: 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 76    The [sqlite3_v
c1f0: 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a 2a  fs_register()].*
c200: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 76  * and [sqlite3_v
c210: 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29 5d  fs_unregister()]
c220: 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e 61   interfaces mana
c230: 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a 20  ge this list.** 
c240: 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66 65  in a thread-safe
c250: 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c 69   way.  The [sqli
c260: 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d 20  te3_vfs_find()] 
c270: 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65 61  interface.** sea
c280: 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e 20  rches the list. 
c290: 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70 70   Neither the app
c2a0: 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e 6f  lication code no
c2b0: 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d 70  r the VFS.** imp
c2c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f 75  lementation shou
c2d0: 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78 74  ld use the pNext
c2e0: 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
c2f0: 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64 20  The pNext field 
c300: 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65 6c  is the only fiel
c310: 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33  d in the sqlite3
c320: 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75 72  _vfs.** structur
c330: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  e that SQLite wi
c340: 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e 20  ll ever modify. 
c350: 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e 6c   SQLite will onl
c360: 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20 6d  y access.** or m
c370: 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c 64  odify this field
c380: 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20 61   while holding a
c390: 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61 74   particular stat
c3a0: 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68 65  ic mutex..** The
c3b0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
c3c0: 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66 79  uld never modify
c3d0: 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69 6e   anything within
c3e0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c3f0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65 20  .** object once 
c400: 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20 62  the object has b
c410: 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e 0a  een registered..
c420: 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65 20  **.** The zName 
c430: 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65 20  field holds the 
c440: 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53 20  name of the VFS 
c450: 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61 6d  module.  The nam
c460: 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e 69  e must.** be uni
c470: 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20 56  que across all V
c480: 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a  FS modules..**.*
c490: 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  * [[sqlite3_vfs.
c4a0: 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69  xOpen]].** ^SQLi
c4b0: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
c4c0: 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  at the zFilename
c4d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f   parameter to xO
c4e0: 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  pen.** is either
c4f0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
c500: 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e  or string obtain
c510: 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c 6c  ed.** from xFull
c520: 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68 20  Pathname() with 
c530: 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66 66  an optional suff
c540: 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49 66  ix added..** ^If
c550: 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64 64   a suffix is add
c560: 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65 6e  ed to the zFilen
c570: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20 69  ame parameter, i
c580: 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73  t will.** consis
c590: 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22 2d  t of a single "-
c5a0: 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c 6c  " character foll
c5b0: 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65 20  owed by no more 
c5c0: 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c 70 68 61  than.** 11 alpha
c5d0: 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20 22  numeric and/or "
c5e0: 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -" characters..*
c5f0: 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68 65  * ^SQLite furthe
c600: 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  r guarantees tha
c610: 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20  t.** the string 
c620: 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61 6e  will be valid an
c630: 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74 69  d unchanged unti
c640: 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a 2a  l xClose() is.**
c650: 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73 65   called. Because
c660: 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75 73   of the previous
c670: 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74 68   sentence,.** th
c680: 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  e [sqlite3_file]
c690: 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f 72   can safely stor
c6a0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  e a pointer to t
c6b0: 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69  he.** filename i
c6c0: 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72 65  f it needs to re
c6d0: 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65 6e  member the filen
c6e0: 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ame for some rea
c6f0: 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20 7a  son..** If the z
c700: 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74  Filename paramet
c710: 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20 61  er to xOpen is a
c720: 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
c730: 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74  en xOpen.** must
c740: 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e 20   invent its own 
c750: 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20 66  temporary name f
c760: 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e 57  or the file.  ^W
c770: 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a 20  henever the .** 
c780: 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  xFilename parame
c790: 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20 77  ter is NULL it w
c7a0: 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65 20  ill also be the 
c7b0: 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  case that the.**
c7c0: 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
c7d0: 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b 53   will include [S
c7e0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54  QLITE_OPEN_DELET
c7f0: 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a  EONCLOSE]..**.**
c800: 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d   The flags argum
c810: 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20 69  ent to xOpen() i
c820: 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74 73  ncludes all bits
c830: 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20 66   set in.** the f
c840: 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f  lags argument to
c850: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
c860: 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73 71  2()].  Or if [sq
c870: 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a  lite3_open()].**
c880: 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
c890: 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c 20  n16()] is used, 
c8a0: 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c 75  then flags inclu
c8b0: 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a 20  des at least.** 
c8c0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
c8d0: 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
c8e0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e 20  E_OPEN_CREATE]. 
c8f0: 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20 6f  .** If xOpen() o
c900: 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61 64  pens a file read
c910: 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73 65  -only then it se
c920: 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74 6f  ts *pOutFlags to
c930: 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c  .** include [SQL
c940: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
c950: 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73 20  Y].  Other bits 
c960: 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d 61  in *pOutFlags ma
c970: 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20  y be set..**.** 
c980: 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c  ^(SQLite will al
c990: 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68  so add one of th
c9a0: 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67  e following flag
c9b0: 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29  s to the xOpen()
c9c0: 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e 64  .** call, depend
c9d0: 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65 63  ing on the objec
c9e0: 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a 0a  t being opened:.
c9f0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
ca00: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
ca10: 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69  _MAIN_DB].** <li
ca20: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ca30: 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  MAIN_JOURNAL].**
ca40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ca50: 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20  PEN_TEMP_DB].** 
ca60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ca70: 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d  EN_TEMP_JOURNAL]
ca80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ca90: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
caa0: 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  _DB].** <li>  [S
cab0: 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f  QLITE_OPEN_SUBJO
cac0: 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20  URNAL].** <li>  
cad0: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 53  [SQLITE_OPEN_MAS
cae0: 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  TER_JOURNAL].** 
caf0: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
cb00: 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e  EN_WAL].** </ul>
cb10: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 6c  )^.**.** The fil
cb20: 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74 61  e I/O implementa
cb30: 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68 65  tion can use the
cb40: 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c 61   object type fla
cb50: 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65 20  gs to.** change 
cb60: 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c 73  the way it deals
cb70: 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46 6f   with files.  Fo
cb80: 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70  r example, an ap
cb90: 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68 61  plication.** tha
cba0: 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20  t does not care 
cbb0: 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63 6f  about crash reco
cbc0: 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  very or rollback
cbd0: 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20 74   might make.** t
cbe0: 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f 75  he open of a jou
cbf0: 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d 6f  rnal file a no-o
cc00: 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74 68  p.  Writes to th
cc10: 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  is journal would
cc20: 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f  .** also be no-o
cc30: 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74 65  ps, and any atte
cc40: 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65 20  mpt to read the 
cc50: 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72 65  journal would re
cc60: 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f 49  turn.** SQLITE_I
cc70: 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69 6d  OERR.  Or the im
cc80: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69 67  plementation mig
cc90: 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68 61  ht recognize tha
cca0: 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  t a database.** 
ccb0: 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f 69  file will be doi
ccc0: 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64 20  ng page-aligned 
ccd0: 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e 64  sector reads and
cce0: 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61 6e   writes in a ran
ccf0: 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e 64  dom.** order and
cd00: 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f 20   set up its I/O 
cd10: 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72 64  subsystem accord
cd20: 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c  ingly..**.** SQL
cd30: 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20 61  ite might also a
cd40: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
cd50: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
cd60: 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   the xOpen metho
cd70: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
cd80: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cd90: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
cda0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ].** <li> [SQLIT
cdb0: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
cdc0: 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ].** </ul>.**.**
cdd0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   The [SQLITE_OPE
cde0: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
cdf0: 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65 20   flag means the 
ce00: 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a  file should be.*
ce10: 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20 69  * deleted when i
ce20: 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e 54  t is closed.  ^T
ce30: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
ce40: 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a  DELETEONCLOSE].*
ce50: 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66 6f  * will be set fo
ce60: 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65 73  r TEMP databases
ce70: 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72 6e   and their journ
ce80: 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a 2a  als, transient.*
ce90: 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e 64  * databases, and
cea0: 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a   subjournals..**
ceb0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
cec0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d  _OPEN_EXCLUSIVE]
ced0: 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73 20   flag is always 
cee0: 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63 74  used in conjunct
cef0: 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ion.** with the 
cf00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45  [SQLITE_OPEN_CRE
cf10: 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63 68  ATE] flag, which
cf20: 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63 74   are both direct
cf30: 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73 20  ly.** analogous 
cf40: 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61 6e  to the O_EXCL an
cf50: 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73 20  d O_CREAT flags 
cf60: 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70 65  of the POSIX ope
cf70: 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68 65  n().** API.  The
cf80: 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43   SQLITE_OPEN_EXC
cf90: 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68 65  LUSIVE flag, whe
cfa0: 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74 68  n paired with th
cfb0: 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50 45  e .** SQLITE_OPE
cfc0: 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73 65  N_CREATE, is use
cfd0: 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  d to indicate th
cfe0: 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 61  at file should a
cff0: 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65 61  lways.** be crea
d000: 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69 74  ted, and that it
d010: 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66 20   is an error if 
d020: 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  it already exist
d030: 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e 6e  s..** It is <i>n
d040: 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20 69  ot</i> used to i
d050: 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c 65  ndicate the file
d060: 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e 65   should be opene
d070: 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75 73  d .** for exclus
d080: 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a  ive access..**.*
d090: 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f 73  * ^At least szOs
d0a0: 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d 65  File bytes of me
d0b0: 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61 74  mory are allocat
d0c0: 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
d0d0: 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73 71  to hold the  [sq
d0e0: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72 75  lite3_file] stru
d0f0: 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73 20  cture passed as 
d100: 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72 67  the third.** arg
d110: 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e 20  ument to xOpen. 
d120: 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f   The xOpen metho
d130: 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  d does not have 
d140: 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 74  to.** allocate t
d150: 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69 74  he structure; it
d160: 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69 6c   should just fil
d170: 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20 74  l it in.  Note t
d180: 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65 6e  hat.** the xOpen
d190: 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65 74   method must set
d1a0: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c   the sqlite3_fil
d1b0: 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65 69  e.pMethods to ei
d1c0: 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64 20  ther.** a valid 
d1d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
d1e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20 74  ods] object or t
d1f0: 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d  o NULL.  xOpen m
d200: 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20 65  ust do.** this e
d210: 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e 20  ven if the open 
d220: 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20 65  fails.  SQLite e
d230: 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65 20  xpects that the 
d240: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
d250: 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74  thods.** element
d260: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
d270: 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75 72  fter xOpen retur
d280: 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ns regardless of
d290: 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a 20   the success.** 
d2a0: 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74 68  or failure of th
d2b0: 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a  e xOpen call..**
d2c0: 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66  .** [[sqlite3_vf
d2d0: 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e  s.xAccess]].** ^
d2e0: 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65  The flags argume
d2f0: 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29 20  nt to xAccess() 
d300: 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f 41  may be [SQLITE_A
d310: 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a 2a  CCESS_EXISTS].**
d320: 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68 65   to test for the
d330: 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61 20   existence of a 
d340: 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45  file, or [SQLITE
d350: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
d360: 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77 68  E] to.** test wh
d370: 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20  ether a file is 
d380: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
d390: 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54  table, or [SQLIT
d3a0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a 2a  E_ACCESS_READ].*
d3b0: 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68 65  * to test whethe
d3c0: 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20 6c  r a file is at l
d3d0: 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20 20  east readable.  
d3e0: 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62 65   The file can be
d3f0: 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79 2e   a.** directory.
d400: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .**.** ^SQLite w
d410: 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f 63  ill always alloc
d420: 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78 50  ate at least mxP
d430: 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73 20  athname+1 bytes 
d440: 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70 75  for the.** outpu
d450: 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50 61  t buffer xFullPa
d460: 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78 61  thname.  The exa
d470: 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6f  ct size of the o
d480: 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20  utput buffer.** 
d490: 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20 61  is also passed a
d4a0: 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74 6f  s a parameter to
d4b0: 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e 20   both  methods. 
d4c0: 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75  If the output bu
d4d0: 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c  ffer.** is not l
d4e0: 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53 51  arge enough, [SQ
d4f0: 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 73  LITE_CANTOPEN] s
d500: 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65  hould be returne
d510: 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69 73  d. Since this is
d520: 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20 61  .** handled as a
d530: 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79 20   fatal error by 
d540: 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70 6c  SQLite, vfs impl
d550: 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75  ementations shou
d560: 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20 74  ld endeavor.** t
d570: 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20 62  o prevent this b
d580: 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74 68  y setting mxPath
d590: 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69 63  name to a suffic
d5a0: 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61 6c  iently large val
d5b0: 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52  ue..**.** The xR
d5c0: 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53 6c  andomness(), xSl
d5d0: 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74 54  eep(), xCurrentT
d5e0: 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72 72  ime(), and xCurr
d5f0: 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a 2a  entTimeInt64().*
d600: 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65  * interfaces are
d610: 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61 20   not strictly a 
d620: 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c 65  part of the file
d630: 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65 79  system, but they
d640: 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65 64   are.** included
d650: 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72 75   in the VFS stru
d660: 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c 65  cture for comple
d670: 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20 78  teness..** The x
d680: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75 6e  Randomness() fun
d690: 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20 74  ction attempts t
d6a0: 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73 20  o return nBytes 
d6b0: 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64  bytes.** of good
d6c0: 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d 6e  -quality randomn
d6d0: 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20 20  ess into zOut.  
d6e0: 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  The return value
d6f0: 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75 61   is.** the actua
d700: 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  l number of byte
d710: 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20  s of randomness 
d720: 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68 65  obtained..** The
d730: 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
d740: 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c   causes the call
d750: 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73 6c  ing thread to sl
d760: 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c 65  eep for at.** le
d770: 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ast the number o
d780: 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20 67  f microseconds g
d790: 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75 72  iven.  ^The xCur
d7a0: 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d 65  rentTime().** me
d7b0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 4a  thod returns a J
d7c0: 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65 72  ulian Day Number
d7d0: 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e 74   for the current
d7e0: 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20 61   date and time a
d7f0: 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67 20  s.** a floating 
d800: 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a 20  point value..** 
d810: 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d  ^The xCurrentTim
d820: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
d830: 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20 69  returns, as an i
d840: 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c 69  nteger, the Juli
d850: 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65 72  an.** Day Number
d860: 20 6d 75 6c 74 69 70 6c 69 65 64 20 62 79 20 38   multiplied by 8
d870: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
d880: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
d890: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
d8a0: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
d8b0: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
d8c0: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
d8d0: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
d8e0: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
d8f0: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
d900: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
d910: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
d920: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
d930: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
d940: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
d950: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
d960: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
d970: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
d980: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
d990: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
d9a0: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
d9b0: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
d9c0: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
d9d0: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
d9e0: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
d9f0: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
da00: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
da10: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
da20: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
da30: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
da40: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
da50: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
da60: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
da70: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
da80: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
da90: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
daa0: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
dab0: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
dac0: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
dad0: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
dae0: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
daf0: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
db00: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
db10: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
db20: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
db30: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
db40: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
db50: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
db60: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
db70: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
db80: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
db90: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
dba0: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
dbb0: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
dbc0: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
dbd0: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
dbe0: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
dbf0: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
dc00: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
dc10: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
dc20: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
dc30: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
dc40: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
dc50: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
dc60: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
dc70: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
dc80: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
dc90: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
dca0: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
dcb0: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
dcc0: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
dcd0: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
dce0: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
dcf0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
dd00: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
dd10: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
dd20: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
dd30: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
dd40: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
dd50: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
dd60: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
dd70: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
dd80: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
dd90: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
dda0: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
ddb0: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
ddc0: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
ddd0: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
dde0: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
ddf0: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
de00: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
de10: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
de20: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
de30: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
de40: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
de50: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
de60: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
de70: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
de80: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
de90: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
dea0: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
deb0: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
dec0: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
ded0: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
dee0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
def0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
df00: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
df10: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
df20: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
df30: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
df40: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
df50: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
df60: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
df70: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
df80: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
df90: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dfa0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
dfb0: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
dfc0: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
dfd0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
dfe0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
dff0: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
e000: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
e010: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
e020: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
e030: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e040: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
e050: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
e060: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
e070: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
e080: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
e090: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
e0a0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
e0b0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e0c0: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
e0d0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
e0e0: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
e0f0: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
e100: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
e110: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
e120: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
e130: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
e140: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
e150: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
e160: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
e170: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
e180: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
e190: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
e1a0: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
e1b0: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
e1c0: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
e1d0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
e1e0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e1f0: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
e200: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
e210: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
e220: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
e230: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
e240: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
e250: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
e260: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
e270: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
e280: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
e290: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
e2a0: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
e2b0: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
e2c0: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
e2d0: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
e2e0: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
e2f0: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
e300: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
e310: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
e320: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
e330: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
e340: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
e350: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
e360: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
e370: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
e380: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
e390: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
e3a0: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
e3b0: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
e3c0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
e3d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
e3e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
e3f0: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
e400: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
e410: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
e420: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
e430: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
e440: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
e450: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
e460: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
e470: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
e480: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
e490: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
e4a0: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
e4b0: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
e4c0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
e4d0: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
e4e0: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
e4f0: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
e500: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
e510: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
e520: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
e530: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
e540: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
e550: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
e560: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
e570: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
e580: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
e590: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
e5a0: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
e5b0: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
e5c0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
e5d0: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e5e0: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
e5f0: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
e600: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
e610: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
e620: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
e630: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e640: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e650: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
e660: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
e670: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
e680: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
e690: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
e6a0: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
e6b0: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
e6c0: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
e6d0: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
e6e0: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
e6f0: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
e700: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
e710: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
e720: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
e730: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
e740: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
e750: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
e760: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
e770: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
e780: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
e790: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
e7a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
e7b0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
e7c0: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
e7d0: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
e7e0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e7f0: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
e800: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
e810: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
e820: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
e830: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
e840: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
e850: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e860: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
e870: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
e880: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
e890: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
e8a0: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
e8b0: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
e8c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
e8d0: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
e8e0: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
e8f0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
e900: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
e910: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
e920: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
e930: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
e940: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
e950: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
e960: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
e970: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
e980: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
e990: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
e9a0: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
e9b0: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
e9c0: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
e9d0: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
e9e0: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
e9f0: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
ea00: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
ea10: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
ea20: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
ea30: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ea40: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
ea50: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
ea60: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
ea70: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
ea80: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
ea90: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
eaa0: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
eab0: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
eac0: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
ead0: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
eae0: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
eaf0: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
eb00: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
eb10: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
eb20: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
eb30: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
eb40: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
eb50: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
eb60: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
eb70: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
eb80: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
eb90: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
eba0: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
ebb0: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
ebc0: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
ebd0: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
ebe0: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
ebf0: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
ec00: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
ec10: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
ec20: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
ec30: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
ec40: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
ec50: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
ec60: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
ec70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
ec80: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
ec90: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
eca0: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
ecb0: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
ecc0: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
ecd0: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
ece0: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
ecf0: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
ed00: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
ed10: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
ed20: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
ed30: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
ed40: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
ed50: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
ed60: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
ed70: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
ed80: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
ed90: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
eda0: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
edb0: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
edc0: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
edd0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ede0: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
edf0: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
ee00: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
ee10: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
ee20: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
ee30: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
ee40: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
ee50: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
ee60: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
ee70: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
ee80: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
ee90: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
eea0: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
eeb0: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
eec0: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
eed0: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
eee0: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
eef0: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
ef00: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
ef10: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
ef20: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
ef30: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
ef40: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
ef50: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
ef60: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
ef70: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
ef80: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
ef90: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
efa0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
efb0: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
efc0: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
efd0: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
efe0: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
eff0: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
f000: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f010: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
f020: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
f030: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
f040: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
f050: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
f060: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
f070: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
f080: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
f090: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
f0a0: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
f0b0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
f0c0: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
f0d0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f0e0: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
f0f0: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
f100: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
f110: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
f120: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
f130: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
f140: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
f150: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
f160: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
f170: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f180: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
f190: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
f1a0: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
f1b0: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
f1c0: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
f1d0: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
f1e0: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
f1f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f200: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
f210: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
f220: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
f230: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
f240: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
f250: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
f260: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
f270: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
f280: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
f290: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
f2a0: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
f2b0: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
f2c0: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
f2d0: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
f2e0: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
f2f0: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
f300: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
f310: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
f320: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
f330: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
f340: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
f350: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
f360: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
f370: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
f380: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
f390: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
f3a0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
f3b0: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
f3c0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
f3d0: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
f3e0: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
f3f0: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
f400: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
f410: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
f420: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
f430: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
f440: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
f450: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
f460: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
f470: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
f480: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
f490: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
f4a0: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
f4b0: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
f4c0: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
f4d0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f4e0: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
f4f0: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
f500: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
f510: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
f520: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
f530: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
f540: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
f550: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
f560: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
f570: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
f580: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
f590: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
f5a0: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
f5b0: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
f5c0: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
f5d0: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
f5e0: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
f5f0: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
f600: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
f610: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
f620: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
f630: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
f640: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
f650: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f660: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
f670: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
f680: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
f690: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
f6a0: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
f6b0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
f6c0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
f6d0: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
f6e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
f6f0: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
f700: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f710: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
f720: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
f730: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
f740: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
f750: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
f760: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
f770: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
f780: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
f790: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
f7a0: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
f7b0: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
f7c0: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
f7d0: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
f7e0: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
f7f0: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
f800: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
f810: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
f820: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
f830: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
f840: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
f850: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
f860: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
f870: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
f880: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
f890: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
f8a0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
f8b0: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
f8c0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
f8d0: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
f8e0: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
f8f0: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
f900: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
f910: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
f920: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
f930: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
f940: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
f950: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
f960: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
f970: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
f980: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
f990: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
f9a0: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
f9b0: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
f9c0: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
f9d0: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
f9e0: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
f9f0: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
fa00: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
fa10: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
fa20: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
fa30: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
fa40: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
fa50: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
fa60: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
fa70: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
fa80: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
fa90: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
faa0: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
fab0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
fac0: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
fad0: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
fae0: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
faf0: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
fb00: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
fb10: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
fb20: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
fb30: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
fb40: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
fb50: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
fb60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
fb70: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
fb80: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
fb90: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
fba0: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
fbb0: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
fbc0: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
fbd0: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
fbe0: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
fbf0: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
fc00: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
fc10: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
fc20: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
fc30: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
fc40: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
fc50: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
fc60: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
fc70: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
fc80: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
fc90: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
fca0: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
fcb0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
fcc0: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
fcd0: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
fce0: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
fcf0: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
fd00: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
fd10: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
fd20: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
fd30: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
fd40: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
fd50: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
fd60: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
fd70: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
fd80: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
fd90: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
fda0: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
fdb0: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
fdc0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fdd0: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
fde0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
fdf0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
fe00: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
fe10: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
fe20: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
fe30: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
fe40: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
fe50: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
fe60: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fe70: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fe80: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
fe90: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
fea0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
feb0: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
fec0: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
fed0: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
fee0: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
fef0: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
ff00: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
ff10: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
ff20: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
ff30: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
ff40: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
ff50: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
ff60: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
ff70: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
ff80: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
ff90: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
ffa0: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
ffb0: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
ffc0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
ffd0: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
ffe0: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
fff0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
10000 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
10010 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
10020 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
10030 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
10040 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
10050 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
10060 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
10070 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
10080 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
10090 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
100a0 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
100b0 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
100c0 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
100d0 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
100e0 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
100f0 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
10100 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
10110 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
10120 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
10130 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
10140 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
10150 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
10160 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
10170 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
10180 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
10190 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
101a0 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
101b0 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
101c0 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
101d0 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
101e0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
101f0 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
10200 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
10210 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
10220 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
10230 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
10240 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
10250 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
10260 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
10270 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
10280 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
10290 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
102a0 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
102b0 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
102c0 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
102d0 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
102e0 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
102f0 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
10300 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
10310 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
10320 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
10330 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
10340 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
10350 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
10360 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
10370 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
10380 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
10390 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
103a0 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
103b0 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
103c0 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
103d0 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
103e0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
103f0 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
10400 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
10410 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
10420 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
10430 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
10440 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
10450 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
10460 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
10470 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
10480 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
10490 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
104a0 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
104b0 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
104c0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
104d0 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
104e0 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
104f0 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
10500 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
10510 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
10520 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
10530 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
10540 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
10550 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
10560 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
10570 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
10580 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
10590 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
105a0 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
105b0 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
105c0 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
105d0 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
105e0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
105f0 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
10600 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
10610 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
10620 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10630 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
10640 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
10650 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
10660 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
10670 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
10680 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
10690 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
106a0 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
106b0 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
106c0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
106d0 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
106e0 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
106f0 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
10700 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
10710 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
10720 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
10730 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
10740 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
10750 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
10760 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
10770 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
10780 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
10790 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
107a0 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
107b0 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
107c0 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
107d0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
107e0 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
107f0 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
10800 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
10810 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
10820 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
10830 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
10840 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
10850 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
10860 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
10870 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
10880 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
10890 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
108a0 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
108b0 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
108c0 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
108d0 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
108e0 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
108f0 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
10900 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
10910 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
10920 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10930 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
10940 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
10950 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
10960 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
10970 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
10980 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
10990 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
109a0 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
109b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
109c0 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
109d0 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
109e0 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
109f0 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
10a00 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
10a10 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
10a20 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
10a30 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
10a40 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
10a50 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
10a60 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
10a70 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
10a80 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
10a90 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
10aa0 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
10ab0 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
10ac0 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
10ad0 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
10ae0 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
10af0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
10b00 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
10b10 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
10b20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
10b30 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
10b40 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
10b50 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
10b60 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
10b70 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
10b80 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20 78 52 65  The xMalloc, xRe
10b90 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46 72 65 65  alloc, and xFree
10ba0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f   methods must wo
10bb0 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d  rk like the.** m
10bc0 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c 6c 6f 63  alloc(), realloc
10bd0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 66 75  () and free() fu
10be0 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20 74 68 65  nctions from the
10bf0 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72   standard C libr
10c00 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ary..** ^SQLite 
10c10 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
10c20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10c30 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
10c40 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
10c50 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
10c60 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
10c70 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a   xRoundup..**.**
10c80 20 78 53 69 7a 65 20 73 68 6f 75 6c 64 20 72 65   xSize should re
10c90 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74  turn the allocat
10ca0 65 64 20 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d  ed size of a mem
10cb0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  ory allocation.*
10cc0 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 6f 62 74  * previously obt
10cd0 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c  ained from xMall
10ce0 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20  oc or xRealloc. 
10cf0 20 54 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   The allocated s
10d00 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73  ize.** is always
10d10 20 61 74 20 6c 65 61 73 74 20 61 73 20 62 69 67   at least as big
10d20 20 61 73 20 74 68 65 20 72 65 71 75 65 73 74 65   as the requeste
10d30 64 20 73 69 7a 65 20 62 75 74 20 6d 61 79 20 62  d size but may b
10d40 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20  e larger..**.** 
10d50 54 68 65 20 78 52 6f 75 6e 64 75 70 20 6d 65 74  The xRoundup met
10d60 68 6f 64 20 72 65 74 75 72 6e 73 20 77 68 61 74  hod returns what
10d70 20 77 6f 75 6c 64 20 62 65 20 74 68 65 20 61 6c   would be the al
10d80 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f 66 0a  located size of.
10d90 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ** a memory allo
10da0 63 61 74 69 6f 6e 20 67 69 76 65 6e 20 61 20 70  cation given a p
10db0 61 72 74 69 63 75 6c 61 72 20 72 65 71 75 65 73  articular reques
10dc0 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20  ted size.  Most 
10dd0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
10de0 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 6d 65  tors round up me
10df0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
10e00 20 61 74 20 6c 65 61 73 74 20 74 6f 20 74 68 65   at least to the
10e10 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a   next multiple.*
10e20 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c  * of 8.  Some al
10e30 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75  locators round u
10e40 70 20 74 6f 20 61 20 6c 61 72 67 65 72 20 6d 75  p to a larger mu
10e50 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20 61 20 70  ltiple or to a p
10e60 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76  ower of 2..** Ev
10e70 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ery memory alloc
10e80 61 74 69 6f 6e 20 72 65 71 75 65 73 74 20 63 6f  ation request co
10e90 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75 67 68 20  ming in through 
10ea0 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
10eb0 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65  )].** or [sqlite
10ec0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72  3_realloc()] fir
10ed0 73 74 20 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75  st calls xRoundu
10ee0 70 2e 20 20 49 66 20 78 52 6f 75 6e 64 75 70 20  p.  If xRoundup 
10ef0 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74  returns 0, .** t
10f00 68 61 74 20 63 61 75 73 65 73 20 74 68 65 20 63  hat causes the c
10f10 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d  orresponding mem
10f20 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74  ory allocation t
10f30 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68  o fail..**.** Th
10f40 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 69  e xInit method i
10f50 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 20 6d  nitializes the m
10f60 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e  emory allocator.
10f70 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a    For example,.*
10f80 2a 20 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63  * it might alloc
10f90 61 74 65 20 61 6e 79 20 72 65 71 75 69 72 65 20  ate any require 
10fa0 6d 75 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69  mutexes or initi
10fb0 61 6c 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64  alize internal d
10fc0 61 74 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ata.** structure
10fd0 73 2e 20 20 54 68 65 20 78 53 68 75 74 64 6f 77  s.  The xShutdow
10fe0 6e 20 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f  n method is invo
10ff0 6b 65 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29  ked (indirectly)
11000 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
11010 73 68 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20  shutdown()] and 
11020 73 68 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74  should deallocat
11030 65 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  e any resources 
11040 61 63 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78  acquired.** by x
11050 49 6e 69 74 2e 20 20 54 68 65 20 70 41 70 70 44  Init.  The pAppD
11060 61 74 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75  ata pointer is u
11070 73 65 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20  sed as the only 
11080 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
11090 78 49 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64  xInit and xShutd
110a0 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  own..**.** SQLit
110b0 65 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  e holds the [SQL
110c0 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
110d0 5f 4d 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77  _MASTER] mutex w
110e0 68 65 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a  hen it invokes.*
110f0 2a 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68  * the xInit meth
11100 6f 64 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74  od, so the xInit
11110 20 6d 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74   method need not
11120 20 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20   be threadsafe. 
11130 20 54 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77   The.** xShutdow
11140 6e 20 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79  n method is only
11150 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71   called from [sq
11160 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
11170 5d 20 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20  ] so it does.** 
11180 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74  not need to be t
11190 68 72 65 61 64 73 61 66 65 20 65 69 74 68 65 72  hreadsafe either
111a0 2e 20 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72  .  For all other
111b0 20 6d 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65   methods, SQLite
111c0 0a 2a 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53  .** holds the [S
111d0 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54  QLITE_MUTEX_STAT
111e0 49 43 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73  IC_MEM] mutex as
111f0 20 6c 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20   long as the.** 
11200 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11210 45 4d 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67  EMSTATUS] config
11220 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
11230 73 20 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69  s turned on (whi
11240 63 68 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64  ch.** it is by d
11250 65 66 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74  efault) and so t
11260 68 65 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61  he methods are a
11270 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72  utomatically ser
11280 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65  ialized..** Howe
11290 76 65 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f  ver, if [SQLITE_
112a0 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
112b0 5d 20 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74  ] is disabled, t
112c0 68 65 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a  hen the other.**
112d0 20 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65   methods must be
112e0 20 74 68 72 65 61 64 73 61 66 65 20 6f 72 20 65   threadsafe or e
112f0 6c 73 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f  lse make their o
11300 77 6e 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20  wn arrangements 
11310 66 6f 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61  for.** serializa
11320 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  tion..**.** SQLi
11330 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e  te will never in
11340 76 6f 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72  voke xInit() mor
11350 65 20 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68  e than once with
11360 6f 75 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69  out an interveni
11370 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53  ng.** call to xS
11380 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79  hutdown()..*/.ty
11390 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
113a0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
113b0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
113c0 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c  hods;.struct sql
113d0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
113e0 20 7b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61   {.  void *(*xMa
113f0 6c 6c 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20  lloc)(int);     
11400 20 20 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c      /* Memory al
11410 6c 6f 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  location functio
11420 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46  n */.  void (*xF
11430 72 65 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  ree)(void*);    
11440 20 20 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20        /* Free a 
11450 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
11460 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52   */.  void *(*xR
11470 65 61 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e  ealloc)(void*,in
11480 74 29 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61  t);  /* Resize a
11490 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
114a0 20 20 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76    int (*xSize)(v
114b0 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
114c0 20 2f 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73   /* Return the s
114d0 69 7a 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61  ize of an alloca
114e0 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
114f0 78 52 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20  xRoundup)(int); 
11500 20 20 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e           /* Roun
11510 64 20 75 70 20 72 65 71 75 65 73 74 20 73 69 7a  d up request siz
11520 65 20 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  e to allocation 
11530 73 69 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  size */.  int (*
11540 78 49 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20  xInit)(void*);  
11550 20 20 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74           /* Init
11560 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11570 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11580 20 76 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77   void (*xShutdow
11590 6e 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  n)(void*);      
115a0 2f 2a 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20  /* Deinitialize 
115b0 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
115c0 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  ator */.  void *
115d0 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
115e0 20 20 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75           /* Argu
115f0 6d 65 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20  ment to xInit() 
11600 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20  and xShutdown() 
11610 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.};../*.** CAP
11620 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61  I3REF: Configura
11630 74 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20  tion Options.** 
11640 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69  KEYWORDS: {confi
11650 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d  guration option}
11660 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
11670 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
11680 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
11690 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
116a0 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
116b0 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
116c0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
116d0 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  nt to the [sqlit
116e0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74  e3_config()] int
116f0 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  erface..**.** Ne
11700 77 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  w configuration 
11710 6f 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61  options may be a
11720 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
11730 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
11740 65 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63  e..** Existing c
11750 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11760 69 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69  ions might be di
11770 73 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70  scontinued.  App
11780 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f  lications.** sho
11790 75 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65  uld check the re
117a0 74 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b  turn code from [
117b0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
117c0 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
117d0 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
117e0 77 6f 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71  worked.  The [sq
117f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11800 69 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72  interface will r
11810 65 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a  eturn a.** non-z
11820 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
11830 20 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75   if a discontinu
11840 65 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65  ed or unsupporte
11850 64 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  d configuration 
11860 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76  option.** is inv
11870 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  oked..**.** <dl>
11880 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
11890 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
118a0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
118b0 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
118c0 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
118d0 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118e0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
11900 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
11910 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11920 74 6f 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64  to Single-thread
11930 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  .  In other word
11940 73 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a  s, it disables.*
11950 2a 20 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61  * all mutexing a
11960 6e 64 20 70 75 74 73 20 53 51 4c 69 74 65 20 69  nd puts SQLite i
11970 6e 74 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65  nto a mode where
11980 20 69 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20   it can only be 
11990 75 73 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e  used.** by a sin
119a0 67 6c 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49  gle thread.   ^I
119b0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
119c0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
119d0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
119e0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
119f0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
11a00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
11a10 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74  hen.** it is not
11a20 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61   possible to cha
11a30 6e 67 65 20 74 68 65 20 5b 74 68 72 65 61 64 69  nge the [threadi
11a40 6e 67 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74  ng mode] from it
11a50 73 20 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c  s default.** val
11a60 75 65 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72  ue of Single-thr
11a70 65 61 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69  ead and so [sqli
11a80 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
11a90 6c 6c 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53  ll return .** [S
11aa0 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
11ab0 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  called with the 
11ac0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49  SQLITE_CONFIG_SI
11ad0 4e 47 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f  NGLETHREAD.** co
11ae0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11af0 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
11b00 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
11b10 55 4c 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74  ULTITHREAD]] <dt
11b20 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
11b30 55 4c 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a  ULTITHREAD</dt>.
11b40 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65  ** <dd>There are
11b50 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f   no arguments to
11b60 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e   this option.  ^
11b70 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
11b80 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69   the.** [threadi
11b90 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74  ng mode] to Mult
11ba0 69 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74  i-thread.  In ot
11bb0 68 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69  her words, it di
11bc0 73 61 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69  sables.** mutexi
11bd0 6e 67 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20  ng on [database 
11be0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20  connection] and 
11bf0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11c00 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  ent] objects..**
11c10 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
11c20 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20   is responsible 
11c30 66 6f 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20  for serializing 
11c40 61 63 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61  access to.** [da
11c50 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11c60 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  ns] and [prepare
11c70 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20  d statements].  
11c80 42 75 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65  But other mutexe
11c90 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64  s.** are enabled
11ca0 20 73 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20   so that SQLite 
11cb0 77 69 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20  will be safe to 
11cc0 75 73 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74  use in a multi-t
11cd0 68 72 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72  hreaded.** envir
11ce0 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61  onment as long a
11cf0 73 20 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73  s no two threads
11d00 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
11d10 74 68 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74  the same.** [dat
11d20 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11d30 5d 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  ] at the same ti
11d40 6d 65 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20  me.  ^If SQLite 
11d50 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11d60 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11d70 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11d80 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11d90 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11da0 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11db0 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11dc0 20 74 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74   to set the Mult
11dd0 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64  i-thread [thread
11de0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
11df0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11e00 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
11e10 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
11e20 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
11e30 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
11e40 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63  IG_MULTITHREAD c
11e50 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
11e60 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ion.</dd>.**.** 
11e70 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
11e80 53 45 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74  SERIALIZED]] <dt
11e90 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53  >SQLITE_CONFIG_S
11ea0 45 52 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a  ERIALIZED</dt>.*
11eb0 2a 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20  * <dd>There are 
11ec0 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  no arguments to 
11ed0 74 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54  this option.  ^T
11ee0 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20  his option sets 
11ef0 74 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e  the.** [threadin
11f00 67 20 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61  g mode] to Seria
11f10 6c 69 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20  lized. In other 
11f20 77 6f 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69  words, this opti
11f30 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c  on enables.** al
11f40 6c 20 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64  l mutexes includ
11f50 69 6e 67 20 74 68 65 20 72 65 63 75 72 73 69 76  ing the recursiv
11f60 65 0a 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20  e.** mutexes on 
11f70 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
11f80 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61  tion] and [prepa
11f90 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f  red statement] o
11fa0 62 6a 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68  bjects..** In th
11fb0 69 73 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69  is mode (which i
11fc0 73 20 74 68 65 20 64 65 66 61 75 6c 74 20 77 68  s the default wh
11fd0 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  en SQLite is com
11fe0 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53  piled with.** [S
11ff0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
12000 3d 31 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20  =1]) the SQLite 
12010 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73  library will its
12020 65 6c 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63  elf serialize ac
12030 63 65 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61  cess.** to [data
12040 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
12050 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
12060 73 74 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74  statements] so t
12070 68 61 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69  hat the.** appli
12080 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74  cation is free t
12090 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b  o use the same [
120a0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
120b0 69 6f 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73  ion] or the.** s
120c0 61 6d 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  ame [prepared st
120d0 61 74 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66  atement] in diff
120e0 65 72 65 6e 74 20 74 68 72 65 61 64 73 20 61 74  erent threads at
120f0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a   the same time..
12100 2a 2a 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  ** ^If SQLite is
12110 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
12120 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
12130 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
12140 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
12150 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
12160 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
12170 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
12180 6f 20 73 65 74 20 74 68 65 20 53 65 72 69 61 6c  o set the Serial
12190 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
121a0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
121b0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
121c0 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
121d0 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
121e0 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
121f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53   SQLITE_CONFIG_S
12200 45 52 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67  ERIALIZED config
12210 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
12220 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12230 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
12240 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  C]] <dt>SQLITE_C
12250 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74  ONFIG_MALLOC</dt
12260 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
12270 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
12280 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
12290 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
122a0 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
122b0 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
122c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
122d0 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68  ] structure.  Th
122e0 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69  e argument speci
122f0 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74  fies.** alternat
12300 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65  ive low-level me
12310 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12320 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
12330 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a  sed in place of.
12340 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ** the memory al
12350 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
12360 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c  s built into SQL
12370 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d  ite.)^ ^SQLite m
12380 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20  akes.** its own 
12390 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
123a0 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
123b0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
123c0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
123d0 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65  re.** before the
123e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
123f0 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73  ()] call returns
12400 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12410 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
12420 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c  MALLOC]] <dt>SQL
12430 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
12440 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LLOC</dt>.** <dd
12450 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
12460 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
12470 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
12480 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12490 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
124a0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
124b0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
124c0 75 72 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74  ure.  The [sqlit
124d0 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a  e3_mem_methods].
124e0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
124f0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
12500 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
12510 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
12520 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  ion routines.)^.
12530 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
12540 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
12550 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
12560 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  lt memory alloca
12570 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  tion.** routines
12580 20 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20   with a wrapper 
12590 74 68 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73  that simulations
125a0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
125b0 6f 6e 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a  on failure or.**
125c0 20 74 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75   tracks memory u
125d0 73 61 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c  sage, for exampl
125e0 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
125f0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
12600 45 4d 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53  EMSTATUS]] <dt>S
12610 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12620 53 54 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c  STATUS</dt>.** <
12630 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12640 20 74 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72   takes single ar
12650 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69  gument of type i
12660 6e 74 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20  nt, interpreted 
12670 61 73 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e  as a .** boolean
12680 2c 20 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20  , which enables 
12690 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68 65 20  or disables the 
126a0 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65  collection of me
126b0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
126c0 0a 2a 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20  .** statistics. 
126d0 5e 28 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c  ^(When memory al
126e0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
126f0 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
12700 2c 20 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77  , the .** follow
12710 69 6e 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72  ing SQLite inter
12720 66 61 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e  faces become non
12730 2d 6f 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a  -operational:.**
12740 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69     <ul>.**   <li
12750 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
12760 79 5f 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c  y_used()].**   <
12770 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  li> [sqlite3_mem
12780 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d  ory_highwater()]
12790 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
127a0 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
127b0 6d 69 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c  mit64()].**   <l
127c0 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74  i> [sqlite3_stat
127d0 75 73 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e  us()].**   </ul>
127e0 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c  )^.** ^Memory al
127f0 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12800 69 63 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20  ics are enabled 
12810 62 79 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73  by default unles
12820 73 20 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63  s SQLite is.** c
12830 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51  ompiled with [SQ
12840 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
12850 53 54 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69  STATUS]=0 in whi
12860 63 68 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a  ch case memory.*
12870 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  * allocation sta
12880 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
12890 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e  bled by default.
128a0 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .** </dd>.**.** 
128b0 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
128c0 53 43 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51  SCRATCH]] <dt>SQ
128d0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
128e0 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TCH</dt>.** <dd>
128f0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
12900 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
12910 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
12920 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
12930 73 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63  se for.** scratc
12940 68 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65  h memory.  There
12950 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
12960 65 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72  ents:  A pointer
12970 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c   an 8-byte.** al
12980 69 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66  igned memory buf
12990 66 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74  fer from which t
129a0 68 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63  he scratch alloc
129b0 61 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a  ations will be.*
129c0 2a 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a  * drawn, the siz
129d0 65 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63  e of each scratc
129e0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a  h allocation (sz
129f0 29 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61  ),.** and the ma
12a00 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12a10 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69  scratch allocati
12a20 6f 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a  ons (N).  The sz
12a30 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  .** argument mus
12a40 74 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20  t be a multiple 
12a50 6f 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69  of 16..** The fi
12a60 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12a70 74 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  t be a pointer t
12a80 6f 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  o an 8-byte alig
12a90 6e 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66  ned buffer.** of
12aa0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
12ab0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
12ac0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12ad0 75 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e  use no more than
12ae0 20 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66   two scratch buf
12af0 66 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e  fers per thread.
12b00 20 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64    So.** N should
12b10 20 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65   be set to twice
12b20 20 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61   the expected ma
12b30 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
12b40 74 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c  threads..** ^SQL
12b50 69 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72  ite will never r
12b60 65 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68  equire a scratch
12b70 20 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20   buffer that is 
12b80 6d 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74  more than 6.** t
12b90 69 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73  imes the databas
12ba0 65 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66  e page size. ^If
12bb0 20 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65   SQLite needs ne
12bc0 65 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  eds additional.*
12bd0 2a 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79  * scratch memory
12be0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
12bf0 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
12c00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
12c10 70 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20  ption, then .** 
12c20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12c30 29 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20  )] will be used 
12c40 74 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65  to obtain the me
12c50 6d 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64  mory needed.</dd
12c60 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12c70 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12c80 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  E]] <dt>SQLITE_C
12c90 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c  ONFIG_PAGECACHE<
12ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12cb0 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
12cc0 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12cd0 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
12ce0 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12cf0 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  or.** the databa
12d00 73 65 20 70 61 67 65 20 63 61 63 68 65 20 77 69  se page cache wi
12d10 74 68 20 74 68 65 20 64 65 66 61 75 6c 74 20 70  th the default p
12d20 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
12d30 65 6e 74 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54  entation.  .** T
12d40 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  his configuratio
12d50 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  n should not be 
12d60 75 73 65 64 20 69 66 20 61 6e 20 61 70 70 6c 69  used if an appli
12d70 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61  cation-define pa
12d80 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c  ge.** cache impl
12d90 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f  ementation is lo
12da0 61 64 65 64 20 75 73 69 6e 67 20 74 68 65 20 53  aded using the S
12db0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
12dc0 43 48 45 32 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  CHE2 option..** 
12dd0 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20  There are three 
12de0 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
12df0 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69 6e  s option: A poin
12e00 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61 6c  ter to 8-byte al
12e10 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c  igned.** memory,
12e20 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63   the size of eac
12e30 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28 73  h page buffer (s
12e40 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d 62  z), and the numb
12e50 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29 2e  er of pages (N).
12e60 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75 6d  .** The sz argum
12e70 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74 68  ent should be th
12e80 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c 61  e size of the la
12e90 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20 70  rgest database p
12ea0 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72 20  age.** (a power 
12eb0 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20 35  of two between 5
12ec0 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70 6c  12 and 32768) pl
12ed0 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74 72  us a little extr
12ee0 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70 61  a for each.** pa
12ef0 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68 65  ge header.  ^The
12f00 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69 7a   page header siz
12f10 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62 79  e is 20 to 40 by
12f20 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e  tes depending on
12f30 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72 63  .** the host arc
12f40 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74 20  hitecture.  ^It 
12f50 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70 61  is harmless, apa
12f60 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73 74  rt from the wast
12f70 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f  ed memory,.** to
12f80 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74 6c   make sz a littl
12f90 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54 68  e too large.  Th
12fa0 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75 6d  e first.** argum
12fb0 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e 74  ent should point
12fc0 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f   to an allocatio
12fd0 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  n of at least sz
12fe0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
12ff0 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
13000 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d 6f  ill use the memo
13010 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  ry provided by t
13020 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
13030 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74 73  t to satisfy its
13040 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73  .** memory needs
13050 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 4e   for the first N
13060 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20 61   pages that it a
13070 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20 5e  dds to cache.  ^
13080 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  If additional.**
13090 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f   page cache memo
130a0 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65 79  ry is needed bey
130b0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
130c0 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70 74  ided by this opt
130d0 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c  ion, then.** SQL
130e0 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71 6c  ite goes to [sql
130f0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66  ite3_malloc()] f
13100 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e 61  or the additiona
13110 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65 2e  l storage space.
13120 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
13130 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67  in the first arg
13140 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62 65  ument must.** be
13150 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38   aligned to an 8
13160 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20 6f  -byte boundary o
13170 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65 68  r subsequent beh
13180 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
13190 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66  ** will be undef
131a0 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ined.</dd>.**.**
131b0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
131c0 5f 48 45 41 50 5d 5d 20 3c 64 74 3e 53 51 4c 49  _HEAP]] <dt>SQLI
131d0 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 3c 2f  TE_CONFIG_HEAP</
131e0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
131f0 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69  s option specifi
13200 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f  es a static memo
13210 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53  ry buffer that S
13220 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a  QLite will use.*
13230 2a 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  * for all of its
13240 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
13250 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73  allocation needs
13260 20 62 65 79 6f 6e 64 20 74 68 6f 73 65 20 70 72   beyond those pr
13270 6f 76 69 64 65 64 0a 2a 2a 20 66 6f 72 20 62 79  ovided.** for by
13280 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13290 53 43 52 41 54 43 48 5d 20 61 6e 64 20 5b 53 51  SCRATCH] and [SQ
132a0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
132b0 43 41 43 48 45 5d 2e 0a 2a 2a 20 54 68 65 72 65  CACHE]..** There
132c0 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d   are three argum
132d0 65 6e 74 73 3a 20 41 6e 20 38 2d 62 79 74 65 20  ents: An 8-byte 
132e0 61 6c 69 67 6e 65 64 20 70 6f 69 6e 74 65 72 20  aligned pointer 
132f0 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a  to the memory,.*
13300 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
13310 62 79 74 65 73 20 69 6e 20 74 68 65 20 6d 65 6d  bytes in the mem
13320 6f 72 79 20 62 75 66 66 65 72 2c 20 61 6e 64 20  ory buffer, and 
13330 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
13340 63 61 74 69 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20  cation size..** 
13350 5e 49 66 20 74 68 65 20 66 69 72 73 74 20 70 6f  ^If the first po
13360 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
13370 79 20 70 6f 69 6e 74 65 72 29 20 69 73 20 4e 55  y pointer) is NU
13380 4c 4c 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  LL, then SQLite 
13390 72 65 76 65 72 74 73 0a 2a 2a 20 74 6f 20 75 73  reverts.** to us
133a0 69 6e 67 20 69 74 73 20 64 65 66 61 75 6c 74 20  ing its default 
133b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
133c0 20 28 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c   (the system mal
133d0 6c 6f 63 28 29 20 69 6d 70 6c 65 6d 65 6e 74 61  loc() implementa
133e0 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e  tion),.** undoin
133f0 67 20 61 6e 79 20 70 72 69 6f 72 20 69 6e 76 6f  g any prior invo
13400 63 61 74 69 6f 6e 20 6f 66 20 5b 53 51 4c 49 54  cation of [SQLIT
13410 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
13420 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 6d 65  .  ^If the.** me
13430 6d 6f 72 79 20 70 6f 69 6e 74 65 72 20 69 73 20  mory pointer is 
13440 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 65 69 74  not NULL and eit
13450 68 65 72 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  her [SQLITE_ENAB
13460 4c 45 5f 4d 45 4d 53 59 53 33 5d 20 6f 72 0a 2a  LE_MEMSYS3] or.*
13470 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
13480 5f 4d 45 4d 53 59 53 35 5d 20 61 72 65 20 64 65  _MEMSYS5] are de
13490 66 69 6e 65 64 2c 20 74 68 65 6e 20 74 68 65 20  fined, then the 
134a0 61 6c 74 65 72 6e 61 74 69 76 65 20 6d 65 6d 6f  alternative memo
134b0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 20  ry.** allocator 
134c0 69 73 20 65 6e 67 61 67 65 64 20 74 6f 20 68 61  is engaged to ha
134d0 6e 64 6c 65 20 61 6c 6c 20 6f 66 20 53 51 4c 69  ndle all of SQLi
134e0 74 65 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  tes memory alloc
134f0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20  ation needs..** 
13500 54 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  The first pointe
13510 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13520 69 6e 74 65 72 29 20 6d 75 73 74 20 62 65 20 61  inter) must be a
13530 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
13540 79 74 65 0a 2a 2a 20 62 6f 75 6e 64 61 72 79 20  yte.** boundary 
13550 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
13560 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
13570 20 77 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e   will be undefin
13580 65 64 2e 0a 2a 2a 20 54 68 65 20 6d 69 6e 69 6d  ed..** The minim
13590 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
135a0 7a 65 20 69 73 20 63 61 70 70 65 64 20 61 74 20  ze is capped at 
135b0 32 2a 2a 31 32 2e 20 52 65 61 73 6f 6e 61 62 6c  2**12. Reasonabl
135c0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 66 6f 72 20  e values.** for 
135d0 74 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f  the minimum allo
135e0 63 61 74 69 6f 6e 20 73 69 7a 65 20 61 72 65 20  cation size are 
135f0 32 2a 2a 35 20 74 68 72 6f 75 67 68 20 32 2a 2a  2**5 through 2**
13600 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  8.</dd>.**.** [[
13610 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
13620 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TEX]] <dt>SQLITE
13630 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64  _CONFIG_MUTEX</d
13640 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13650 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13660 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13670 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13680 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
13690 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
136a0 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
136b0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
136c0 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70   The argument sp
136d0 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72  ecifies.** alter
136e0 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c  native low-level
136f0 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20   mutex routines 
13700 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
13710 61 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78  ace.** the mutex
13720 20 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20   routines built 
13730 69 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20  into SQLite.)^  
13740 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20  ^SQLite makes a 
13750 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63  copy of the.** c
13760 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73  ontent of the [s
13770 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
13780 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20  hods] structure 
13790 62 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20  before the call 
137a0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  to.** [sqlite3_c
137b0 6f 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73  onfig()] returns
137c0 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20  . ^If SQLite is 
137d0 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
137e0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
137f0 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
13800 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
13810 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
13820 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65  on then.** the e
13830 6e 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73  ntire mutexing s
13840 75 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74  ubsystem is omit
13850 74 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69  ted from the bui
13860 6c 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c  ld and hence cal
13870 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ls to.** [sqlite
13880 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68  3_config()] with
13890 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
138a0 49 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75  IG_MUTEX configu
138b0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69  ration option wi
138c0 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51  ll.** return [SQ
138d0 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64  LITE_ERROR].</dd
138e0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
138f0 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58  _CONFIG_GETMUTEX
13900 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
13910 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 3c 2f 64  NFIG_GETMUTEX</d
13920 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13930 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13940 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13950 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13960 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
13970 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
13980 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
13990 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20  ods] structure. 
139a0 20 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   The.** [sqlite3
139b0 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 0a  _mutex_methods].
139c0 2a 2a 20 73 74 72 75 63 74 75 72 65 20 69 73 20  ** structure is 
139d0 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
139e0 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
139f0 64 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  d mutex routines
13a00 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
13a10 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
13a20 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
13a30 65 66 61 75 6c 74 20 6d 75 74 65 78 20 61 6c 6c  efault mutex all
13a40 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69  ocation.** routi
13a50 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70 70  nes with a wrapp
13a60 65 72 20 75 73 65 64 20 74 6f 20 74 72 61 63 6b  er used to track
13a70 20 6d 75 74 65 78 20 75 73 61 67 65 20 66 6f 72   mutex usage for
13a80 20 70 65 72 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20   performance.** 
13a90 70 72 6f 66 69 6c 69 6e 67 20 6f 72 20 74 65 73  profiling or tes
13aa0 74 69 6e 67 2c 20 66 6f 72 20 65 78 61 6d 70 6c  ting, for exampl
13ab0 65 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  e.   ^If SQLite 
13ac0 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
13ad0 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
13ae0 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
13af0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
13b00 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
13b10 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74 68  ption then.** th
13b20 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69 6e  e entire mutexin
13b30 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20 6f  g subsystem is o
13b40 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
13b50 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65 20  build and hence 
13b60 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c  calls to.** [sql
13b70 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77  ite3_config()] w
13b80 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43  ith the SQLITE_C
13b90 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 63  ONFIG_GETMUTEX c
13ba0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
13bb0 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75  ion will.** retu
13bc0 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
13bd0 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  ].</dd>.**.** [[
13be0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13bf0 4f 4b 41 53 49 44 45 5d 5d 20 3c 64 74 3e 53 51  OKASIDE]] <dt>SQ
13c00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  LITE_CONFIG_LOOK
13c10 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
13c20 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13c30 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
13c40 65 6e 74 73 20 74 68 61 74 20 64 65 74 65 72 6d  ents that determ
13c50 69 6e 65 20 74 68 65 20 64 65 66 61 75 6c 74 0a  ine the default.
13c60 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
13c70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 6c 6f 6f  tion for the loo
13c80 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c  kaside memory al
13c90 6c 6f 63 61 74 6f 72 20 6f 6e 20 65 61 63 68 0a  locator on each.
13ca0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
13cb0 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 66  nection].  The f
13cc0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13cd0 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
13ce0 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
13cf0 75 66 66 65 72 20 73 6c 6f 74 20 61 6e 64 20 74  uffer slot and t
13d00 68 65 20 73 65 63 6f 6e 64 20 69 73 20 74 68 65  he second is the
13d10 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
13d20 6f 74 73 20 61 6c 6c 6f 63 61 74 65 64 20 74 6f  ots allocated to
13d30 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20 63   each database c
13d40 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e 20 20 5e 28  onnection.)^  ^(
13d50 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73  This option sets
13d60 20 74 68 65 0a 2a 2a 20 3c 69 3e 64 65 66 61 75   the.** <i>defau
13d70 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61 73 69 64 65  lt</i> lookaside
13d80 20 73 69 7a 65 2e 20 54 68 65 20 5b 53 51 4c 49   size. The [SQLI
13d90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13da0 41 53 49 44 45 5d 0a 2a 2a 20 76 65 72 62 20 74  ASIDE].** verb t
13db0 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  o [sqlite3_db_co
13dc0 6e 66 69 67 28 29 5d 20 63 61 6e 20 62 65 20 75  nfig()] can be u
13dd0 73 65 64 20 74 6f 20 63 68 61 6e 67 65 20 74 68  sed to change th
13de0 65 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 63  e lookaside.** c
13df0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 6e 20  onfiguration on 
13e00 69 6e 64 69 76 69 64 75 61 6c 20 63 6f 6e 6e 65  individual conne
13e10 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a  ctions.)^ </dd>.
13e20 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
13e30 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 5d 5d 20  ONFIG_PCACHE2]] 
13e40 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13e50 47 5f 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a  G_PCACHE2</dt>.*
13e60 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
13e70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13e80 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13e90 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
13ea0 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65  to.** an [sqlite
13eb0 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73  3_pcache_methods
13ec0 32 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 69 73  2] object.  This
13ed0 20 6f 62 6a 65 63 74 20 73 70 65 63 69 66 69 65   object specifie
13ee0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
13ef0 2a 2a 20 74 6f 20 61 20 63 75 73 74 6f 6d 20 70  ** to a custom p
13f00 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d  age cache implem
13f10 65 6e 74 61 74 69 6f 6e 2e 29 5e 20 20 5e 53 51  entation.)^  ^SQ
13f20 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
13f30 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 62 6a 65  y of the.** obje
13f40 63 74 20 61 6e 64 20 75 73 65 73 20 69 74 20 66  ct and uses it f
13f50 6f 72 20 70 61 67 65 20 63 61 63 68 65 20 6d 65  or page cache me
13f60 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
13f70 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
13f80 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
13f90 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51  PCACHE2]] <dt>SQ
13fa0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50  LITE_CONFIG_GETP
13fb0 43 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c  CACHE2</dt>.** <
13fc0 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
13fd0 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
13fe0 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
13ff0 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
14000 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  an.** [sqlite3_p
14010 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20  cache_methods2] 
14020 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69 74 65 20  object.  SQLite 
14030 63 6f 70 69 65 73 20 6f 66 20 74 68 65 20 63 75  copies of the cu
14040 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61  rrent.** page ca
14050 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  che implementati
14060 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a  on into that obj
14070 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ect.)^ </dd>.**.
14080 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
14090 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c  IG_LOG]] <dt>SQL
140a0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f  ITE_CONFIG_LOG</
140b0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 20  dt>.** <dd> The 
140c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
140d0 47 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  G option is used
140e0 20 74 6f 20 63 6f 6e 66 69 67 75 72 65 20 74 68   to configure th
140f0 65 20 53 51 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62  e SQLite.** glob
14100 61 6c 20 5b 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a  al [error log]..
14110 2a 2a 20 28 5e 54 68 65 20 53 51 4c 49 54 45 5f  ** (^The SQLITE_
14120 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f  CONFIG_LOG optio
14130 6e 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75  n takes two argu
14140 6d 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72  ments: a pointer
14150 20 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f   to a.** functio
14160 6e 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69  n with a call si
14170 67 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28  gnature of void(
14180 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e  *)(void*,int,con
14190 73 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61  st char*), .** a
141a0 6e 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  nd a pointer to 
141b0 76 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75  void. ^If the fu
141c0 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69  nction pointer i
141d0 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69  s not NULL, it i
141e0 73 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20  s.** invoked by 
141f0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
14200 74 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20  to process each 
14210 6c 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20  logging event.  
14220 5e 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  ^If the.** funct
14230 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e  ion pointer is N
14240 55 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ULL, the [sqlite
14250 33 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61  3_log()] interfa
14260 63 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d  ce becomes a no-
14270 6f 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64  op..** ^The void
14280 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
14290 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
142a0 6d 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43  ment to SQLITE_C
142b0 4f 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20  ONFIG_LOG is.** 
142c0 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61  passed through a
142d0 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
142e0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70  meter to the app
142f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
14300 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74   logger.** funct
14310 69 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61  ion whenever tha
14320 74 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e  t function is in
14330 76 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63  voked.  ^The sec
14340 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
14350 0a 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66  .** the logger f
14360 75 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70  unction is a cop
14370 79 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70  y of the first p
14380 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
14390 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a  corresponding.**
143a0 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d   [sqlite3_log()]
143b0 20 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74   call and is int
143c0 65 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72  ended to be a [r
143d0 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61  esult code] or a
143e0 6e 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  n.** [extended r
143f0 65 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54  esult code].  ^T
14400 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
14410 65 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65  er passed to the
14420 20 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f   logger is.** lo
14430 67 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20  g message after 
14440 66 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b  formatting via [
14450 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
14460 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69  ()]..** The SQLi
14470 74 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72  te logging inter
14480 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e  face is not reen
14490 74 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65  trant; the logge
144a0 72 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75  r function.** su
144b0 70 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70  pplied by the ap
144c0 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e  plication must n
144d0 6f 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51  ot invoke any SQ
144e0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a  Lite interface..
144f0 2a 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68  ** In a multi-th
14500 72 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69  readed applicati
14510 6f 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  on, the applicat
14520 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
14530 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d  er.** function m
14540 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66  ust be threadsaf
14550 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  e. </dd>.**.** [
14560 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55  [SQLITE_CONFIG_U
14570 52 49 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  RI]] <dt>SQLITE_
14580 43 4f 4e 46 49 47 5f 55 52 49 0a 2a 2a 20 3c 64  CONFIG_URI.** <d
14590 64 3e 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  d>^(This option 
145a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
145b0 72 67 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20  rgument of type 
145c0 69 6e 74 2e 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f  int. If non-zero
145d0 2c 20 74 68 65 6e 0a 2a 2a 20 55 52 49 20 68 61  , then.** URI ha
145e0 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c  ndling is global
145f0 6c 79 20 65 6e 61 62 6c 65 64 2e 20 49 66 20 74  ly enabled. If t
14600 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  he parameter is 
14610 7a 65 72 6f 2c 20 74 68 65 6e 20 55 52 49 20 68  zero, then URI h
14620 61 6e 64 6c 69 6e 67 0a 2a 2a 20 69 73 20 67 6c  andling.** is gl
14630 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64 2e  obally disabled.
14640 29 5e 20 5e 49 66 20 55 52 49 20 68 61 6e 64 6c  )^ ^If URI handl
14650 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20  ing is globally 
14660 65 6e 61 62 6c 65 64 2c 20 61 6c 6c 20 66 69 6c  enabled, all fil
14670 65 6e 61 6d 65 73 0a 2a 2a 20 70 61 73 73 65 64  enames.** passed
14680 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
14690 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
146a0 70 65 6e 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  pen_v2()], [sqli
146b0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 6f 72  te3_open16()] or
146c0 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 61 73  .** specified as
146d0 20 70 61 72 74 20 6f 66 20 5b 41 54 54 41 43 48   part of [ATTACH
146e0 5d 20 63 6f 6d 6d 61 6e 64 73 20 61 72 65 20 69  ] commands are i
146f0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 52  nterpreted as UR
14700 49 73 2c 20 72 65 67 61 72 64 6c 65 73 73 0a 2a  Is, regardless.*
14710 2a 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  * of whether or 
14720 6e 6f 74 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  not the [SQLITE_
14730 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
14740 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 20 64  s set when the d
14750 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65  atabase.** conne
14760 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64 2e  ction is opened.
14770 20 5e 49 66 20 69 74 20 69 73 20 67 6c 6f 62 61   ^If it is globa
14780 6c 6c 79 20 64 69 73 61 62 6c 65 64 2c 20 66 69  lly disabled, fi
14790 6c 65 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20 6f  lenames are.** o
147a0 6e 6c 79 20 69 6e 74 65 72 70 72 65 74 65 64 20  nly interpreted 
147b0 61 73 20 55 52 49 73 20 69 66 20 74 68 65 20 53  as URIs if the S
147c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 20 66  QLITE_OPEN_URI f
147d0 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
147e0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
147f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
14800 65 6e 65 64 2e 20 5e 28 42 79 20 64 65 66 61 75  ened. ^(By defau
14810 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  lt, URI handling
14820 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20   is globally.** 
14830 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20 64 65  disabled. The de
14840 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61 79 20  fault value may 
14850 62 65 20 63 68 61 6e 67 65 64 20 62 79 20 63 6f  be changed by co
14860 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74 68 65  mpiling with the
14870 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f  .** [SQLITE_USE_
14880 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65 66 69  URI] symbol defi
14890 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ned.)^.**.** [[S
148a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56  QLITE_CONFIG_COV
148b0 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e  ERING_INDEX_SCAN
148c0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
148d0 4e 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e  NFIG_COVERING_IN
148e0 44 45 58 5f 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e  DEX_SCAN.** <dd>
148f0 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
14900 65 73 20 61 20 73 69 6e 67 6c 65 20 69 6e 74 65  es a single inte
14910 67 65 72 20 61 72 67 75 6d 65 6e 74 20 77 68 69  ger argument whi
14920 63 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65  ch is interprete
14930 64 20 61 73 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61  d as.** a boolea
14940 6e 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 65 6e  n in order to en
14950 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
14960 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72  the use of cover
14970 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f 72 0a  ing indices for.
14980 2a 2a 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63  ** full table sc
14990 61 6e 73 20 69 6e 20 74 68 65 20 71 75 65 72 79  ans in the query
149a0 20 6f 70 74 69 6d 69 7a 65 72 2e 20 20 5e 54 68   optimizer.  ^Th
149b0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
149c0 67 20 69 73 20 64 65 74 65 72 6d 69 6e 65 64 0a  g is determined.
149d0 2a 2a 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  ** by the [SQLIT
149e0 45 5f 41 4c 4c 4f 57 5f 43 4f 56 45 52 49 4e 47  E_ALLOW_COVERING
149f0 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 20 63 6f 6d  _INDEX_SCAN] com
14a00 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
14a10 2c 20 6f 72 20 69 73 20 22 6f 6e 22 0a 2a 2a 20  , or is "on".** 
14a20 69 66 20 74 68 61 74 20 63 6f 6d 70 69 6c 65 2d  if that compile-
14a30 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 6f  time option is o
14a40 6d 69 74 74 65 64 2e 0a 2a 2a 20 54 68 65 20 61  mitted..** The a
14a50 62 69 6c 69 74 79 20 74 6f 20 64 69 73 61 62 6c  bility to disabl
14a60 65 20 74 68 65 20 75 73 65 20 6f 66 20 63 6f 76  e the use of cov
14a70 65 72 69 6e 67 20 69 6e 64 69 63 65 73 20 66 6f  ering indices fo
14a80 72 20 66 75 6c 6c 20 74 61 62 6c 65 20 73 63 61  r full table sca
14a90 6e 73 0a 2a 2a 20 69 73 20 62 65 63 61 75 73 65  ns.** is because
14aa0 20 73 6f 6d 65 20 69 6e 63 6f 72 72 65 63 74 6c   some incorrectl
14ab0 79 20 63 6f 64 65 64 20 6c 65 67 61 63 79 20 61  y coded legacy a
14ac0 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 69 67 68  pplications migh
14ad0 74 20 6d 61 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a  t malfunction.**
14ae0 20 77 68 65 6e 20 74 68 65 20 6f 70 74 69 6d 69   when the optimi
14af0 7a 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  zation is enable
14b00 64 2e 20 20 50 72 6f 76 69 64 69 6e 67 20 74 68  d.  Providing th
14b10 65 20 61 62 69 6c 69 74 79 20 74 6f 0a 2a 2a 20  e ability to.** 
14b20 64 69 73 61 62 6c 65 20 74 68 65 20 6f 70 74 69  disable the opti
14b30 6d 69 7a 61 74 69 6f 6e 20 61 6c 6c 6f 77 73 20  mization allows 
14b40 74 68 65 20 6f 6c 64 65 72 2c 20 62 75 67 67 79  the older, buggy
14b50 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64   application cod
14b60 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74  e to work.** wit
14b70 68 6f 75 74 20 63 68 61 6e 67 65 20 65 76 65 6e  hout change even
14b80 20 77 69 74 68 20 6e 65 77 65 72 20 76 65 72 73   with newer vers
14b90 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ions of SQLite..
14ba0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
14bb0 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 5d 20 5b  ONFIG_PCACHE]] [
14bc0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
14bd0 45 54 50 43 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64  ETPCACHE]].** <d
14be0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
14bf0 50 43 41 43 48 45 20 61 6e 64 20 53 51 4c 49 54  PCACHE and SQLIT
14c00 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
14c10 48 45 0a 2a 2a 20 3c 64 64 3e 20 54 68 65 73 65  HE.** <dd> These
14c20 20 6f 70 74 69 6f 6e 73 20 61 72 65 20 6f 62 73   options are obs
14c30 6f 6c 65 74 65 20 61 6e 64 20 73 68 6f 75 6c 64  olete and should
14c40 20 6e 6f 74 20 62 65 20 75 73 65 64 20 62 79 20   not be used by 
14c50 6e 65 77 20 63 6f 64 65 2e 0a 2a 2a 20 54 68 65  new code..** The
14c60 79 20 61 72 65 20 72 65 74 61 69 6e 65 64 20 66  y are retained f
14c70 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d  or backwards com
14c80 70 61 74 69 62 69 6c 69 74 79 20 62 75 74 20 61  patibility but a
14c90 72 65 20 6e 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a  re now no-ops..*
14ca0 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
14cb0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51  SQLITE_CONFIG_SQ
14cc0 4c 4c 4f 47 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  LLOG]].** <dt>SQ
14cd0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
14ce0 4f 47 0a 2a 2a 20 3c 64 64 3e 54 68 69 73 20 6f  OG.** <dd>This o
14cf0 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76  ption is only av
14d00 61 69 6c 61 62 6c 65 20 69 66 20 73 71 6c 69 74  ailable if sqlit
14d10 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
14d20 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  th the.** [SQLIT
14d30 45 5f 45 4e 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d  E_ENABLE_SQLLOG]
14d40 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d   pre-processor m
14d50 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 20 54 68  acro defined. Th
14d60 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
14d70 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61 20   should.** be a 
14d80 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 66 75 6e  pointer to a fun
14d90 63 74 69 6f 6e 20 6f 66 20 74 79 70 65 20 76 6f  ction of type vo
14da0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
14db0 74 65 33 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  te3*,const char*
14dc0 2c 20 69 6e 74 29 2e 0a 2a 2a 20 54 68 65 20 73  , int)..** The s
14dd0 65 63 6f 6e 64 20 73 68 6f 75 6c 64 20 62 65 20  econd should be 
14de0 6f 66 20 74 79 70 65 20 28 76 6f 69 64 2a 29 2e  of type (void*).
14df0 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73   The callback is
14e00 20 69 6e 76 6f 6b 65 64 20 62 79 20 74 68 65 20   invoked by the 
14e10 6c 69 62 72 61 72 79 0a 2a 2a 20 69 6e 20 74 68  library.** in th
14e20 72 65 65 20 73 65 70 61 72 61 74 65 20 63 69 72  ree separate cir
14e30 63 75 6d 73 74 61 6e 63 65 73 2c 20 69 64 65 6e  cumstances, iden
14e40 74 69 66 69 65 64 20 62 79 20 74 68 65 20 76 61  tified by the va
14e50 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
14e60 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61 72 61  e.** fourth para
14e70 6d 65 74 65 72 2e 20 49 66 20 74 68 65 20 66 6f  meter. If the fo
14e80 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14e90 73 20 30 2c 20 74 68 65 6e 20 74 68 65 20 64 61  s 0, then the da
14ea0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14eb0 6e 0a 2a 2a 20 70 61 73 73 65 64 20 61 73 20 74  n.** passed as t
14ec0 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
14ed0 6e 74 20 68 61 73 20 6a 75 73 74 20 62 65 65 6e  nt has just been
14ee0 20 6f 70 65 6e 65 64 2e 20 54 68 65 20 74 68 69   opened. The thi
14ef0 72 64 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 70  rd argument.** p
14f00 6f 69 6e 74 73 20 74 6f 20 61 20 62 75 66 66 65  oints to a buffe
14f10 72 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  r containing the
14f20 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6d 61 69   name of the mai
14f30 6e 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2e  n database file.
14f40 20 49 66 20 74 68 65 0a 2a 2a 20 66 6f 75 72 74   If the.** fourt
14f50 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 31  h parameter is 1
14f60 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20 73  , then the SQL s
14f70 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20 74 68  tatement that th
14f80 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
14f90 72 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20 68  r.** points to h
14fa0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 65 78 65  as just been exe
14fb0 63 75 74 65 64 2e 20 4f 72 2c 20 69 66 20 74 68  cuted. Or, if th
14fc0 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
14fd0 65 72 20 69 73 20 32 2c 20 74 68 65 6e 0a 2a 2a  er is 2, then.**
14fe0 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   the connection 
14ff0 62 65 69 6e 67 20 70 61 73 73 65 64 20 61 73 20  being passed as 
15000 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
15010 65 74 65 72 20 69 73 20 62 65 69 6e 67 20 63 6c  eter is being cl
15020 6f 73 65 64 2e 20 54 68 65 0a 2a 2a 20 74 68 69  osed. The.** thi
15030 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
15040 70 61 73 73 65 64 20 4e 55 4c 4c 20 49 6e 20 74  passed NULL In t
15050 68 69 73 20 63 61 73 65 2e 20 20 41 6e 20 65 78  his case.  An ex
15060 61 6d 70 6c 65 20 6f 66 20 75 73 69 6e 67 20 74  ample of using t
15070 68 69 73 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  his.** configura
15080 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 63 61 6e 20  tion option can 
15090 62 65 20 73 65 65 6e 20 69 6e 20 74 68 65 20 22  be seen in the "
150a0 74 65 73 74 5f 73 71 6c 6c 6f 67 2e 63 22 20 73  test_sqllog.c" s
150b0 6f 75 72 63 65 20 66 69 6c 65 20 69 6e 0a 2a 2a  ource file in.**
150c0 20 74 68 65 20 63 61 6e 6f 6e 69 63 61 6c 20 53   the canonical S
150d0 51 4c 69 74 65 20 73 6f 75 72 63 65 20 74 72 65  QLite source tre
150e0 65 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  e.</dd>.**.** [[
150f0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d  SQLITE_CONFIG_MM
15100 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74  AP_SIZE]].** <dt
15110 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
15120 4d 41 50 5f 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  MAP_SIZE.** <dd>
15130 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  ^SQLITE_CONFIG_M
15140 4d 41 50 5f 53 49 5a 45 20 74 61 6b 65 73 20 74  MAP_SIZE takes t
15150 77 6f 20 36 34 2d 62 69 74 20 69 6e 74 65 67 65  wo 64-bit intege
15160 72 20 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  r (sqlite3_int64
15170 29 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74  ) values.** that
15180 20 61 72 65 20 74 68 65 20 64 65 66 61 75 6c 74   are the default
15190 20 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74   mmap size limit
151a0 20 28 74 68 65 20 64 65 66 61 75 6c 74 20 73 65   (the default se
151b0 74 74 69 6e 67 20 66 6f 72 0a 2a 2a 20 5b 50 52  tting for.** [PR
151c0 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 29  AGMA mmap_size])
151d0 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75 6d   and the maximum
151e0 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69   allowed mmap si
151f0 7a 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  ze limit..** ^Th
15200 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
15210 67 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  g can be overrid
15220 64 65 6e 20 62 79 20 65 61 63 68 20 64 61 74 61  den by each data
15230 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
15240 75 73 69 6e 67 0a 2a 2a 20 65 69 74 68 65 72 20  using.** either 
15250 74 68 65 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  the [PRAGMA mmap
15260 5f 73 69 7a 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20  _size] command, 
15270 6f 72 20 62 79 20 75 73 69 6e 67 20 74 68 65 0a  or by using the.
15280 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
15290 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65  _MMAP_SIZE] file
152a0 20 63 6f 6e 74 72 6f 6c 2e 20 20 5e 28 54 68 65   control.  ^(The
152b0 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
152c0 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 63 61   mmap size.** ca
152d0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 20  nnot be changed 
152e0 61 74 20 72 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f  at run-time.  No
152f0 72 20 6d 61 79 20 74 68 65 20 6d 61 78 69 6d 75  r may the maximu
15300 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73  m allowed mmap s
15310 69 7a 65 0a 2a 2a 20 65 78 63 65 65 64 20 74 68  ize.** exceed th
15320 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d  e compile-time m
15330 61 78 69 6d 75 6d 20 6d 6d 61 70 20 73 69 7a 65  aximum mmap size
15340 20 73 65 74 20 62 79 20 74 68 65 0a 2a 2a 20 5b   set by the.** [
15350 53 51 4c 49 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f  SQLITE_MAX_MMAP_
15360 53 49 5a 45 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  SIZE] compile-ti
15370 6d 65 20 6f 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20  me option.)^.** 
15380 5e 49 66 20 65 69 74 68 65 72 20 61 72 67 75 6d  ^If either argum
15390 65 6e 74 20 74 6f 20 74 68 69 73 20 6f 70 74 69  ent to this opti
153a0 6f 6e 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  on is negative, 
153b0 74 68 65 6e 20 74 68 61 74 20 61 72 67 75 6d 65  then that argume
153c0 6e 74 20 69 73 0a 2a 2a 20 63 68 61 6e 67 65 64  nt is.** changed
153d0 20 74 6f 20 69 74 73 20 63 6f 6d 70 69 6c 65 2d   to its compile-
153e0 74 69 6d 65 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  time default..**
153f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
15400 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49  FIG_WIN32_HEAPSI
15410 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  ZE]].** <dt>SQLI
15420 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f  TE_CONFIG_WIN32_
15430 48 45 41 50 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e  HEAPSIZE.** <dd>
15440 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  ^This option is 
15450 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
15460 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
15470 69 6c 65 64 20 66 6f 72 20 57 69 6e 64 6f 77 73  iled for Windows
15480 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51  .** with the [SQ
15490 4c 49 54 45 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f  LITE_WIN32_MALLO
154a0 43 5d 20 70 72 65 2d 70 72 6f 63 65 73 73 6f 72  C] pre-processor
154b0 20 6d 61 63 72 6f 20 64 65 66 69 6e 65 64 2e 0a   macro defined..
154c0 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
154d0 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 20  _WIN32_HEAPSIZE 
154e0 74 61 6b 65 73 20 61 20 33 32 2d 62 69 74 20 75  takes a 32-bit u
154f0 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20  nsigned integer 
15500 76 61 6c 75 65 0a 2a 2a 20 74 68 61 74 20 73 70  value.** that sp
15510 65 63 69 66 69 65 73 20 74 68 65 20 6d 61 78 69  ecifies the maxi
15520 6d 75 6d 20 73 69 7a 65 20 6f 66 20 74 68 65 20  mum size of the 
15530 63 72 65 61 74 65 64 20 68 65 61 70 2e 0a 2a 2a  created heap..**
15540 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
15550 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
15560 53 49 4e 47 4c 45 54 48 52 45 41 44 20 20 31 20  SINGLETHREAD  1 
15570 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69   /* nil */.#defi
15580 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15590 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 20 20 32  _MULTITHREAD   2
155a0 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66    /* nil */.#def
155b0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
155c0 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 20 20 20  G_SERIALIZED    
155d0 33 20 20 2f 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65  3  /* nil */.#de
155e0 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
155f0 49 47 5f 4d 41 4c 4c 4f 43 20 20 20 20 20 20 20  IG_MALLOC       
15600 20 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d   4  /* sqlite3_m
15610 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  em_methods* */.#
15620 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
15630 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 20 20  NFIG_GETMALLOC  
15640 20 20 20 35 20 20 2f 2a 20 73 71 6c 69 74 65 33     5  /* sqlite3
15650 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  _mem_methods* */
15660 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15670 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 20 20  CONFIG_SCRATCH  
15680 20 20 20 20 20 36 20 20 2f 2a 20 76 6f 69 64 2a       6  /* void*
15690 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20  , int sz, int N 
156a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
156b0 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
156c0 48 45 20 20 20 20 20 37 20 20 2f 2a 20 76 6f 69  HE     7  /* voi
156d0 64 2a 2c 20 69 6e 74 20 73 7a 2c 20 69 6e 74 20  d*, int sz, int 
156e0 4e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  N */.#define SQL
156f0 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41 50 20  ITE_CONFIG_HEAP 
15700 20 20 20 20 20 20 20 20 20 38 20 20 2f 2a 20 76           8  /* v
15710 6f 69 64 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c  oid*, int nByte,
15720 20 69 6e 74 20 6d 69 6e 20 2a 2f 0a 23 64 65 66   int min */.#def
15730 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15740 47 5f 4d 45 4d 53 54 41 54 55 53 20 20 20 20 20  G_MEMSTATUS     
15750 39 20 20 2f 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f  9  /* boolean */
15760 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15770 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 20 20 20  CONFIG_MUTEX    
15780 20 20 20 20 31 30 20 20 2f 2a 20 73 71 6c 69 74      10  /* sqlit
15790 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
157a0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
157b0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55  ITE_CONFIG_GETMU
157c0 54 45 58 20 20 20 20 20 31 31 20 20 2f 2a 20 73  TEX     11  /* s
157d0 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74  qlite3_mutex_met
157e0 68 6f 64 73 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76  hods* */./* prev
157f0 69 6f 75 73 6c 79 20 53 51 4c 49 54 45 5f 43 4f  iously SQLITE_CO
15800 4e 46 49 47 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20  NFIG_CHUNKALLOC 
15810 31 32 20 77 68 69 63 68 20 69 73 20 6e 6f 77 20  12 which is now 
15820 75 6e 75 73 65 64 2e 20 2a 2f 20 0a 23 64 65 66  unused. */ .#def
15830 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15840 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 31  G_LOOKASIDE    1
15850 33 20 20 2f 2a 20 69 6e 74 20 69 6e 74 20 2a 2f  3  /* int int */
15860 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15870 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 20 20  CONFIG_PCACHE   
15880 20 20 20 20 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70      14  /* no-op
15890 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
158a0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
158b0 43 48 45 20 20 20 20 31 35 20 20 2f 2a 20 6e 6f  CHE    15  /* no
158c0 2d 6f 70 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  -op */.#define S
158d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
158e0 20 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a            16  /*
158f0 20 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f   xFunc, void* */
15900 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15910 43 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20  CONFIG_URI      
15920 20 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a      17  /* int *
15930 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15940 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 20  _CONFIG_PCACHE2 
15950 20 20 20 20 20 31 38 20 20 2f 2a 20 73 71 6c 69       18  /* sqli
15960 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f  te3_pcache_metho
15970 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ds2* */.#define 
15980 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
15990 54 50 43 41 43 48 45 32 20 20 20 31 39 20 20 2f  TPCACHE2   19  /
159a0 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65  * sqlite3_pcache
159b0 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23 64  _methods2* */.#d
159c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
159d0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
159e0 45 58 5f 53 43 41 4e 20 32 30 20 20 2f 2a 20 69  EX_SCAN 20  /* i
159f0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
15a00 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c  LITE_CONFIG_SQLL
15a10 4f 47 20 20 20 20 20 20 20 32 31 20 20 2f 2a 20  OG       21  /* 
15a20 78 53 71 6c 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a  xSqllog, void* *
15a30 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15a40 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a  _CONFIG_MMAP_SIZ
15a50 45 20 20 20 20 32 32 20 20 2f 2a 20 73 71 6c 69  E    22  /* sqli
15a60 74 65 33 5f 69 6e 74 36 34 2c 20 73 71 6c 69 74  te3_int64, sqlit
15a70 65 33 5f 69 6e 74 36 34 20 2a 2f 0a 23 64 65 66  e3_int64 */.#def
15a80 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15a90 47 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45  G_WIN32_HEAPSIZE
15aa0 20 20 20 20 20 20 32 33 20 20 2f 2a 20 69 6e 74        23  /* int
15ab0 20 6e 42 79 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a   nByte */../*.**
15ac0 20 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62   CAPI3REF: Datab
15ad0 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43  ase Connection C
15ae0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
15af0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
15b00 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
15b10 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
15b20 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
15b30 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
15b40 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
15b50 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61   as the second a
15b60 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b  rgument to the [
15b70 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
15b80 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  g()] interface..
15b90 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67  **.** New config
15ba0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
15bb0 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
15bc0 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20  future releases 
15bd0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78  of SQLite..** Ex
15be0 69 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  isting configura
15bf0 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67  tion options mig
15c00 68 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75  ht be discontinu
15c10 65 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ed.  Application
15c20 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63  s.** should chec
15c30 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
15c40 65 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  e from [sqlite3_
15c50 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20  db_config()] to 
15c60 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a  make sure that.*
15c70 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65  * the call worke
15c80 64 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  d.  ^The [sqlite
15c90 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69  3_db_config()] i
15ca0 6e 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65  nterface will re
15cb0 74 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65  turn a.** non-ze
15cc0 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ro [error code] 
15cd0 69 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65  if a discontinue
15ce0 64 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64  d or unsupported
15cf0 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15d00 70 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f  ption.** is invo
15d10 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  ked..**.** <dl>.
15d20 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42  ** <dt>SQLITE_DB
15d30 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
15d40 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54  </dt>.** <dd> ^T
15d50 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
15d60 20 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61   three additiona
15d70 6c 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  l arguments that
15d80 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a   determine the .
15d90 2a 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  ** [lookaside me
15da0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20  mory allocator] 
15db0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f  configuration fo
15dc0 72 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  r the [database 
15dd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20  connection]..** 
15de0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
15df0 65 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70  ent (the third p
15e00 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
15e10 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
15e20 5d 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65  ] is a.** pointe
15e30 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75  r to a memory bu
15e40 66 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20  ffer to use for 
15e50 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15e60 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
15e70 61 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74  argument after t
15e80 68 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  he SQLITE_DBCONF
15e90 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72  IG_LOOKASIDE ver
15ea0 62 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c  b.** may be NULL
15eb0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53   in which case S
15ec0 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63  QLite will alloc
15ed0 61 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61  ate the.** looka
15ee0 73 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65  side buffer itse
15ef0 6c 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  lf using [sqlite
15f00 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68  3_malloc()]. ^Th
15f10 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
15f20 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
15f30 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
15f40 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20  de buffer slot. 
15f50 20 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75   ^The third argu
15f60 6d 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62  ment is the numb
15f70 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20  er of.** slots. 
15f80 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   The size of the
15f90 20 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66   buffer in the f
15fa0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75  irst argument mu
15fb0 73 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68  st be greater th
15fc0 61 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74  an.** or equal t
15fd0 6f 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66  o the product of
15fe0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
15ff0 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e  third arguments.
16000 20 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20    The buffer.** 
16010 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20  must be aligned 
16020 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
16030 6e 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20  ndary.  ^If the 
16040 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
16050 74 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43  to.** SQLITE_DBC
16060 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
16070 69 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c  is not a multipl
16080 65 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e  e of 8, it is in
16090 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e  ternally.** roun
160a0 64 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20  ded down to the 
160b0 6e 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c  next smaller mul
160c0 74 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54  tiple of 8.  ^(T
160d0 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
160e0 6f 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ory.** configura
160f0 74 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62  tion for a datab
16100 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
16110 61 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67  an only be chang
16120 65 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20  ed when that.** 
16130 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f  connection is no
16140 74 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e  t currently usin
16150 67 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  g lookaside memo
16160 72 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20  ry, or in other 
16170 77 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68  words.** when th
16180 65 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65  e "current value
16190 22 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  " returned by.**
161a0 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61   [sqlite3_db_sta
161b0 74 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43  tus](D,[SQLITE_C
161c0 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d  ONFIG_LOOKASIDE]
161d0 2c 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a  ,...) is zero..*
161e0 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f  * Any attempt to
161f0 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b   change the look
16200 61 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e  aside memory con
16210 66 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20  figuration when 
16220 6c 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d  lookaside.** mem
16230 6f 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65  ory is in use le
16240 61 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75  aves the configu
16250 72 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64  ration unchanged
16260 20 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a   and returns .**
16270 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29   [SQLITE_BUSY].)
16280 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74  ^</dd>.**.** <dt
16290 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47  >SQLITE_DBCONFIG
162a0 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74  _ENABLE_FKEY</dt
162b0 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
162c0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
162d0 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
162e0 62 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d  ble the enforcem
162f0 65 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69  ent of.** [forei
16300 67 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e  gn key constrain
16310 74 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75  ts].  There shou
16320 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
16330 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
16340 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16350 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
16360 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
16370 6f 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66  o disable FK enf
16380 6f 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73  orcement,.** pos
16390 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20  itive to enable 
163a0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f  FK enforcement o
163b0 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65  r negative to le
163c0 61 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65  ave FK enforceme
163d0 6e 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e  nt.** unchanged.
163e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
163f0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
16400 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
16410 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
16420 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
16430 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
16440 65 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65  ether FK enforce
16450 6d 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f  ment is off or o
16460 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74  n.** following t
16470 68 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73  his call.  The s
16480 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16490 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f  may be a NULL po
164a0 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69  inter, in.** whi
164b0 63 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65  ch case the FK e
164c0 6e 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69  nforcement setti
164d0 6e 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74  ng is not report
164e0 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a  ed back. </dd>.*
164f0 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
16500 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f  DBCONFIG_ENABLE_
16510 54 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20  TRIGGER</dt>.** 
16520 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
16530 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61  n is used to ena
16540 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b  ble or disable [
16550 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
16560 20 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54   triggers]..** T
16570 68 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74  here should be t
16580 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  wo additional ar
16590 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20  guments..** The 
165a0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69  first argument i
165b0 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
165c0 63 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62  ch is 0 to disab
165d0 6c 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20  le triggers,.** 
165e0 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62  positive to enab
165f0 6c 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e  le triggers or n
16600 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65  egative to leave
16610 20 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63   the setting unc
16620 68 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73  hanged..** The s
16630 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
16640 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
16650 61 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20  an integer into 
16660 77 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74  which.** is writ
16670 74 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e  ten 0 or 1 to in
16680 64 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74  dicate whether t
16690 72 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61  riggers are disa
166a0 62 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a  bled or enabled.
166b0 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69  ** following thi
166c0 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63  s call.  The sec
166d0 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61  ond parameter ma
166e0 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  y be a NULL poin
166f0 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68  ter, in.** which
16700 20 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65   case the trigge
16710 72 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  r setting is not
16720 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16730 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c  </dd>.**.** </dl
16740 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
16750 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
16760 4b 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30  KASIDE       100
16770 31 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20  1  /* void* int 
16780 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  int */.#define S
16790 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45  QLITE_DBCONFIG_E
167a0 4e 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31  NABLE_FKEY     1
167b0 30 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a  002  /* int int*
167c0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
167d0 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42  TE_DBCONFIG_ENAB
167e0 4c 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33  LE_TRIGGER  1003
167f0 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f    /* int int* */
16800 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  .../*.** CAPI3RE
16810 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73  F: Enable Or Dis
16820 61 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65  able Extended Re
16830 73 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a  sult Codes.**.**
16840 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
16850 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
16860 64 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e  des() routine en
16870 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
16880 73 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64  s the.** [extend
16890 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
168a0 20 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69   feature of SQLi
168b0 74 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65  te. ^The extende
168c0 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65  d result.** code
168d0 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62  s are disabled b
168e0 79 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69  y default for hi
168f0 73 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69  storical compati
16900 62 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73  bility..*/.int s
16910 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
16920 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c  result_codes(sql
16930 69 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66  ite3*, int onoff
16940 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
16950 45 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20  EF: Last Insert 
16960 52 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63  Rowid.**.** ^Eac
16970 68 20 65 6e 74 72 79 20 69 6e 20 6d 6f 73 74 20  h entry in most 
16980 53 51 4c 69 74 65 20 74 61 62 6c 65 73 20 28 65  SQLite tables (e
16990 78 63 65 70 74 20 66 6f 72 20 5b 57 49 54 48 4f  xcept for [WITHO
169a0 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c 65 73  UT ROWID] tables
169b0 29 0a 2a 2a 20 68 61 73 20 61 20 75 6e 69 71 75  ).** has a uniqu
169c0 65 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 0a  e 64-bit signed.
169d0 2a 2a 20 69 6e 74 65 67 65 72 20 6b 65 79 20 63  ** integer key c
169e0 61 6c 6c 65 64 20 74 68 65 20 5b 52 4f 57 49 44  alled the [ROWID
169f0 20 7c 20 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68   | "rowid"]. ^Th
16a00 65 20 72 6f 77 69 64 20 69 73 20 61 6c 77 61 79  e rowid is alway
16a10 73 20 61 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61  s available.** a
16a20 73 20 61 6e 20 75 6e 64 65 63 6c 61 72 65 64 20  s an undeclared 
16a30 63 6f 6c 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57  column named ROW
16a40 49 44 2c 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57  ID, OID, or _ROW
16a50 49 44 5f 20 61 73 20 6c 6f 6e 67 20 61 73 20 74  ID_ as long as t
16a60 68 6f 73 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72  hose.** names ar
16a70 65 20 6e 6f 74 20 61 6c 73 6f 20 75 73 65 64 20  e not also used 
16a80 62 79 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65  by explicitly de
16a90 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20  clared columns. 
16aa0 5e 49 66 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65  ^If.** the table
16ab0 20 68 61 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66   has a column of
16ac0 20 74 79 70 65 20 5b 49 4e 54 45 47 45 52 20 50   type [INTEGER P
16ad0 52 49 4d 41 52 59 20 4b 45 59 5d 20 74 68 65 6e  RIMARY KEY] then
16ae0 20 74 68 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20   that column.** 
16af0 69 73 20 61 6e 6f 74 68 65 72 20 61 6c 69 61 73  is another alias
16b00 20 66 6f 72 20 74 68 65 20 72 6f 77 69 64 2e 0a   for the rowid..
16b10 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
16b20 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
16b30 6f 77 69 64 28 44 29 20 69 6e 74 65 72 66 61 63  owid(D) interfac
16b40 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72  e returns the [r
16b50 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 0a 2a 2a  owid] of the .**
16b60 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 73 75 63   most recent suc
16b70 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d  cessful [INSERT]
16b80 20 69 6e 74 6f 20 61 20 72 6f 77 69 64 20 74 61   into a rowid ta
16b90 62 6c 65 20 6f 72 20 5b 76 69 72 74 75 61 6c 20  ble or [virtual 
16ba0 74 61 62 6c 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74  table].** on dat
16bb0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
16bc0 20 44 2e 0a 2a 2a 20 5e 49 6e 73 65 72 74 73 20   D..** ^Inserts 
16bd0 69 6e 74 6f 20 5b 57 49 54 48 4f 55 54 20 52 4f  into [WITHOUT RO
16be0 57 49 44 5d 20 74 61 62 6c 65 73 20 61 72 65 20  WID] tables are 
16bf0 6e 6f 74 20 72 65 63 6f 72 64 65 64 2e 0a 2a 2a  not recorded..**
16c00 20 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66   ^If no successf
16c10 75 6c 20 5b 49 4e 53 45 52 54 5d 73 20 69 6e 74  ul [INSERT]s int
16c20 6f 20 72 6f 77 69 64 20 74 61 62 6c 65 73 0a 2a  o rowid tables.*
16c30 2a 20 68 61 76 65 20 65 76 65 72 20 6f 63 63 75  * have ever occu
16c40 72 72 65 64 20 6f 6e 20 74 68 65 20 64 61 74 61  rred on the data
16c50 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
16c60 44 2c 20 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69  D, .** then sqli
16c70 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
16c80 72 6f 77 69 64 28 44 29 20 72 65 74 75 72 6e 73  rowid(D) returns
16c90 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49   zero..**.** ^(I
16ca0 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 6f 63  f an [INSERT] oc
16cb0 63 75 72 73 20 77 69 74 68 69 6e 20 61 20 74 72  curs within a tr
16cc0 69 67 67 65 72 20 6f 72 20 77 69 74 68 69 6e 20  igger or within 
16cd0 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
16ce0 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74 68 65  ].** method, the
16cf0 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  n this routine w
16d00 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65 20 5b  ill return the [
16d10 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20 69 6e  rowid] of the in
16d20 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20 61 73  serted.** row as
16d30 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
16d40 67 67 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20  gger or virtual 
16d50 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69 73 20  table method is 
16d60 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75 74 20  running..** But 
16d70 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67 65 72  once the trigger
16d80 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
16d90 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c 20 74  e method ends, t
16da0 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
16db0 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20 72 6f  d .** by this ro
16dc0 75 74 69 6e 65 20 72 65 76 65 72 74 73 20 74 6f  utine reverts to
16dd0 20 77 68 61 74 20 69 74 20 77 61 73 20 62 65 66   what it was bef
16de0 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72 20  ore the trigger 
16df0 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20 74 61  or virtual.** ta
16e00 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67 61 6e  ble method began
16e10 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49  .)^.**.** ^An [I
16e20 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61 69 6c  NSERT] that fail
16e30 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e 73 74  s due to a const
16e40 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20  raint violation 
16e50 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75 63 63  is not a.** succ
16e60 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20  essful [INSERT] 
16e70 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63 68 61  and does not cha
16e80 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20 72 65  nge the value re
16e90 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 0a 2a  turned by this.*
16ea0 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54 68 75  * routine.  ^Thu
16eb0 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41 49 4c  s INSERT OR FAIL
16ec0 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47 4e 4f  , INSERT OR IGNO
16ed0 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20 52 4f  RE, INSERT OR RO
16ee0 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49  LLBACK,.** and I
16ef0 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54 20 6d  NSERT OR ABORT m
16f00 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73 20 74  ake no changes t
16f10 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  o the return val
16f20 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20 72 6f  ue of this.** ro
16f30 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65 69 72  utine when their
16f40 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 73   insertion fails
16f50 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45 52 54  .  ^(When INSERT
16f60 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a 20 65   OR REPLACE.** e
16f70 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f 6e 73  ncounters a cons
16f80 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e  traint violation
16f90 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 66 61  , it does not fa
16fa0 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e 53 45  il.  The.** INSE
16fb0 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74 6f 20  RT continues to 
16fc0 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74 65 72  completion after
16fd0 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73 20 74   deleting rows t
16fe0 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20 74 68  hat caused.** th
16ff0 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70 72 6f  e constraint pro
17000 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54 20 4f  blem so INSERT O
17010 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c 20 61  R REPLACE will a
17020 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a 2a 20  lways change.** 
17030 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
17040 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72 66 61   of this interfa
17050 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72  ce.)^.**.** ^For
17060 20 74 68 65 20 70 75 72 70 6f 73 65 73 20 6f 66   the purposes of
17070 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 61   this routine, a
17080 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20 63 6f  n [INSERT] is co
17090 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a 20 62  nsidered to.** b
170a0 65 20 73 75 63 63 65 73 73 66 75 6c 20 65 76 65  e successful eve
170b0 6e 20 69 66 20 69 74 20 69 73 20 73 75 62 73 65  n if it is subse
170c0 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64 20 62  quently rolled b
170d0 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ack..**.** This 
170e0 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63 63 65  function is acce
170f0 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20 73 74  ssible to SQL st
17100 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74 68 65  atements via the
17110 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65 72 74  .** [last_insert
17120 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66 75 6e  _rowid() SQL fun
17130 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
17140 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
17150 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20 6e 65  ad performs a ne
17160 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20 74 68  w [INSERT] on th
17170 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61 62 61  e same.** databa
17180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  se connection wh
17190 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ile the [sqlite3
171a0 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  _last_insert_row
171b0 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f  id()].** functio
171c0 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61 6e 64  n is running and
171d0 20 74 68 75 73 20 63 68 61 6e 67 65 73 20 74 68   thus changes th
171e0 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  e last insert [r
171f0 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  owid],.** then t
17200 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
17210 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 61  d by [sqlite3_la
17220 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28  st_insert_rowid(
17230 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65 64 69  )] is.** unpredi
17240 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67 68 74  ctable and might
17250 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74 68 65   not equal eithe
17260 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74 68 65  r the old or the
17270 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69 6e 73   new.** last ins
17280 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a  ert [rowid]..*/.
17290 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71  sqlite3_int64 sq
172a0 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72  lite3_last_inser
172b0 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65 33 2a  t_rowid(sqlite3*
172c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
172d0 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20 4e 75  EF: Count The Nu
172e0 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64  mber Of Rows Mod
172f0 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  ified.**.** ^Thi
17300 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72  s function retur
17310 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
17320 20 64 61 74 61 62 61 73 65 20 72 6f 77 73 20 74   database rows t
17330 68 61 74 20 77 65 72 65 20 63 68 61 6e 67 65 64  hat were changed
17340 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65 64 20  .** or inserted 
17350 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20 74 68  or deleted by th
17360 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20  e most recently 
17370 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20 73 74  completed SQL st
17380 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68  atement.** on th
17390 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
173a0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
173b0 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 70  d by the first p
173c0 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f  arameter..** ^(O
173d0 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68 61 74  nly changes that
173e0 20 61 72 65 20 64 69 72 65 63 74 6c 79 20 73 70   are directly sp
173f0 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 5b  ecified by the [
17400 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41 54 45  INSERT], [UPDATE
17410 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45 54 45  ],.** or [DELETE
17420 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72 65 20  ] statement are 
17430 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69 6c 69  counted.  Auxili
17440 61 72 79 20 63 68 61 6e 67 65 73 20 63 61 75 73  ary changes caus
17450 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67 65 72  ed by.** trigger
17460 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20 6b 65  s or [foreign ke
17470 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65 20 6e  y actions] are n
17480 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20 55 73  ot counted.)^ Us
17490 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
174a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
174b0 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 66  )] function to f
174c0 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20 6e 75  ind the total nu
174d0 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 0a  mber of changes.
174e0 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63 68 61  ** including cha
174f0 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20 74  nges caused by t
17500 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f 72 65  riggers and fore
17510 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 2e  ign key actions.
17520 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65 73 20  .**.** ^Changes 
17530 74 6f 20 61 20 76 69 65 77 20 74 68 61 74 20 61  to a view that a
17540 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62 79 20  re simulated by 
17550 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74  an [INSTEAD OF t
17560 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65 20 6e  rigger].** are n
17570 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c  ot counted.  Onl
17580 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63 68 61  y real table cha
17590 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74 65 64  nges are counted
175a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72 6f 77  ..**.** ^(A "row
175b0 20 63 68 61 6e 67 65 22 20 69 73 20 61 20 63 68   change" is a ch
175c0 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67 6c 65  ange to a single
175d0 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67 6c 65   row of a single
175e0 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73 65 64   table.** caused
175f0 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c 20 44   by an INSERT, D
17600 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41 54 45  ELETE, or UPDATE
17610 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52 6f 77   statement.  Row
17620 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20 63 68  s that.** are ch
17630 61 6e 67 65 64 20 61 73 20 73 69 64 65 20 65 66  anged as side ef
17640 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c 41 43  fects of [REPLAC
17650 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20 72 65  E] constraint re
17660 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c  solution,.** rol
17670 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70 72 6f  lback, ABORT pro
17680 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50 20 54  cessing, [DROP T
17690 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61 6e 79  ABLE], or by any
176a0 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68 61 6e   other.** mechan
176b0 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  isms do not coun
176c0 74 20 61 73 20 64 69 72 65 63 74 20 72 6f 77 20  t as direct row 
176d0 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a  changes.)^.**.**
176e0 20 41 20 22 74 72 69 67 67 65 72 20 63 6f 6e 74   A "trigger cont
176f0 65 78 74 22 20 69 73 20 61 20 73 63 6f 70 65 20  ext" is a scope 
17700 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74 68 61  of execution tha
17710 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a 2a 20  t begins and.** 
17720 65 6e 64 73 20 77 69 74 68 20 74 68 65 20 73 63  ends with the sc
17730 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45 41 54  ript of a [CREAT
17740 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17750 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53  ger]. .** Most S
17760 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72  QL statements ar
17770 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64 20 6f  e.** evaluated o
17780 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20 74 72  utside of any tr
17790 69 67 67 65 72 2e 20 20 54 68 69 73 20 69 73 20  igger.  This is 
177a0 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c 22 0a  the "top level".
177b0 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65  ** trigger conte
177c0 78 74 2e 20 20 49 66 20 61 20 74 72 69 67 67 65  xt.  If a trigge
177d0 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74 68 65  r fires from the
177e0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a   top level, a.**
177f0 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f 6e   new trigger con
17800 74 65 78 74 20 69 73 20 65 6e 74 65 72 65 64 20  text is entered 
17810 66 6f 72 20 74 68 65 20 64 75 72 61 74 69 6f 6e  for the duration
17820 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a 2a 20   of that one.** 
17830 74 72 69 67 67 65 72 2e 20 20 53 75 62 74 72 69  trigger.  Subtri
17840 67 67 65 72 73 20 63 72 65 61 74 65 20 73 75 62  ggers create sub
17850 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74 68 65  contexts for the
17860 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a  ir duration..**.
17870 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73 71 6c  ** ^Calling [sql
17880 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f 72 20  ite3_exec()] or 
17890 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
178a0 20 72 65 63 75 72 73 69 76 65 6c 79 20 64 6f 65   recursively doe
178b0 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74 65 20  s.** not create 
178c0 61 20 6e 65 77 20 74 72 69 67 67 65 72 20 63 6f  a new trigger co
178d0 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ntext..**.** ^Th
178e0 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
178f0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
17900 66 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61  f direct row cha
17910 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a 20 6d  nges in the.** m
17920 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52  ost recent INSER
17930 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45  T, UPDATE, or DE
17940 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74 20 77  LETE statement w
17950 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 0a 2a  ithin the same.*
17960 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  * trigger contex
17970 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20  t..**.** ^Thus, 
17980 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72 6f 6d  when called from
17990 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20   the top level, 
179a0 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  this function re
179b0 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  turns the.** num
179c0 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73 20 69  ber of changes i
179d0 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  n the most recen
179e0 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
179f0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
17a00 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72 72 65  hat also occurre
17a10 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c 65 76  d at the top lev
17a20 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20 74 68  el.  ^(Within th
17a30 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72 69 67  e body of a trig
17a40 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71 6c 69  ger,.** the sqli
17a50 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  te3_changes() in
17a60 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 63  terface can be c
17a70 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20 74 68  alled to find th
17a80 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63  e number of.** c
17a90 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f  hanges in the mo
17aa0 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17ab0 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20 55 50  leted INSERT, UP
17ac0 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a  DATE, or DELETE.
17ad0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74  ** statement wit
17ae0 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
17af0 74 68 65 20 73 61 6d 65 20 74 72 69 67 67 65 72  the same trigger
17b00 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68  ..** However, th
17b10 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72 6e 65  e number returne
17b20 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  d does not inclu
17b30 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 63 61  de changes.** ca
17b40 75 73 65 64 20 62 79 20 73 75 62 74 72 69 67 67  used by subtrigg
17b50 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73 65 20  ers since those 
17b60 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e 20 63  have their own c
17b70 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ontext.)^.**.** 
17b80 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
17b90 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e  lite3_total_chan
17ba0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17bb0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17bc0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
17bd0 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e 67 65   and the [change
17be0 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  s() SQL function
17bf0 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65  ]..**.** If a se
17c00 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61  parate thread ma
17c10 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74  kes changes on t
17c20 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65  he same database
17c30 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77   connection.** w
17c40 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 63 68  hile [sqlite3_ch
17c50 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e  anges()] is runn
17c60 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c  ing then the val
17c70 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 69  ue returned.** i
17c80 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20  s unpredictable 
17c90 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66  and not meaningf
17ca0 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ul..*/.int sqlit
17cb0 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c 69 74  e3_changes(sqlit
17cc0 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
17cd0 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e 75 6d  I3REF: Total Num
17ce0 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69  ber Of Rows Modi
17cf0 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  fied.**.** ^This
17d00 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
17d10 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
17d20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61 75 73  row changes caus
17d30 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d 2c 0a  ed by [INSERT],.
17d40 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72 20 5b  ** [UPDATE] or [
17d50 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
17d60 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b 64 61  ts since the [da
17d70 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
17d80 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e 0a 2a  n] was opened..*
17d90 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20 72 65  * ^(The count re
17da0 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
17db0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
17dc0 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 63  ) includes all c
17dd0 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d 20 61  hanges.** from a
17de0 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49 47 47  ll [CREATE TRIGG
17df0 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20 63 6f  ER | trigger] co
17e00 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61 6e 67  ntexts and chang
17e10 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20 5b 66  es made by.** [f
17e20 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f  oreign key actio
17e30 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ns]. However,.**
17e40 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65 73 20   the count does 
17e50 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e  not include chan
17e60 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  ges used to impl
17e70 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45 5d 20  ement [REPLACE] 
17e80 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a 2a 20  constraints,.** 
17e90 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f 72 20  do rollbacks or 
17ea0 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67  ABORT processing
17eb0 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42 4c 45  , or [DROP TABLE
17ec0 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20 20 54  ] processing.  T
17ed0 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f 65 73  he.** count does
17ee0 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72 6f 77   not include row
17ef0 73 20 6f 66 20 76 69 65 77 73 20 74 68 61 74 20  s of views that 
17f00 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45 41 44  fire an [INSTEAD
17f10 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a   OF trigger],.**
17f20 20 74 68 6f 75 67 68 20 69 66 20 74 68 65 20 49   though if the I
17f30 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
17f40 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20  r makes changes 
17f50 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68 6f 73  of its own, thos
17f60 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20 61 72  e changes .** ar
17f70 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20  e counted.)^.** 
17f80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 6f 74  ^The sqlite3_tot
17f90 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66 75 6e  al_changes() fun
17fa0 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74 68 65  ction counts the
17fb0 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f 6f 6e   changes as soon
17fc0 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61 74 65   as.** the state
17fd0 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65 73 20  ment that makes 
17fe0 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65 74 65  them is complete
17ff0 64 20 28 77 68 65 6e 20 74 68 65 20 73 74 61 74  d (when the stat
18000 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a 2a 20  ement handle.** 
18010 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71  is passed to [sq
18020 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
18030 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
18040 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53  ize()])..**.** S
18050 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
18060 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
18070 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a  interface, the.*
18080 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73  * [count_changes
18090 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68   pragma], and th
180a0 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e [total_changes
180b0 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
180c0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
180d0 61 72 61 74 65 20 74 68 72 65 61 64 20 6d 61 6b  arate thread mak
180e0 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20 74 68  es changes on th
180f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
18100 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68  connection.** wh
18110 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  ile [sqlite3_tot
18120 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 73  al_changes()] is
18130 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68   running then th
18140 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72  e value.** retur
18150 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69 63 74  ned is unpredict
18160 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61  able and not mea
18170 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20  ningful..*/.int 
18180 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
18190 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b  anges(sqlite3*);
181a0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
181b0 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20 4c 6f  : Interrupt A Lo
181c0 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65 72 79  ng-Running Query
181d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
181e0 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61 6e 79  ction causes any
181f0 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62 61 73   pending databas
18200 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 61  e operation to a
18210 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65 74 75  bort and.** retu
18220 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c 69 65  rn at its earlie
18230 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79 2e 20  st opportunity. 
18240 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  This routine is 
18250 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c  typically.** cal
18260 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73 65 20  led in response 
18270 74 6f 20 61 20 75 73 65 72 20 61 63 74 69 6f 6e  to a user action
18280 20 73 75 63 68 20 61 73 20 70 72 65 73 73 69 6e   such as pressin
18290 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72  g "Cancel".** or
182a0 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20 74 68   Ctrl-C where th
182b0 65 20 75 73 65 72 20 77 61 6e 74 73 20 61 20 6c  e user wants a l
182c0 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72 61 74  ong query operat
182d0 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a 20 69  ion to halt.** i
182e0 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a  mmediately..**.*
182f0 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20 74 6f  * ^It is safe to
18300 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18310 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65 61 64  ne from a thread
18320 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20   different from 
18330 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20 74 68  the.** thread th
18340 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  at is currently 
18350 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61 74 61  running the data
18360 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 2e 20  base operation. 
18370 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20 6e 6f   But it.** is no
18380 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74  t safe to call t
18390 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
183a0 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
183b0 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a  nection] that.**
183c0 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20 6d 69   is closed or mi
183d0 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f 72 65  ght close before
183e0 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
183f0 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a 2a 2a  pt() returns..**
18400 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c 20 6f  .** ^If an SQL o
18410 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65 72 79  peration is very
18420 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68 65 64   nearly finished
18430 20 61 74 20 74 68 65 20 74 69 6d 65 20 77 68 65   at the time whe
18440 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74  n.** sqlite3_int
18450 65 72 72 75 70 74 28 29 20 69 73 20 63 61 6c 6c  errupt() is call
18460 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69 67 68  ed, then it migh
18470 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20 6f 70  t not have an op
18480 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74 6f 20  portunity.** to 
18490 62 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61  be interrupted a
184a0 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69 6e 75  nd might continu
184b0 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e  e to completion.
184c0 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f  .**.** ^An SQL o
184d0 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20 69 73  peration that is
184e0 20 69 6e 74 65 72 72 75 70 74 65 64 20 77 69 6c   interrupted wil
184f0 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  l return [SQLITE
18500 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a 2a 20  _INTERRUPT]..** 
18510 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72 75 70  ^If the interrup
18520 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74 69 6f  ted SQL operatio
18530 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54 2c 20  n is an INSERT, 
18540 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
18550 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 73  E.** that is ins
18560 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69 74 20  ide an explicit 
18570 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65  transaction, the
18580 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74 72 61  n the entire tra
18590 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c  nsaction.** will
185a0 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20   be rolled back 
185b0 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a  automatically..*
185c0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
185d0 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 63  3_interrupt(D) c
185e0 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65 63 74  all is in effect
185f0 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72 72 65   until all curre
18600 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20  ntly running.** 
18610 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 6f  SQL statements o
18620 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
18630 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65  ection] D comple
18640 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20 53 51  te.  ^Any new SQ
18650 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
18660 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64  that are started
18670 20 61 66 74 65 72 20 74 68 65 20 73 71 6c 69 74   after the sqlit
18680 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63  e3_interrupt() c
18690 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65 20 74  all and before t
186a0 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 73  he .** running s
186b0 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63 68 65  tatements reache
186c0 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74 65 72  s zero are inter
186d0 72 75 70 74 65 64 20 61 73 20 69 66 20 74 68 65  rupted as if the
186e0 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20 72 75  y had been.** ru
186f0 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f 20 74  nning prior to t
18700 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
18710 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20 5e 4e  rupt() call.  ^N
18720 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ew SQL statement
18730 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74  s.** that are st
18740 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20  arted after the 
18750 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e  running statemen
18760 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65 73 20  t count reaches 
18770 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f 74 20  zero are.** not 
18780 65 66 66 65 63 74 65 64 20 62 79 20 74 68 65 20  effected by the 
18790 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
187a0 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  t()..** ^A call 
187b0 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  to sqlite3_inter
187c0 72 75 70 74 28 44 29 20 74 68 61 74 20 6f 63 63  rupt(D) that occ
187d0 75 72 73 20 77 68 65 6e 20 74 68 65 72 65 20 61  urs when there a
187e0 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a  re no running.**
187f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
18800 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64 20 68  is a no-op and h
18810 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f 6e 20  as no effect on 
18820 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
18830 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
18840 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
18850 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18860 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 0a 2a   call returns..*
18870 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61 74 61  *.** If the data
18880 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
18890 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b 73 71  closes while [sq
188a0 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28  lite3_interrupt(
188b0 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69 6e 67  )].** is running
188c0 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e 67 73   then bad things
188d0 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68 61 70   will likely hap
188e0 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c  pen..*/.void sql
188f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 73  ite3_interrupt(s
18900 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
18910 20 43 41 50 49 33 52 45 46 3a 20 44 65 74 65 72   CAPI3REF: Deter
18920 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c 20 53  mine If An SQL S
18930 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f 6d 70  tatement Is Comp
18940 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  lete.**.** These
18950 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
18960 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f 6d 6d  eful during comm
18970 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74 20 74  and-line input t
18980 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66 20 74  o determine if t
18990 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20  he.** currently 
189a0 65 6e 74 65 72 65 64 20 74 65 78 74 20 73 65 65  entered text see
189b0 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63 6f 6d  ms to form a com
189c0 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
189d0 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61 64 64  ent or.** if add
189e0 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20 69 73  itional input is
189f0 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65 20 73   needed before s
18a00 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78 74 20  ending the text 
18a10 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65 20 66  into.** SQLite f
18a20 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e 54 68  or parsing.  ^Th
18a30 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18a40 75 72 6e 20 31 20 69 66 20 74 68 65 20 69 6e 70  urn 1 if the inp
18a50 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61 70 70  ut string.** app
18a60 65 61 72 73 20 74 6f 20 62 65 20 61 20 63 6f 6d  ears to be a com
18a70 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74 65 6d  plete SQL statem
18a80 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65 6d 65  ent.  ^A stateme
18a90 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74 6f 20  nt is judged to 
18aa0 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 69  be.** complete i
18ab0 66 20 69 74 20 65 6e 64 73 20 77 69 74 68 20 61  f it ends with a
18ac0 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e   semicolon token
18ad0 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70 72   and is not a pr
18ae0 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77 65 6c  efix of a.** wel
18af0 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54 45 20  l-formed CREATE 
18b00 54 52 49 47 47 45 52 20 73 74 61 74 65 6d 65 6e  TRIGGER statemen
18b10 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20  t.  ^Semicolons 
18b20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64 64 65  that are embedde
18b30 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74 72 69  d within.** stri
18b40 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72 20 71  ng literals or q
18b50 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69 65 72  uoted identifier
18b60 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d 65 6e   names or commen
18b70 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e  ts are not.** in
18b80 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65 6e 73  dependent tokens
18b90 20 28 74 68 65 79 20 61 72 65 20 70 61 72 74 20   (they are part 
18ba0 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69 6e 20  of the token in 
18bb0 77 68 69 63 68 20 74 68 65 79 20 61 72 65 0a 2a  which they are.*
18bc0 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e 64 20  * embedded) and 
18bd0 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f 75 6e  thus do not coun
18be0 74 20 61 73 20 61 20 73 74 61 74 65 6d 65 6e 74  t as a statement
18bf0 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 57   terminator.  ^W
18c00 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61 6e 64  hitespace.** and
18c10 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74 20 66   comments that f
18c20 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61 6c 20  ollow the final 
18c30 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20 69 67  semicolon are ig
18c40 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  nored..**.** ^Th
18c50 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
18c60 75 72 6e 20 30 20 69 66 20 74 68 65 20 73 74 61  urn 0 if the sta
18c70 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f 6d 70  tement is incomp
18c80 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a 2a 20  lete.  ^If a.** 
18c90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
18ca0 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 53 51  n fails, then SQ
18cb0 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20 72 65  LITE_NOMEM is re
18cc0 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
18cd0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 64 6f  hese routines do
18ce0 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65 20 53   not parse the S
18cf0 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  QL statements th
18d00 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74 20 64  us.** will not d
18d10 65 74 65 63 74 20 73 79 6e 74 61 63 74 69 63 61  etect syntactica
18d20 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20 53 51  lly incorrect SQ
18d30 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 53 51  L..**.** ^(If SQ
18d40 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62 65 65  Lite has not bee
18d50 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 75 73  n initialized us
18d60 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ing [sqlite3_ini
18d70 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69 6f 72  tialize()] prior
18d80 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69 6e 67   .** to invoking
18d90 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18da0 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c 69 74  e16() then sqlit
18db0 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
18dc0 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75  is invoked.** au
18dd0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73  tomatically by s
18de0 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31  qlite3_complete1
18df0 36 28 29 2e 20 20 49 66 20 74 68 61 74 20 69 6e  6().  If that in
18e00 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66 61 69  itialization fai
18e10 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  ls,.** then the 
18e20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f  return value fro
18e30 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65  m sqlite3_comple
18e40 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65 20 6e  te16() will be n
18e50 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67 61 72  on-zero.** regar
18e60 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
18e70 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e 70 75   or not the inpu
18e80 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c 65 74  t SQL is complet
18e90 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69  e.)^.**.** The i
18ea0 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  nput to [sqlite3
18eb0 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d 75 73  _complete()] mus
18ec0 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d  t be a zero-term
18ed0 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 38 20  inated.** UTF-8 
18ee0 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68  string..**.** Th
18ef0 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  e input to [sqli
18f00 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
18f10 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72 6f  ] must be a zero
18f20 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55  -terminated.** U
18f30 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
18f40 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
18f50 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  r..*/.int sqlite
18f60 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e 73 74  3_complete(const
18f70 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69 6e 74   char *sql);.int
18f80 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18f90 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64 20 2a  e16(const void *
18fa0 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  sql);../*.** CAP
18fb0 49 33 52 45 46 3a 20 52 65 67 69 73 74 65 72 20  I3REF: Register 
18fc0 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20 48 61  A Callback To Ha
18fd0 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55 53 59  ndle SQLITE_BUSY
18fe0 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54   Errors.**.** ^T
18ff0 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74 73  his routine sets
19000 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
19010 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68 74 20  tion that might 
19020 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65  be invoked whene
19030 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65 6d 70  ver.** an attemp
19040 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70 65  t is made to ope
19050 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61 62  n a database tab
19060 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65 72 20  le that another 
19070 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70 72 6f  thread.** or pro
19080 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65 64 2e  cess has locked.
19090 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 62  .**.** ^If the b
190a0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  usy callback is 
190b0 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51 4c 49  NULL, then [SQLI
190c0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
190d0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
190e0 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72 6e 65  D].** is returne
190f0 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20 75 70  d immediately up
19100 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e 67 20  on encountering 
19110 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66 20 74  the lock.  ^If t
19120 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
19130 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  .** is not NULL,
19140 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61   then the callba
19150 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f  ck might be invo
19160 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61 72 67  ked with two arg
19170 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  uments..**.** ^T
19180 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
19190 74 20 74 6f 20 74 68 65 20 62 75 73 79 20 68 61  t to the busy ha
191a0 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70 79 20  ndler is a copy 
191b0 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70 6f 69  of the void* poi
191c0 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20 69 73  nter which.** is
191d0 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75 6d   the third argum
191e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
191f0 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e 20 20  usy_handler().  
19200 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
19210 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65 20 62  ment to.** the b
19220 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c  usy handler call
19230 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75 6d 62  back is the numb
19240 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68 61 74  er of times that
19250 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19260 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 69 6e  r has.** been in
19270 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73 20 6c  voked for this l
19280 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ocking event.  ^
19290 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79 20 63  If the.** busy c
192a0 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20  allback returns 
192b0 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64 69 74  0, then no addit
192c0 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73 20 61  ional attempts a
192d0 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20 61 63  re made to.** ac
192e0 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73  cess the databas
192f0 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 42 55  e and [SQLITE_BU
19300 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49  SY] or [SQLITE_I
19310 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 73  OERR_BLOCKED] is
19320 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 49   returned..** ^I
19330 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  f the callback r
19340 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
19350 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61 74   then another at
19360 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64 65  tempt.** is made
19370 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64 61 74   to open the dat
19380 61 62 61 73 65 20 66 6f 72 20 72 65 61 64 69 6e  abase for readin
19390 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20  g and the cycle 
193a0 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  repeats..**.** T
193b0 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61  he presence of a
193c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f   busy handler do
193d0 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65  es not guarantee
193e0 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65   that it will be
193f0 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e   invoked.** when
19400 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63   there is lock c
19410 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53  ontention. ^If S
19420 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73  QLite determines
19430 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74   that invoking t
19440 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c  he busy.** handl
19450 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20  er could result 
19460 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69  in a deadlock, i
19470 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20  t will go ahead 
19480 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  and return [SQLI
19490 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72 20 5b  TE_BUSY].** or [
194a0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
194b0 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20 6f 66  CKED] instead of
194c0 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75   invoking the bu
194d0 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43  sy handler..** C
194e0 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e 61 72  onsider a scenar
194f0 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f  io where one pro
19500 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19510 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74  a read lock that
19520 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67  .** it is trying
19530 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
19540 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61   reserved lock a
19550 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70  nd.** a second p
19560 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
19570 67 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63  g a reserved loc
19580 6b 20 74 68 61 74 20 69 74 20 69 73 20 74 72 79  k that it is try
19590 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74  ing.** to promot
195a0 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76  e to an exclusiv
195b0 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72  e lock.  The fir
195c0 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f  st process canno
195d0 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63  t proceed.** bec
195e0 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b  ause it is block
195f0 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64  ed by the second
19600 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
19610 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a  process cannot.*
19620 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61 75 73  * proceed becaus
19630 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20  e it is blocked 
19640 62 79 20 74 68 65 20 66 69 72 73 74 2e 20 20 49  by the first.  I
19650 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73  f both processes
19660 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62  .** invoke the b
19670 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65  usy handlers, ne
19680 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20  ither will make 
19690 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54  any progress.  T
196a0 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c  herefore,.** SQL
196b0 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ite returns [SQL
196c0 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68  ITE_BUSY] for th
196d0 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c  e first process,
196e0 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69   hoping that thi
196f0 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65  s.** will induce
19700 20 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65   the first proce
19710 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74  ss to release it
19720 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20  s read lock and 
19730 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63  allow.** the sec
19740 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70  ond process to p
19750 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  roceed..**.** ^T
19760 68 65 20 64 65 66 61 75 6c 74 20 62 75 73 79 20  he default busy 
19770 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c  callback is NULL
19780 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ..**.** ^The [SQ
19790 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72  LITE_BUSY] error
197a0 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f   is converted to
197b0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
197c0 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20  LOCKED].** when 
197d0 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65  SQLite is in the
197e0 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72   middle of a lar
197f0 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77  ge transaction w
19800 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20  here all the.** 
19810 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74  changes will not
19820 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e   fit into the in
19830 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20  -memory cache.  
19840 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61  SQLite will.** a
19850 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45  lready hold a RE
19860 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74  SERVED lock on t
19870 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
19880 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a  , but it needs.*
19890 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69  * to promote thi
198a0 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53  s lock to EXCLUS
198b0 49 56 45 20 73 6f 20 74 68 61 74 20 69 74 20 63  IVE so that it c
198c0 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a  an spill cache.*
198d0 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65  * pages into the
198e0 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
198f0 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63  ithout harm to c
19900 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61  oncurrent.** rea
19910 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73  ders.  ^If it is
19920 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f   unable to promo
19930 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65  te the lock, the
19940 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a  n the in-memory.
19950 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65  ** cache will be
19960 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f   left in an inco
19970 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65 20 61  nsistent state a
19980 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a  nd so the error.
19990 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f  ** code is promo
199a0 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c  ted from the rel
199b0 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b  atively benign [
199c0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a  SQLITE_BUSY] to.
199d0 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65  ** the more seve
199e0 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  re [SQLITE_IOERR
199f0 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69  _BLOCKED].  ^Thi
19a00 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f  s error code pro
19a10 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73  motion.** forces
19a20 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f   an automatic ro
19a30 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68  llback of the ch
19a40 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a  anges.  See the.
19a50 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73  ** <a href="/cvs
19a60 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72  trac/wiki?p=Corr
19a70 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
19a80 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f  usyError">.** Co
19a90 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
19aa0 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77  gBusyError</a> w
19ab0 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61 20 64  iki page for a d
19ac0 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79  iscussion of why
19ad0 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f  .** this is impo
19ae0 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  rtant..**.** ^(T
19af0 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65  here can only be
19b00 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68   a single busy h
19b10 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66  andler defined f
19b20 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  or each.** [data
19b30 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
19b40 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77  .  Setting a new
19b50 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c   busy handler cl
19b60 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76  ears any.** prev
19b70 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c  iously set handl
19b80 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61  er.)^  ^Note tha
19b90 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  t calling [sqlit
19ba0 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
19bb0 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73 6f 20  )].** will also 
19bc0 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74 68 65  set or clear the
19bd0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a   busy handler..*
19be0 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20 63 61  *.** The busy ca
19bf0 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20 6e 6f  llback should no
19c00 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74 69 6f  t take any actio
19c10 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66 79 20  ns which modify 
19c20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
19c30 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
19c40 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
19c50 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79 20 73   handler.  Any s
19c60 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 72  uch actions.** r
19c70 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
19c80 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 20  ed behavior..** 
19c90 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e 64 6c  .** A busy handl
19ca0 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  er must not clos
19cb0 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  e the database c
19cc0 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 72 20  onnection.** or 
19cd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
19ce0 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f 6b 65  ent] that invoke
19cf0 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
19d00 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  er..*/.int sqlit
19d10 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
19d20 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
19d30 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76 6f 69  (void*,int), voi
19d40 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
19d50 33 52 45 46 3a 20 53 65 74 20 41 20 42 75 73 79  3REF: Set A Busy
19d60 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a 20 5e   Timeout.**.** ^
19d70 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65 74  This routine set
19d80 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  s a [sqlite3_bus
19d90 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75 73 79  y_handler | busy
19da0 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74 20 73   handler] that s
19db0 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61 20 73  leeps.** for a s
19dc0 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e 74 20  pecified amount 
19dd0 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61 20 74  of time when a t
19de0 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64 2e 20  able is locked. 
19df0 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a 2a 2a   ^The handler.**
19e00 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75 6c 74   will sleep mult
19e10 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74 69 6c  iple times until
19e20 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d   at least "ms" m
19e30 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73  illiseconds of s
19e40 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76 65 20  leeping.** have 
19e50 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20 5e 41  accumulated.  ^A
19e60 66 74 65 72 20 61 74 20 6c 65 61 73 74 20 22 6d  fter at least "m
19e70 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  s" milliseconds 
19e80 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a 2a 20  of sleeping,.** 
19e90 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65 74 75  the handler retu
19ea0 72 6e 73 20 30 20 77 68 69 63 68 20 63 61 75 73  rns 0 which caus
19eb0 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  es [sqlite3_step
19ec0 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a  ()] to return.**
19ed0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
19ee0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
19ef0 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a 2a 20  BLOCKED]..**.** 
19f00 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19f10 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19f20 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19f30 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19f40 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19f50 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19f60 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19f70 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19f80 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19f90 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19fa0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19fb0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
19fc0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
19fd0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
19fe0 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19ff0 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
1a000 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
1a010 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
1a020 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
1a030 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
1a040 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
1a050 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
1a060 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  .)^.*/.int sqlit
1a070 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
1a080 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6d 73  sqlite3*, int ms
1a090 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a0a0 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63 65 20  EF: Convenience 
1a0b0 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52 75 6e  Routines For Run
1a0c0 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a 2a 0a  ning Queries.**.
1a0d0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c 65 67  ** This is a leg
1a0e0 61 63 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  acy interface th
1a0f0 61 74 20 69 73 20 70 72 65 73 65 72 76 65 64 20  at is preserved 
1a100 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
1a110 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 20  mpatibility..** 
1a120 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65  Use of this inte
1a130 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72 65 63  rface is not rec
1a140 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a 2a 20  ommended..**.** 
1a150 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20 3c 62  Definition: A <b
1a160 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c 2f 62  >result table</b
1a170 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61 74 61  > is memory data
1a180 20 73 74 72 75 63 74 75 72 65 20 63 72 65 61 74   structure creat
1a190 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b 73 71  ed by the.** [sq
1a1a0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a1b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20 20 41  )] interface.  A
1a1c0 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 72 65   result table re
1a1d0 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63 6f 6d  cords the.** com
1a1e0 70 6c 65 74 65 20 71 75 65 72 79 20 72 65 73 75  plete query resu
1a1f0 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f 72 20  lts from one or 
1a200 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a 2a 2a  more queries..**
1a210 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20 63 6f  .** The table co
1a220 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73 20 61  nceptually has a
1a230 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 20   number of rows 
1a240 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20 42 75  and columns.  Bu
1a250 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d 62 65  t.** these numbe
1a260 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72 74 20  rs are not part 
1a270 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  of the result ta
1a280 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54 68 65  ble itself.  The
1a290 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20 61 72  se.** numbers ar
1a2a0 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70 61 72  e obtained separ
1a2b0 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20 62 65  ately.  Let N be
1a2c0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 72   the number of r
1a2d0 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62 65 20  ows.** and M be 
1a2e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
1a2f0 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 72  lumns..**.** A r
1a300 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73 20 61  esult table is a
1a310 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
1a320 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d  ers to zero-term
1a330 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73 74 72  inated UTF-8 str
1a340 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65 20 61  ings..** There a
1a350 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65 6d 65  re (N+1)*M eleme
1a360 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72 61 79  nts in the array
1a370 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d 20 70  .  The first M p
1a380 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a 2a 2a  ointers point.**
1a390 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61   to zero-termina
1a3a0 74 65 64 20 73 74 72 69 6e 67 73 20 74 68 61 74  ted strings that
1a3b0 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20 6e 61    contain the na
1a3c0 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  mes of the colum
1a3d0 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d 61 69  ns..** The remai
1a3e0 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61 6c 6c  ning entries all
1a3f0 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72 79 20   point to query 
1a400 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c 20 76  results.  NULL v
1a410 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a 2a 20  alues result.** 
1a420 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  in NULL pointers
1a430 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  .  All other val
1a440 75 65 73 20 61 72 65 20 69 6e 20 74 68 65 69 72  ues are in their
1a450 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65 72 6d   UTF-8 zero-term
1a460 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67  inated.** string
1a470 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20   representation 
1a480 61 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  as returned by [
1a490 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
1a4a0 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 41 20  ext()]..**.** A 
1a4b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d 69 67  result table mig
1a4c0 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20 6f 6e  ht consist of on
1a4d0 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f 72 79  e or more memory
1a4e0 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a 2a 2a   allocations..**
1a4f0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
1a500 74 6f 20 70 61 73 73 20 61 20 72 65 73 75 6c 74  to pass a result
1a510 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c 79 20   table directly 
1a520 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1a530 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ()]..** A result
1a540 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20 62 65   table should be
1a550 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75 73 69   deallocated usi
1a560 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ng [sqlite3_free
1a570 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _table()]..**.**
1a580 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70 6c 65   ^(As an example
1a590 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 74   of the result t
1a5a0 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73 75 70  able format, sup
1a5b0 70 6f 73 65 20 61 20 71 75 65 72 79 20 72 65 73  pose a query res
1a5c0 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66 6f 6c  ult.** is as fol
1a5d0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1a5e0 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1a5f0 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20 20 20          Name    
1a600 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20 20 20      | Age.**    
1a610 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d      ------------
1a620 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a 20 20  -----------.**  
1a630 20 20 20 20 20 20 41 6c 69 63 65 20 20 20 20 20        Alice     
1a640 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20 20 20    | 43.**       
1a650 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c 20 32   Bob         | 2
1a660 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69 6e 64  8.**        Cind
1a670 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a 2a 20  y       | 21.** 
1a680 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1a690 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72 65 20  te>.**.** There 
1a6a0 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e 20 28  are two column (
1a6b0 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65 65 20  M==2) and three 
1a6c0 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20 54 68  rows (N==3).  Th
1a6d0 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  us the.** result
1a6e0 20 74 61 62 6c 65 20 68 61 73 20 38 20 65 6e 74   table has 8 ent
1a6f0 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65 20 74  ries.  Suppose t
1a700 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  he result table 
1a710 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69 6e 20  is stored.** in 
1a720 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73 20 61  an array names a
1a730 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e 20 61  zResult.  Then a
1a740 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20 74 68  zResult holds th
1a750 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a 0a 2a  is content:.**.*
1a760 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1a770 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  re>.**        az
1a780 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20 3d 20  Result&#91;0] = 
1a790 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20 20 20  "Name";.**      
1a7a0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 31    azResult&#91;1
1a7b0 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20 20 20  ] = "Age";.**   
1a7c0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a7d0 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22 3b 0a  1;2] = "Alice";.
1a7e0 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a7f0 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34 33 22  lt&#91;3] = "43"
1a800 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a810 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20 22 42  sult&#91;4] = "B
1a820 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ob";.**        a
1a830 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d 20 3d  zResult&#91;5] =
1a840 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20 20 20   "28";.**       
1a850 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 36 5d   azResult&#91;6]
1a860 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a 20 20   = "Cindy";.**  
1a870 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a880 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a 2a 2a  91;7] = "21";.**
1a890 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
1a8a0 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ote>)^.**.** ^Th
1a8b0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1a8c0 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 65  ble() function e
1a8d0 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f 72 20  valuates one or 
1a8e0 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f  more.** semicolo
1a8f0 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51 4c 20  n-separated SQL 
1a900 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20 74 68  statements in th
1a910 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
1a920 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72 69 6e  d UTF-8.** strin
1a930 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70 61 72  g of its 2nd par
1a940 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74 75 72  ameter and retur
1a950 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c  ns a result tabl
1a960 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f 69 6e  e to the.** poin
1a970 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69 74 73  ter given in its
1a980 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   3rd parameter..
1a990 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68 65 20  **.** After the 
1a9a0 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61 73 20  application has 
1a9b0 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 74 68  finished with th
1a9c0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 73 71  e result from sq
1a9d0 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28  lite3_get_table(
1a9e0 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20 70 61  ),.** it must pa
1a9f0 73 73 20 74 68 65 20 72 65 73 75 6c 74 20 74 61  ss the result ta
1aa00 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 73  ble pointer to s
1aa10 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
1aa20 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74 6f 0a  e() in order to.
1aa30 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65 20 6d  ** release the m
1aa40 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73 20 6d  emory that was m
1aa50 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61 75 73  alloced.  Becaus
1aa60 65 20 6f 66 20 74 68 65 20 77 61 79 20 74 68 65  e of the way the
1aa70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
1aa80 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73 20 77  loc()] happens w
1aa90 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f 67 65  ithin sqlite3_ge
1aaa0 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65 20 63  t_table(), the c
1aab0 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69  alling.** functi
1aac0 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72 79 20  on must not try 
1aad0 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33  to call [sqlite3
1aae0 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63 74 6c  _free()] directl
1aaf0 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73 71 6c  y.  Only.** [sql
1ab00 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1ab10 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20 72 65  )] is able to re
1ab20 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79  lease the memory
1ab30 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20 73 61   properly and sa
1ab40 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  fely..**.** The 
1ab50 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
1ab60 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  e() interface is
1ab70 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 73 20   implemented as 
1ab80 61 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64  a wrapper around
1ab90 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65  .** [sqlite3_exe
1aba0 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c 69 74  c()].  The sqlit
1abb0 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 72  e3_get_table() r
1abc0 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f 74 20  outine does not 
1abd0 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  have access.** t
1abe0 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c 20 64  o any internal d
1abf0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 6f  ata structures o
1ac00 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20 75 73  f SQLite.  It us
1ac10 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75 62 6c  es only the publ
1ac20 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  ic.** interface 
1ac30 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20 20 41  defined here.  A
1ac40 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63 65 2c  s a consequence,
1ac50 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f 63 63   errors that occ
1ac60 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77 72 61  ur in the.** wra
1ac70 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74 73 69  pper layer outsi
1ac80 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65 72 6e  de of the intern
1ac90 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  al [sqlite3_exec
1aca0 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e 6f 74  ()] call are not
1acb0 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20 69 6e  .** reflected in
1acc0 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   subsequent call
1acd0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
1ace0 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a 20 5b  rcode()] or.** [
1acf0 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29  sqlite3_errmsg()
1ad00 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
1ad10 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20 20 73  3_get_table(.  s
1ad20 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
1ad30 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65 6e 20       /* An open 
1ad40 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63 6f  database */.  co
1ad50 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20  nst char *zSql, 
1ad60 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65      /* SQL to be
1ad70 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20   evaluated */.  
1ad80 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73 75 6c  char ***pazResul
1ad90 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c 74 73  t,    /* Results
1ada0 20 6f 66 20 74 68 65 20 71 75 65 72 79 20 2a 2f   of the query */
1adb0 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c 20 20  .  int *pnRow,  
1adc0 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62           /* Numb
1add0 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72 6f 77  er of result row
1ade0 73 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  s written here *
1adf0 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c 75 6d  /.  int *pnColum
1ae00 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d  n,        /* Num
1ae10 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 63 6f  ber of result co
1ae20 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20 68 65  lumns written he
1ae30 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70  re */.  char **p
1ae40 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20 2f 2a  zErrmsg       /*
1ae50 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69 74 74   Error msg writt
1ae60 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a 76 6f  en here */.);.vo
1ae70 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  id sqlite3_free_
1ae80 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72 65 73  table(char **res
1ae90 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ult);../*.** CAP
1aea0 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74 65 64  I3REF: Formatted
1aeb0 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69 6e 67   String Printing
1aec0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
1aed0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
1aee0 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65 73 20  are work-alikes 
1aef0 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66 28 29  of the "printf()
1af00 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75 6e 63  " family of func
1af10 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20 74 68  tions.** from th
1af20 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
1af30 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  rary..**.** ^The
1af40 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66   sqlite3_mprintf
1af50 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 76  () and sqlite3_v
1af60 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  mprintf() routin
1af70 65 73 20 77 72 69 74 65 20 74 68 65 69 72 0a 2a  es write their.*
1af80 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f 20 6d  * results into m
1af90 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66  emory obtained f
1afa0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  rom [sqlite3_mal
1afb0 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73  loc()]..** The s
1afc0 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65 64 20  trings returned 
1afd0 62 79 20 74 68 65 73 65 20 74 77 6f 20 72 6f 75  by these two rou
1afe0 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62 65 0a  tines should be.
1aff0 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79 20 5b  ** released by [
1b000 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e  sqlite3_free()].
1b010 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e 65 73    ^Both routines
1b020 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e 55 4c   return a.** NUL
1b030 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b 73 71  L pointer if [sq
1b040 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1b050 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1b060 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a 2a 20  ocate enough.** 
1b070 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1b080 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72  he resulting str
1b090 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ing..**.** ^(The
1b0a0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b0b0 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20 73  f() routine is s
1b0c0 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70 72 69  imilar to "snpri
1b0d0 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a 20 74  ntf()" from.** t
1b0e0 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69  he standard C li
1b0f0 62 72 61 72 79 2e 20 20 54 68 65 20 72 65 73 75  brary.  The resu
1b100 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e  lt is written in
1b110 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66 65 72  to the.** buffer
1b120 20 73 75 70 70 6c 69 65 64 20 61 73 20 74 68 65   supplied as the
1b130 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1b140 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69 73 20  r whose size is 
1b150 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68 65 20  given by.** the 
1b160 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
1b170 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6f   Note that the o
1b180 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a 20 66  rder of the.** f
1b190 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d 65 74  irst two paramet
1b1a0 65 72 73 20 69 73 20 72 65 76 65 72 73 65 64 20  ers is reversed 
1b1b0 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28 29 2e  from snprintf().
1b1c0 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e 0a 2a  )^  This is an.*
1b1d0 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61 63 63  * historical acc
1b1e0 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e 6e 6f  ident that canno
1b1f0 74 20 62 65 20 66 69 78 65 64 20 77 69 74 68 6f  t be fixed witho
1b200 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a 20 62  ut breaking.** b
1b210 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
1b220 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74 65 20  bility.  ^(Note 
1b230 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69 74 65  also that sqlite
1b240 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
1b250 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1b260 72 20 74 6f 20 69 74 73 20 62 75 66 66 65 72 20  r to its buffer 
1b270 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65 20 6e  instead of the n
1b280 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 72  umber of.** char
1b290 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c 79 20  acters actually 
1b2a0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
1b2b0 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65 20 61   buffer.)^  We a
1b2c0 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74 68 65  dmit that.** the
1b2d0 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
1b2e0 63 74 65 72 73 20 77 72 69 74 74 65 6e 20 77 6f  cters written wo
1b2f0 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20 75 73  uld be a more us
1b300 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 76  eful return.** v
1b310 61 6c 75 65 20 62 75 74 20 77 65 20 63 61 6e 6e  alue but we cann
1b320 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 69 6d  ot change the im
1b330 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
1b340 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
1b350 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68 6f 75  ().** now withou
1b360 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d 70 61  t breaking compa
1b370 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
1b380 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20  ^As long as the 
1b390 62 75 66 66 65 72 20 73 69 7a 65 20 69 73 20 67  buffer size is g
1b3a0 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65 72 6f  reater than zero
1b3b0 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  , sqlite3_snprin
1b3c0 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e 74 65  tf().** guarante
1b3d0 65 73 20 74 68 61 74 20 74 68 65 20 62 75 66 66  es that the buff
1b3e0 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a 65 72  er is always zer
1b3f0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e  o-terminated.  ^
1b400 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70 61 72  The first.** par
1b410 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20 74 68  ameter "n" is th
1b420 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f 66 20  e total size of 
1b430 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e 63 6c  the buffer, incl
1b440 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f 72 0a  uding space for.
1b450 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65 72 6d  ** the zero term
1b460 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68 65 20  inator.  So the 
1b470 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67 20 74  longest string t
1b480 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d 70 6c  hat can be compl
1b490 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74 65 6e  etely.** written
1b4a0 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63 68 61   will be n-1 cha
1b4b0 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e  racters..**.** ^
1b4c0 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73 6e 70  The sqlite3_vsnp
1b4d0 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20  rintf() routine 
1b4e0 69 73 20 61 20 76 61 72 61 72 67 73 20 76 65 72  is a varargs ver
1b4f0 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f  sion of sqlite3_
1b500 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a 0a 2a  snprintf()..**.*
1b510 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1b520 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74 20 73   all implement s
1b530 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 66  ome additional f
1b540 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f 70 74  ormatting.** opt
1b550 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 75 73  ions that are us
1b560 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74 72 75  eful for constru
1b570 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74 65 6d  cting SQL statem
1b580 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f 66 20  ents..** All of 
1b590 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e 74 66  the usual printf
1b5a0 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70  () formatting op
1b5b0 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20 49 6e  tions apply.  In
1b5c0 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65 72 65   addition, there
1b5d0 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71 22 2c  .** is are "%q",
1b5e0 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a 22 20   "%Q", and "%z" 
1b5f0 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  options..**.** ^
1b600 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e 20 77  (The %q option w
1b610 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69 6e 20  orks like %s in 
1b620 74 68 61 74 20 69 74 20 73 75 62 73 74 69 74 75  that it substitu
1b630 74 65 73 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e  tes a nul-termin
1b640 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 66  ated.** string f
1b650 72 6f 6d 20 74 68 65 20 61 72 67 75 6d 65 6e 74  rom the argument
1b660 20 6c 69 73 74 2e 20 20 42 75 74 20 25 71 20 61   list.  But %q a
1b670 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65 76 65 72  lso doubles ever
1b680 79 20 27 5c 27 27 20 63 68 61 72 61 63 74 65 72  y '\'' character
1b690 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65 73 69 67  ..** %q is desig
1b6a0 6e 65 64 20 66 6f 72 20 75 73 65 20 69 6e 73 69  ned for use insi
1b6b0 64 65 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65  de a string lite
1b6c0 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f 75 62 6c  ral.)^  By doubl
1b6d0 69 6e 67 20 65 61 63 68 20 27 5c 27 27 0a 2a 2a  ing each '\''.**
1b6e0 20 63 68 61 72 61 63 74 65 72 20 69 74 20 65 73   character it es
1b6f0 63 61 70 65 73 20 74 68 61 74 20 63 68 61 72 61  capes that chara
1b700 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f 77 73 20  cter and allows 
1b710 69 74 20 74 6f 20 62 65 20 69 6e 73 65 72 74 65  it to be inserte
1b720 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 73 74  d into.** the st
1b730 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20  ring..**.** For 
1b740 65 78 61 6d 70 6c 65 2c 20 61 73 73 75 6d 65 20  example, assume 
1b750 74 68 65 20 73 74 72 69 6e 67 20 76 61 72 69 61  the string varia
1b760 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e 74 61 69  ble zText contai
1b770 6e 73 20 74 65 78 74 20 61 73 20 66 6f 6c 6c 6f  ns text as follo
1b780 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ws:.**.** <block
1b790 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
1b7a0 63 68 61 72 20 2a 7a 54 65 78 74 20 3d 20 22 49  char *zText = "I
1b7b0 74 27 73 20 61 20 68 61 70 70 79 20 64 61 79 21  t's a happy day!
1b7c0 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  ";.** </pre></bl
1b7d0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
1b7e0 4f 6e 65 20 63 61 6e 20 75 73 65 20 74 68 69 73  One can use this
1b7f0 20 74 65 78 74 20 69 6e 20 61 6e 20 53 51 4c 20   text in an SQL 
1b800 73 74 61 74 65 6d 65 6e 74 20 61 73 20 66 6f 6c  statement as fol
1b810 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  lows:.**.** <blo
1b820 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
1b830 20 20 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73    char *zSQL = s
1b840 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22  qlite3_mprintf("
1b850 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c  INSERT INTO tabl
1b860 65 20 56 41 4c 55 45 53 28 27 25 71 27 29 22 2c  e VALUES('%q')",
1b870 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73 71 6c   zText);.**  sql
1b880 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20 7a 53  ite3_exec(db, zS
1b890 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a  QL, 0, 0, 0);.**
1b8a0 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 7a    sqlite3_free(z
1b8b0 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  SQL);.** </pre><
1b8c0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b8d0 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65 20 25  ** Because the %
1b8e0 71 20 66 6f 72 6d 61 74 20 73 74 72 69 6e 67 20  q format string 
1b8f0 69 73 20 75 73 65 64 2c 20 74 68 65 20 27 5c 27  is used, the '\'
1b900 27 20 63 68 61 72 61 63 74 65 72 20 69 6e 20 7a  ' character in z
1b910 54 65 78 74 0a 2a 2a 20 69 73 20 65 73 63 61 70  Text.** is escap
1b920 65 64 20 61 6e 64 20 74 68 65 20 53 51 4c 20 67  ed and the SQL g
1b930 65 6e 65 72 61 74 65 64 20 69 73 20 61 73 20 66  enerated is as f
1b940 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
1b950 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
1b960 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20  **  INSERT INTO 
1b970 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49  table1 VALUES('I
1b980 74 27 27 73 20 61 20 68 61 70 70 79 20 64 61 79  t''s a happy day
1b990 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  !').** </pre></b
1b9a0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1b9b0 20 54 68 69 73 20 69 73 20 63 6f 72 72 65 63 74   This is correct
1b9c0 2e 20 20 48 61 64 20 77 65 20 75 73 65 64 20 25  .  Had we used %
1b9d0 73 20 69 6e 73 74 65 61 64 20 6f 66 20 25 71 2c  s instead of %q,
1b9e0 20 74 68 65 20 67 65 6e 65 72 61 74 65 64 20 53   the generated S
1b9f0 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68 61 76 65  QL.** would have
1ba00 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20 74 68 69   looked like thi
1ba10 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
1ba20 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49  uote><pre>.**  I
1ba30 4e 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65  NSERT INTO table
1ba40 31 20 56 41 4c 55 45 53 28 27 49 74 27 73 20 61  1 VALUES('It's a
1ba50 20 68 61 70 70 79 20 64 61 79 21 27 29 3b 0a 2a   happy day!');.*
1ba60 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ba70 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73  uote>.**.** This
1ba80 20 73 65 63 6f 6e 64 20 65 78 61 6d 70 6c 65 20   second example 
1ba90 69 73 20 61 6e 20 53 51 4c 20 73 79 6e 74 61 78  is an SQL syntax
1baa0 20 65 72 72 6f 72 2e 20 20 41 73 20 61 20 67 65   error.  As a ge
1bab0 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f 75 20 73  neral rule you s
1bac0 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61 79 73 20  hould.** always 
1bad0 75 73 65 20 25 71 20 69 6e 73 74 65 61 64 20 6f  use %q instead o
1bae0 66 20 25 73 20 77 68 65 6e 20 69 6e 73 65 72 74  f %s when insert
1baf0 69 6e 67 20 74 65 78 74 20 69 6e 74 6f 20 61 20  ing text into a 
1bb00 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 0a  string literal..
1bb10 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 51 20 6f  **.** ^(The %Q o
1bb20 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1bb30 20 25 71 20 65 78 63 65 70 74 20 69 74 20 61 6c   %q except it al
1bb40 73 6f 20 61 64 64 73 20 73 69 6e 67 6c 65 20 71  so adds single q
1bb50 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a 2a 2a 20  uotes around.** 
1bb60 74 68 65 20 6f 75 74 73 69 64 65 20 6f 66 20 74  the outside of t
1bb70 68 65 20 74 6f 74 61 6c 20 73 74 72 69 6e 67 2e  he total string.
1bb80 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c 79 2c 20    Additionally, 
1bb90 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
1bba0 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72 67 75 6d   in the.** argum
1bbb0 65 6e 74 20 6c 69 73 74 20 69 73 20 61 20 4e 55  ent list is a NU
1bbc0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25 51 20 73  LL pointer, %Q s
1bbd0 75 62 73 74 69 74 75 74 65 73 20 74 68 65 20 74  ubstitutes the t
1bbe0 65 78 74 20 22 4e 55 4c 4c 22 20 28 77 69 74 68  ext "NULL" (with
1bbf0 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65 20 71 75  out.** single qu
1bc00 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c 20 66 6f  otes).)^  So, fo
1bc10 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e 65 20 63  r example, one c
1bc20 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a 2a 2a 20  ould say:.**.** 
1bc30 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1bc40 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c  >.**  char *zSQL
1bc50 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e   = sqlite3_mprin
1bc60 74 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20  tf("INSERT INTO 
1bc70 74 61 62 6c 65 20 56 41 4c 55 45 53 28 25 51 29  table VALUES(%Q)
1bc80 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20 73  ", zText);.**  s
1bc90 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c 20  qlite3_exec(db, 
1bca0 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b 0a  zSQL, 0, 0, 0);.
1bcb0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65 65  **  sqlite3_free
1bcc0 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72 65  (zSQL);.** </pre
1bcd0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1bce0 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 61 62  *.** The code ab
1bcf0 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64 65 72 20  ove will render 
1bd00 61 20 63 6f 72 72 65 63 74 20 53 51 4c 20 73 74  a correct SQL st
1bd10 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65 20 7a  atement in the z
1bd20 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62 6c 65 20  SQL.** variable 
1bd30 65 76 65 6e 20 69 66 20 74 68 65 20 7a 54 65 78  even if the zTex
1bd40 74 20 76 61 72 69 61 62 6c 65 20 69 73 20 61 20  t variable is a 
1bd50 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
1bd60 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a 22 20 66  .** ^(The "%z" f
1bd70 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e  ormatting option
1bd80 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22 25 73 22   works like "%s"
1bd90 20 62 75 74 20 77 69 74 68 20 74 68 65 0a 2a 2a   but with the.**
1bda0 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 61   addition that a
1bdb0 66 74 65 72 20 74 68 65 20 73 74 72 69 6e 67 20  fter the string 
1bdc0 68 61 73 20 62 65 65 6e 20 72 65 61 64 20 61 6e  has been read an
1bdd0 64 20 63 6f 70 69 65 64 20 69 6e 74 6f 0a 2a 2a  d copied into.**
1bde0 20 74 68 65 20 72 65 73 75 6c 74 2c 20 5b 73 71   the result, [sq
1bdf0 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 69 73  lite3_free()] is
1be00 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68 65 20 69   called on the i
1be10 6e 70 75 74 20 73 74 72 69 6e 67 2e 29 5e 0a 2a  nput string.)^.*
1be20 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  /.char *sqlite3_
1be30 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1be40 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a  ar*,...);.char *
1be50 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1be60 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  (const char*, va
1be70 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20 2a 73 71  _list);.char *sq
1be80 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 69  lite3_snprintf(i
1be90 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63  nt,char*,const c
1bea0 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63 68 61 72  har*, ...);.char
1beb0 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e 70 72 69   *sqlite3_vsnpri
1bec0 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f  ntf(int,char*,co
1bed0 6e 73 74 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69  nst char*, va_li
1bee0 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  st);../*.** CAPI
1bef0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1bf00 6f 63 61 74 69 6f 6e 20 53 75 62 73 79 73 74 65  ocation Subsyste
1bf10 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 69  m.**.** The SQLi
1bf20 74 65 20 63 6f 72 65 20 75 73 65 73 20 74 68 65  te core uses the
1bf30 73 65 20 74 68 72 65 65 20 72 6f 75 74 69 6e 65  se three routine
1bf40 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73  s for all of its
1bf50 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c   own.** internal
1bf60 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1bf70 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f 72 65 22  on needs. "Core"
1bf80 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
1bf90 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20 64 6f 65   sentence.** doe
1bfa0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 6f 70  s not include op
1bfb0 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73  erating-system s
1bfc0 70 65 63 69 66 69 63 20 56 46 53 20 69 6d 70 6c  pecific VFS impl
1bfd0 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 54 68 65  ementation.  The
1bfe0 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56 46 53 20  .** Windows VFS 
1bff0 75 73 65 73 20 6e 61 74 69 76 65 20 6d 61 6c 6c  uses native mall
1c000 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1c010 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72 61 74 69  for some operati
1c020 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ons..**.** ^The 
1c030 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c040 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
1c050 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
1c060 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d 65 6d 6f  block.** of memo
1c070 72 79 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  ry at least N by
1c080 74 65 73 20 69 6e 20 6c 65 6e 67 74 68 2c 20 77  tes in length, w
1c090 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 70 61  here N is the pa
1c0a0 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
1c0b0 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c0c0 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 6f 62   is unable to ob
1c0d0 74 61 69 6e 20 73 75 66 66 69 63 69 65 6e 74 20  tain sufficient 
1c0e0 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20  free.** memory, 
1c0f0 69 74 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  it returns a NUL
1c100 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 49 66 20  L pointer.  ^If 
1c110 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20  the parameter N 
1c120 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  to.** sqlite3_ma
1c130 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f  lloc() is zero o
1c140 72 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  r negative then 
1c150 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c160 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 4e 55   returns.** a NU
1c170 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
1c180 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74  * ^Calling sqlit
1c190 65 33 5f 66 72 65 65 28 29 20 77 69 74 68 20 61  e3_free() with a
1c1a0 20 70 6f 69 6e 74 65 72 20 70 72 65 76 69 6f 75   pointer previou
1c1b0 73 6c 79 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  sly returned.** 
1c1c0 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
1c1d0 63 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72  c() or sqlite3_r
1c1e0 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65 61 73 65  ealloc() release
1c1f0 73 20 74 68 61 74 20 6d 65 6d 6f 72 79 20 73 6f  s that memory so
1c200 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d 69 67 68  .** that it migh
1c210 74 20 62 65 20 72 65 75 73 65 64 2e 20 20 5e 54  t be reused.  ^T
1c220 68 65 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  he sqlite3_free(
1c230 29 20 72 6f 75 74 69 6e 65 20 69 73 0a 2a 2a 20  ) routine is.** 
1c240 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73 20 63 61  a no-op if is ca
1c250 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c  lled with a NULL
1c260 20 70 6f 69 6e 74 65 72 2e 20 20 50 61 73 73 69   pointer.  Passi
1c270 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ng a NULL pointe
1c280 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  r.** to sqlite3_
1c290 66 72 65 65 28 29 20 69 73 20 68 61 72 6d 6c 65  free() is harmle
1c2a0 73 73 2e 20 20 41 66 74 65 72 20 62 65 69 6e 67  ss.  After being
1c2b0 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72 79 0a 2a   freed, memory.*
1c2c0 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74 68 65 72  * should neither
1c2d0 20 62 65 20 72 65 61 64 20 6e 6f 72 20 77 72 69   be read nor wri
1c2e0 74 74 65 6e 2e 20 20 45 76 65 6e 20 72 65 61 64  tten.  Even read
1c2f0 69 6e 67 20 70 72 65 76 69 6f 75 73 6c 79 20 66  ing previously f
1c300 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6d  reed.** memory m
1c310 69 67 68 74 20 72 65 73 75 6c 74 20 69 6e 20 61  ight result in a
1c320 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20 66 61   segmentation fa
1c330 75 6c 74 20 6f 72 20 6f 74 68 65 72 20 73 65 76  ult or other sev
1c340 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 4d 65  ere error..** Me
1c350 6d 6f 72 79 20 63 6f 72 72 75 70 74 69 6f 6e 2c  mory corruption,
1c360 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e 20   a segmentation 
1c370 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68 65 72 20  fault, or other 
1c380 73 65 76 65 72 65 20 65 72 72 6f 72 0a 2a 2a 20  severe error.** 
1c390 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69 66 20  might result if 
1c3a0 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69  sqlite3_free() i
1c3b0 73 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20  s called with a 
1c3c0 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  non-NULL pointer
1c3d0 20 74 68 61 74 0a 2a 2a 20 77 61 73 20 6e 6f 74   that.** was not
1c3e0 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 73   obtained from s
1c3f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1c400 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  or sqlite3_reall
1c410 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  oc()..**.** ^(Th
1c420 65 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  e sqlite3_reallo
1c430 63 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74  c() interface at
1c440 74 65 6d 70 74 73 20 74 6f 20 72 65 73 69 7a 65  tempts to resize
1c450 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d 65 6d 6f   a.** prior memo
1c460 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f  ry allocation to
1c470 20 62 65 20 61 74 20 6c 65 61 73 74 20 4e 20 62   be at least N b
1c480 79 74 65 73 2c 20 77 68 65 72 65 20 4e 20 69 73  ytes, where N is
1c490 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70   the.** second p
1c4a0 61 72 61 6d 65 74 65 72 2e 20 20 54 68 65 20 6d  arameter.  The m
1c4b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1c4c0 20 74 6f 20 62 65 20 72 65 73 69 7a 65 64 20 69   to be resized i
1c4d0 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 70  s the first.** p
1c4e0 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e 20 49 66  arameter.)^ ^ If
1c4f0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
1c500 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c510 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
1c520 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
1c530 68 65 6e 20 69 74 73 20 62 65 68 61 76 69 6f 72  hen its behavior
1c540 20 69 73 20 69 64 65 6e 74 69 63 61 6c 20 74 6f   is identical to
1c550 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69   calling.** sqli
1c560 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29 20 77 68  te3_malloc(N) wh
1c570 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
1c580 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ond parameter to
1c590 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c5a0 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  ()..** ^If the s
1c5b0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20  econd parameter 
1c5c0 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  to sqlite3_reall
1c5d0 6f 63 28 29 20 69 73 20 7a 65 72 6f 20 6f 72 0a  oc() is zero or.
1c5e0 2a 2a 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e  ** negative then
1c5f0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1c600 20 65 78 61 63 74 6c 79 20 74 68 65 20 73 61 6d   exactly the sam
1c610 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  e as calling.** 
1c620 73 71 6c 69 74 65 33 5f 66 72 65 65 28 50 29 20  sqlite3_free(P) 
1c630 77 68 65 72 65 20 50 20 69 73 20 74 68 65 20 66  where P is the f
1c640 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
1c650 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
1c660 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69 74 65 33  c()..** ^sqlite3
1c670 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1c680 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
1c690 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
1c6a0 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61  ion.** of at lea
1c6b0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  st N bytes in si
1c6c0 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66 20 73 75  ze or NULL if su
1c6d0 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f 72 79 20  fficient memory 
1c6e0 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a  is unavailable..
1c6f0 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74 68 65 20  ** ^If M is the 
1c700 73 69 7a 65 20 6f 66 20 74 68 65 20 70 72 69 6f  size of the prio
1c710 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c 20 74 68  r allocation, th
1c720 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62 79 74 65  en min(N,M) byte
1c730 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70 72 69 6f  s.** of the prio
1c740 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 61 72 65  r allocation are
1c750 20 63 6f 70 69 65 64 20 69 6e 74 6f 20 74 68 65   copied into the
1c760 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 62 75   beginning of bu
1c770 66 66 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a  ffer returned.**
1c780 20 62 79 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   by sqlite3_real
1c790 6c 6f 63 28 29 20 61 6e 64 20 74 68 65 20 70 72  loc() and the pr
1c7a0 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 69  ior allocation i
1c7b0 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20  s freed..** ^If 
1c7c0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c7d0 29 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2c 20  ) returns NULL, 
1c7e0 74 68 65 6e 20 74 68 65 20 70 72 69 6f 72 20 61  then the prior a
1c7f0 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  llocation.** is 
1c800 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a 0a 2a 2a  not freed..**.**
1c810 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 72 65 74   ^The memory ret
1c820 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
1c830 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20 73 71  _malloc() and sq
1c840 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a  lite3_realloc().
1c850 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 6c 69  ** is always ali
1c860 67 6e 65 64 20 74 6f 20 61 74 20 6c 65 61 73 74  gned to at least
1c870 20 61 6e 20 38 20 62 79 74 65 20 62 6f 75 6e 64   an 8 byte bound
1c880 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a 2a 2a 20  ary, or to a.** 
1c890 34 20 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  4 byte boundary 
1c8a0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 34  if the [SQLITE_4
1c8b0 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44 5f 4d 41  _BYTE_ALIGNED_MA
1c8c0 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  LLOC] compile-ti
1c8d0 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20 69 73 20  me.** option is 
1c8e0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 6e 20 53  used..**.** In S
1c8f0 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1c900 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31 2c 20 69  5.0 and 3.5.1, i
1c910 74 20 77 61 73 20 70 6f 73 73 69 62 6c 65 20 74  t was possible t
1c920 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74 68 65 20  o define.** the 
1c930 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d 45 4d 4f  SQLITE_OMIT_MEMO
1c940 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e 20 77 68  RY_ALLOCATION wh
1c950 69 63 68 20 77 6f 75 6c 64 20 63 61 75 73 65 20  ich would cause 
1c960 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a 2a 2a 20  the built-in.** 
1c970 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
1c980 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
1c990 20 74 6f 20 62 65 20 6f 6d 69 74 74 65 64 2e 20   to be omitted. 
1c9a0 20 54 68 61 74 20 63 61 70 61 62 69 6c 69 74 79   That capability
1c9b0 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72  .** is no longer
1c9c0 20 70 72 6f 76 69 64 65 64 2e 20 20 4f 6e 6c 79   provided.  Only
1c9d0 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
1c9e0 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63 61 6e 20   allocators can 
1c9f0 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 50  be used..**.** P
1ca00 72 69 6f 72 20 74 6f 20 53 51 4c 69 74 65 20 76  rior to SQLite v
1ca10 65 72 73 69 6f 6e 20 33 2e 37 2e 31 30 2c 20 74  ersion 3.7.10, t
1ca20 68 65 20 57 69 6e 64 6f 77 73 20 4f 53 20 69 6e  he Windows OS in
1ca30 74 65 72 66 61 63 65 20 6c 61 79 65 72 20 63 61  terface layer ca
1ca40 6c 6c 65 64 0a 2a 2a 20 74 68 65 20 73 79 73 74  lled.** the syst
1ca50 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  em malloc() and 
1ca60 66 72 65 65 28 29 20 64 69 72 65 63 74 6c 79 20  free() directly 
1ca70 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e 67 0a  when converting.
1ca80 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62 65 74  ** filenames bet
1ca90 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38 20 65  ween the UTF-8 e
1caa0 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62 79 20  ncoding used by 
1cab0 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 77 68  SQLite.** and wh
1cac0 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d 65 20  atever filename 
1cad0 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64  encoding is used
1cae0 20 62 79 20 74 68 65 20 70 61 72 74 69 63 75 6c   by the particul
1caf0 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20 69 6e  ar Windows.** in
1cb00 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d 65 6d  stallation.  Mem
1cb10 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
1cb20 72 72 6f 72 73 20 77 65 72 65 20 64 65 74 65 63  rrors were detec
1cb30 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65 79  ted, but.** they
1cb40 20 77 65 72 65 20 72 65 70 6f 72 74 65 64 20 62   were reported b
1cb50 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
1cb60 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
1cb70 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
1cb80 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
1cb90 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
1cba0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
1cbb0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
1cbc0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
1cbd0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1cbe0 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
1cbf0 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
1cc00 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
1cc10 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
1cc20 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
1cc30 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
1cc40 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1cc50 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
1cc60 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
1cc70 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
1cc80 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
1cc90 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
1cca0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
1ccb0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
1ccc0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
1ccd0 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
1cce0 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
1ccf0 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1cd00 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
1cd10 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
1cd20 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
1cd30 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
1cd40 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
1cd50 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
1cd60 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
1cd70 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
1cd80 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
1cd90 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
1cda0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
1cdb0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
1cdc0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
1cdd0 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
1cde0 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
1cdf0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
1ce00 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
1ce10 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
1ce20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
1ce30 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
1ce40 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
1ce50 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
1ce60 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
1ce70 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
1ce80 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1ce90 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
1cea0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
1ceb0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
1cec0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
1ced0 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
1cee0 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
1cef0 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
1cf00 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
1cf10 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
1cf20 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
1cf30 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
1cf40 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
1cf50 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
1cf60 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
1cf70 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
1cf80 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
1cf90 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
1cfa0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1cfb0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
1cfc0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1cfd0 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
1cfe0 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
1cff0 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
1d000 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
1d010 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
1d020 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1d030 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
1d040 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
1d050 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
1d060 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
1d070 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
1d080 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
1d090 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
1d0a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
1d0b0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
1d0c0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
1d0d0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
1d0e0 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
1d0f0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
1d100 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
1d110 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1d120 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
1d130 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
1d140 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
1d150 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
1d160 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
1d170 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
1d180 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
1d190 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
1d1a0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
1d1b0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1d1c0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1d1d0 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
1d1e0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1d1f0 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
1d200 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
1d210 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
1d220 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
1d230 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
1d240 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
1d250 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
1d260 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
1d270 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
1d280 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
1d290 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
1d2a0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
1d2b0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
1d2c0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
1d2d0 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
1d2e0 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
1d2f0 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
1d300 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
1d310 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
1d320 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
1d330 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
1d340 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
1d350 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
1d360 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
1d370 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
1d380 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
1d390 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
1d3a0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
1d3b0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
1d3c0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
1d3d0 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
1d3e0 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
1d3f0 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
1d400 2e 0a 2a 2a 20 5e 49 66 20 4e 20 69 73 20 6c 65  ..** ^If N is le
1d410 73 73 20 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65  ss than one, the
1d420 6e 20 50 20 63 61 6e 20 62 65 20 61 20 4e 55 4c  n P can be a NUL
1d430 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
1d440 20 5e 49 66 20 74 68 69 73 20 72 6f 75 74 69 6e   ^If this routin
1d450 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 70  e has not been p
1d460 72 65 76 69 6f 75 73 6c 79 20 63 61 6c 6c 65 64  reviously called
1d470 20 6f 72 20 69 66 20 74 68 65 20 70 72 65 76 69   or if the previ
1d480 6f 75 73 0a 2a 2a 20 63 61 6c 6c 20 68 61 64 20  ous.** call had 
1d490 4e 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65 2c  N less than one,
1d4a0 20 74 68 65 6e 20 74 68 65 20 50 52 4e 47 20 69   then the PRNG i
1d4b0 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20 72  s seeded using r
1d4c0 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6f 62 74  andomness.** obt
1d4d0 61 69 6e 65 64 20 66 72 6f 6d 20 74 68 65 20 78  ained from the x
1d4e0 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68 6f  Randomness metho
1d4f0 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74  d of the default
1d500 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1d510 62 6a 65 63 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  bject..** ^If th
1d520 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
1d530 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1d540 68 61 64 20 61 6e 20 4e 20 6f 66 20 31 20 6f 72  had an N of 1 or
1d550 20 6d 6f 72 65 20 74 68 65 6e 0a 2a 2a 20 74 68   more then.** th
1d560 65 20 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e  e pseudo-randomn
1d570 65 73 73 20 69 73 20 67 65 6e 65 72 61 74 65 64  ess is generated
1d580 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61  .** internally a
1d590 6e 64 20 77 69 74 68 6f 75 74 20 72 65 63 6f 75  nd without recou
1d5a0 72 73 65 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  rse to the [sqli
1d5b0 74 65 33 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d  te3_vfs] xRandom
1d5c0 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a  ness.** method..
1d5d0 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  */.void sqlite3_
1d5e0 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e  randomness(int N
1d5f0 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a  , void *P);../*.
1d600 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
1d610 70 69 6c 65 2d 54 69 6d 65 20 41 75 74 68 6f 72  pile-Time Author
1d620 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b  ization Callback
1d630 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
1d640 75 74 69 6e 65 20 72 65 67 69 73 74 65 72 73 20  utine registers 
1d650 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  an authorizer ca
1d660 6c 6c 62 61 63 6b 20 77 69 74 68 20 61 20 70 61  llback with a pa
1d670 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
1d680 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d690 5d 2c 20 73 75 70 70 6c 69 65 64 20 69 6e 20 74  ], supplied in t
1d6a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
1d6b0 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f  t..** ^The autho
1d6c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d6d0 73 20 69 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c  s invoked as SQL
1d6e0 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
1d6f0 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a  being compiled.*
1d700 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  * by [sqlite3_pr
1d710 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1d720 76 61 72 69 61 6e 74 73 20 5b 73 71 6c 69 74 65  variants [sqlite
1d730 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
1d740 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
1d750 70 61 72 65 31 36 28 29 5d 20 61 6e 64 20 5b 73  pare16()] and [s
1d760 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
1d770 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20 76 61 72  _v2()].  ^At var
1d780 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64  ious.** points d
1d790 75 72 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c  uring the compil
1d7a0 61 74 69 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61  ation process, a
1d7b0 73 20 6c 6f 67 69 63 20 69 73 20 62 65 69 6e 67  s logic is being
1d7c0 20 63 72 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70   created.** to p
1d7d0 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 61  erform various a
1d7e0 63 74 69 6f 6e 73 2c 20 74 68 65 20 61 75 74 68  ctions, the auth
1d7f0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d800 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a  is invoked to.**
1d810 20 73 65 65 20 69 66 20 74 68 6f 73 65 20 61 63   see if those ac
1d820 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65  tions are allowe
1d830 64 2e 20 20 5e 54 68 65 20 61 75 74 68 6f 72 69  d.  ^The authori
1d840 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  zer callback sho
1d850 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53  uld.** return [S
1d860 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c  QLITE_OK] to all
1d870 6f 77 20 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b  ow the action, [
1d880 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1d890 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a  o disallow the.*
1d8a0 2a 20 73 70 65 63 69 66 69 63 20 61 63 74 69 6f  * specific actio
1d8b0 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74 68 65 20  n but allow the 
1d8c0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  SQL statement to
1d8d0 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a   continue to be.
1d8e0 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20  ** compiled, or 
1d8f0 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f  [SQLITE_DENY] to
1d900 20 63 61 75 73 65 20 74 68 65 20 65 6e 74 69 72   cause the entir
1d910 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
1d920 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65  to be.** rejecte
1d930 64 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 2e  d with an error.
1d940 20 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72    ^If the author
1d950 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65  izer callback re
1d960 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c  turns.** any val
1d970 75 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b 53  ue other than [S
1d980 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b  QLITE_IGNORE], [
1d990 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b  SQLITE_OK], or [
1d9a0 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20  SQLITE_DENY].** 
1d9b0 74 68 65 6e 20 74 68 65 20 5b 73 71 6c 69 74 65  then the [sqlite
1d9c0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
1d9d0 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61  or equivalent ca
1d9e0 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65  ll that triggere
1d9f0 64 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69  d.** the authori
1da00 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69  zer will fail wi
1da10 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  th an error mess
1da20 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20  age..**.** When 
1da30 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1da40 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
1da50 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65  , that means the
1da60 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65   operation.** re
1da70 71 75 65 73 74 65 64 20 69 73 20 6f 6b 2e 20 20  quested is ok.  
1da80 5e 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62 61  ^When the callba
1da90 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1daa0 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a  TE_DENY], the.**
1dab0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1dac0 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76  e_v2()] or equiv
1dad0 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20  alent call that 
1dae0 74 72 69 67 67 65 72 65 64 20 74 68 65 0a 2a 2a  triggered the.**
1daf0 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c   authorizer will
1db00 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72   fail with an er
1db10 72 6f 72 20 6d 65 73 73 61 67 65 20 65 78 70 6c  ror message expl
1db20 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61  aining that.** a
1db30 63 63 65 73 73 20 69 73 20 64 65 6e 69 65 64 2e  ccess is denied.
1db40 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72   .**.** ^The fir
1db50 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
1db60 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1db70 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 63 6f 70  allback is a cop
1db80 79 20 6f 66 20 74 68 65 20 74 68 69 72 64 0a 2a  y of the third.*
1db90 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  * parameter to t
1dba0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
1dbb0 75 74 68 6f 72 69 7a 65 72 28 29 20 69 6e 74 65  uthorizer() inte
1dbc0 72 66 61 63 65 2e 20 5e 54 68 65 20 73 65 63 6f  rface. ^The seco
1dbd0 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
1dbe0 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  to the callback 
1dbf0 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 5b 53  is an integer [S
1dc00 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20 61 63 74  QLITE_COPY | act
1dc10 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61 74 20 73  ion code] that s
1dc20 70 65 63 69 66 69 65 73 0a 2a 2a 20 74 68 65 20  pecifies.** the 
1dc30 70 61 72 74 69 63 75 6c 61 72 20 61 63 74 69 6f  particular actio
1dc40 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1dc50 65 64 2e 20 5e 54 68 65 20 74 68 69 72 64 20 74  ed. ^The third t
1dc60 68 72 6f 75 67 68 20 73 69 78 74 68 20 70 61 72  hrough sixth par
1dc70 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68  ameters.** to th
1dc80 65 20 63 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a  e callback are z
1dc90 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73  ero-terminated s
1dca0 74 72 69 6e 67 73 20 74 68 61 74 20 63 6f 6e 74  trings that cont
1dcb0 61 69 6e 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ain additional.*
1dcc0 2a 20 64 65 74 61 69 6c 73 20 61 62 6f 75 74 20  * details about 
1dcd0 74 68 65 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  the action to be
1dce0 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a   authorized..**.
1dcf0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1dd00 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1dd10 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74  E_READ].** and t
1dd20 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1dd30 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  rns [SQLITE_IGNO
1dd40 52 45 5d 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20  RE] then the.** 
1dd50 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
1dd60 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e 74 20 69  ent] statement i
1dd70 73 20 63 6f 6e 73 74 72 75 63 74 65 64 20 74 6f  s constructed to
1dd80 20 73 75 62 73 74 69 74 75 74 65 0a 2a 2a 20 61   substitute.** a
1dd90 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70   NULL value in p
1dda0 6c 61 63 65 20 6f 66 20 74 68 65 20 74 61 62 6c  lace of the tabl
1ddb0 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f  e column that wo
1ddc0 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e  uld have.** been
1ddd0 20 72 65 61 64 20 69 66 20 5b 53 51 4c 49 54 45   read if [SQLITE
1dde0 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e 20 72 65  _OK] had been re
1ddf0 74 75 72 6e 65 64 2e 20 20 54 68 65 20 5b 53 51  turned.  The [SQ
1de00 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20  LITE_IGNORE].** 
1de10 72 65 74 75 72 6e 20 63 61 6e 20 62 65 20 75 73  return can be us
1de20 65 64 20 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e  ed to deny an un
1de30 74 72 75 73 74 65 64 20 75 73 65 72 20 61 63 63  trusted user acc
1de40 65 73 73 20 74 6f 20 69 6e 64 69 76 69 64 75 61  ess to individua
1de50 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  l.** columns of 
1de60 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  a table..** ^If 
1de70 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1de80 69 73 20 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54  is [SQLITE_DELET
1de90 45 5d 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62  E] and the callb
1dea0 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b  ack returns.** [
1deb0 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74  SQLITE_IGNORE] t
1dec0 68 65 6e 20 74 68 65 20 5b 44 45 4c 45 54 45 5d  hen the [DELETE]
1ded0 20 6f 70 65 72 61 74 69 6f 6e 20 70 72 6f 63 65   operation proce
1dee0 65 64 73 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b  eds but the.** [
1def0 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a  truncate optimiz
1df00 61 74 69 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c  ation] is disabl
1df10 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20  ed and all rows 
1df20 61 72 65 20 64 65 6c 65 74 65 64 20 69 6e 64 69  are deleted indi
1df30 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20  vidually..**.** 
1df40 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73  An authorizer is
1df50 20 75 73 65 64 20 77 68 65 6e 20 5b 73 71 6c 69   used when [sqli
1df60 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72  te3_prepare | pr
1df70 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20  eparing].** SQL 
1df80 73 74 61 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20  statements from 
1df90 61 6e 20 75 6e 74 72 75 73 74 65 64 20 73 6f 75  an untrusted sou
1dfa0 72 63 65 2c 20 74 6f 20 65 6e 73 75 72 65 20 74  rce, to ensure t
1dfb0 68 61 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  hat the SQL stat
1dfc0 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74  ements.** do not
1dfd0 20 74 72 79 20 74 6f 20 61 63 63 65 73 73 20 64   try to access d
1dfe0 61 74 61 20 74 68 65 79 20 61 72 65 20 6e 6f 74  ata they are not
1dff0 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c   allowed to see,
1e000 20 6f 72 20 74 68 61 74 20 74 68 65 79 20 64 6f   or that they do
1e010 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65   not.** try to e
1e020 78 65 63 75 74 65 20 6d 61 6c 69 63 69 6f 75 73  xecute malicious
1e030 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68 61 74   statements that
1e040 20 64 61 6d 61 67 65 20 74 68 65 20 64 61 74 61   damage the data
1e050 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78  base.  For.** ex
1e060 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
1e070 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20  ation may allow 
1e080 61 20 75 73 65 72 20 74 6f 20 65 6e 74 65 72 20  a user to enter 
1e090 61 72 62 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c  arbitrary.** SQL
1e0a0 20 71 75 65 72 69 65 73 20 66 6f 72 20 65 76 61   queries for eva
1e0b0 6c 75 61 74 69 6f 6e 20 62 79 20 61 20 64 61 74  luation by a dat
1e0c0 61 62 61 73 65 2e 20 20 42 75 74 20 74 68 65 20  abase.  But the 
1e0d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73  application does
1e0e0 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20 74 68 65  .** not want the
1e0f0 20 75 73 65 72 20 74 6f 20 62 65 20 61 62 6c 65   user to be able
1e100 20 74 6f 20 6d 61 6b 65 20 61 72 62 69 74 72 61   to make arbitra
1e110 72 79 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  ry changes to th
1e120 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20  e.** database.  
1e130 41 6e 20 61 75 74 68 6f 72 69 7a 65 72 20 63 6f  An authorizer co
1e140 75 6c 64 20 74 68 65 6e 20 62 65 20 70 75 74 20  uld then be put 
1e150 69 6e 20 70 6c 61 63 65 20 77 68 69 6c 65 20 74  in place while t
1e160 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72  he.** user-enter
1e170 65 64 20 53 51 4c 20 69 73 20 62 65 69 6e 67 20  ed SQL is being 
1e180 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1e190 20 7c 20 70 72 65 70 61 72 65 64 5d 20 74 68 61   | prepared] tha
1e1a0 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65  t.** disallows e
1e1b0 76 65 72 79 74 68 69 6e 67 20 65 78 63 65 70 74  verything except
1e1c0 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d   [SELECT] statem
1e1d0 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ents..**.** Appl
1e1e0 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6e 65  ications that ne
1e1f0 65 64 20 74 6f 20 70 72 6f 63 65 73 73 20 53 51  ed to process SQ
1e200 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73 74 65 64  L from untrusted
1e210 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68   sources.** migh
1e220 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20  t also consider 
1e230 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f 75 72 63  lowering resourc
1e240 65 20 6c 69 6d 69 74 73 20 75 73 69 6e 67 20 5b  e limits using [
1e250 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
1e260 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67  .** and limiting
1e270 20 64 61 74 61 62 61 73 65 20 73 69 7a 65 20 75   database size u
1e280 73 69 6e 67 20 74 68 65 20 5b 6d 61 78 5f 70 61  sing the [max_pa
1e290 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
1e2a0 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f  A].** in additio
1e2b0 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e 20 61 75  n to using an au
1e2c0 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20  thorizer..**.** 
1e2d0 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20  ^(Only a single 
1e2e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6e 20 62  authorizer can b
1e2f0 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20  e in place on a 
1e300 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e310 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65  ion.** at a time
1e320 2e 20 20 45 61 63 68 20 63 61 6c 6c 20 74 6f 20  .  Each call to 
1e330 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1e340 6f 72 69 7a 65 72 20 6f 76 65 72 72 69 64 65 73  orizer overrides
1e350 20 74 68 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73   the.** previous
1e360 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62   call.)^  ^Disab
1e370 6c 65 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  le the authorize
1e380 72 20 62 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20  r by installing 
1e390 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e  a NULL callback.
1e3a0 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1e3b0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 20 62  er is disabled b
1e3c0 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a  y default..**.**
1e3d0 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1e3e0 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f  callback must no
1e3f0 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74 68  t do anything th
1e400 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a  at will modify.*
1e410 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1e420 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20 69  onnection that i
1e430 6e 76 6f 6b 65 64 20 74 68 65 20 61 75 74 68 6f  nvoked the autho
1e440 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a  rizer callback..
1e450 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71  ** Note that [sq
1e460 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
1e470 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1e480 5f 73 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f  _step()] both mo
1e490 64 69 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61  dify their.** da
1e4a0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e4b0 6e 73 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69  ns for the meani
1e4c0 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69  ng of "modify" i
1e4d0 6e 20 74 68 69 73 20 70 61 72 61 67 72 61 70 68  n this paragraph
1e4e0 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73  ..**.** ^When [s
1e4f0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1e500 32 28 29 5d 20 69 73 20 75 73 65 64 20 74 6f 20  2()] is used to 
1e510 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65 6d  prepare a statem
1e520 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74  ent, the.** stat
1e530 65 6d 65 6e 74 20 6d 69 67 68 74 20 62 65 20 72  ement might be r
1e540 65 2d 70 72 65 70 61 72 65 64 20 64 75 72 69 6e  e-prepared durin
1e550 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
1e560 29 5d 20 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20  )] due to a .** 
1e570 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 20 20  schema change.  
1e580 48 65 6e 63 65 2c 20 74 68 65 20 61 70 70 6c 69  Hence, the appli
1e590 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e  cation should en
1e5a0 73 75 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a  sure that the.**
1e5b0 20 63 6f 72 72 65 63 74 20 61 75 74 68 6f 72 69   correct authori
1e5c0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d  zer callback rem
1e5d0 61 69 6e 73 20 69 6e 20 70 6c 61 63 65 20 64 75  ains in place du
1e5e0 72 69 6e 67 20 74 68 65 20 5b 73 71 6c 69 74 65  ring the [sqlite
1e5f0 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_step()]..**.**
1e600 20 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20   ^Note that the 
1e610 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e620 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f  ack is invoked o
1e630 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73  nly during.** [s
1e640 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1e650 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1e660 73 2e 20 20 41 75 74 68 6f 72 69 7a 61 74 69 6f  s.  Authorizatio
1e670 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66  n is not.** perf
1e680 6f 72 6d 65 64 20 64 75 72 69 6e 67 20 73 74 61  ormed during sta
1e690 74 65 6d 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  tement evaluatio
1e6a0 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74  n in [sqlite3_st
1e6b0 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a  ep()], unless.**
1e6c0 20 61 73 20 73 74 61 74 65 64 20 69 6e 20 74 68   as stated in th
1e6d0 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61 67  e previous parag
1e6e0 72 61 70 68 2c 20 73 71 6c 69 74 65 33 5f 73 74  raph, sqlite3_st
1e6f0 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  ep() invokes.** 
1e700 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1e710 76 32 28 29 20 74 6f 20 72 65 70 72 65 70 61 72  v2() to reprepar
1e720 65 20 61 20 73 74 61 74 65 6d 65 6e 74 20 61 66  e a statement af
1e730 74 65 72 20 61 20 73 63 68 65 6d 61 20 63 68 61  ter a schema cha
1e740 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  nge..*/.int sqli
1e750 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1e760 65 72 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a  er(.  sqlite3*,.
1e770 20 20 69 6e 74 20 28 2a 78 41 75 74 68 29 28 76    int (*xAuth)(v
1e780 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
1e790 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1e7a0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e  ,const char*,con
1e7b0 73 74 20 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69  st char*),.  voi
1e7c0 64 20 2a 70 55 73 65 72 44 61 74 61 0a 29 3b 0a  d *pUserData.);.
1e7d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1e7e0 20 41 75 74 68 6f 72 69 7a 65 72 20 52 65 74 75   Authorizer Retu
1e7f0 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54  rn Codes.**.** T
1e800 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
1e810 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1e820 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1e830 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a   function] must.
1e840 2a 2a 20 72 65 74 75 72 6e 20 65 69 74 68 65 72  ** return either
1e850 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20   [SQLITE_OK] or 
1e860 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 74 77 6f  one of these two
1e870 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72   constants in or
1e880 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c  der.** to signal
1e890 20 53 51 4c 69 74 65 20 77 68 65 74 68 65 72 20   SQLite whether 
1e8a0 6f 72 20 6e 6f 74 20 74 68 65 20 61 63 74 69 6f  or not the actio
1e8b0 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 2e 20  n is permitted. 
1e8c0 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c   See the.** [sql
1e8d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e8e0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1e8f0 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20   documentation] 
1e900 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
1e910 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
1e920 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53  *.** Note that S
1e930 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 69 73 20  QLITE_IGNORE is 
1e940 61 6c 73 6f 20 75 73 65 64 20 61 73 20 61 20 5b  also used as a [
1e950 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20  SQLITE_ROLLBACK 
1e960 7c 20 72 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a  | return code].*
1e970 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69  * from the [sqli
1e980 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66  te3_vtab_on_conf
1e990 6c 69 63 74 28 29 5d 20 69 6e 74 65 72 66 61 63  lict()] interfac
1e9a0 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
1e9b0 4c 49 54 45 5f 44 45 4e 59 20 20 20 31 20 20 20  LITE_DENY   1   
1e9c0 2f 2a 20 41 62 6f 72 74 20 74 68 65 20 53 51 4c  /* Abort the SQL
1e9d0 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 20   statement with 
1e9e0 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  an error */.#def
1e9f0 69 6e 65 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52  ine SQLITE_IGNOR
1ea00 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61  E 2   /* Don't a
1ea10 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20 62 75 74  llow access, but
1ea20 20 64 6f 6e 27 74 20 67 65 6e 65 72 61 74 65 20   don't generate 
1ea30 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a  an error */../*.
1ea40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74  ** CAPI3REF: Aut
1ea50 68 6f 72 69 7a 65 72 20 41 63 74 69 6f 6e 20 43  horizer Action C
1ea60 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b  odes.**.** The [
1ea70 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1ea80 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74 65 72 66  orizer()] interf
1ea90 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
1eaa0 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1eab0 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20 69 6e 76  n.** that is inv
1eac0 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f 72 69 7a  oked to authoriz
1ead0 65 20 63 65 72 74 61 69 6e 20 53 51 4c 20 73 74  e certain SQL st
1eae0 61 74 65 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e  atement actions.
1eaf0 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20    The.** second 
1eb00 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1eb10 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
1eb20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 74 68 61  integer code tha
1eb30 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  t specifies.** w
1eb40 68 61 74 20 61 63 74 69 6f 6e 20 69 73 20 62 65  hat action is be
1eb50 69 6e 67 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  ing authorized. 
1eb60 20 54 68 65 73 65 20 61 72 65 20 74 68 65 20 69   These are the i
1eb70 6e 74 65 67 65 72 20 61 63 74 69 6f 6e 20 63 6f  nteger action co
1eb80 64 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  des that.** the 
1eb90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eba0 61 63 6b 20 6d 61 79 20 62 65 20 70 61 73 73 65  ack may be passe
1ebb0 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61  d..**.** These a
1ebc0 63 74 69 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65  ction code value
1ebd0 73 20 73 69 67 6e 69 66 79 20 77 68 61 74 20 6b  s signify what k
1ebe0 69 6e 64 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e  ind of operation
1ebf0 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74   is to be.** aut
1ec00 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 20 33 72  horized.  The 3r
1ec10 64 20 61 6e 64 20 34 74 68 20 70 61 72 61 6d 65  d and 4th parame
1ec20 74 65 72 73 20 74 6f 20 74 68 65 20 61 75 74 68  ters to the auth
1ec30 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c  orization.** cal
1ec40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77  lback function w
1ec50 69 6c 6c 20 62 65 20 70 61 72 61 6d 65 74 65 72  ill be parameter
1ec60 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64  s or NULL depend
1ec70 69 6e 67 20 6f 6e 20 77 68 69 63 68 20 6f 66 20  ing on which of 
1ec80 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69  these.** codes i
1ec90 73 20 75 73 65 64 20 61 73 20 74 68 65 20 73 65  s used as the se
1eca0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20  cond parameter. 
1ecb0 20 5e 28 54 68 65 20 35 74 68 20 70 61 72 61 6d   ^(The 5th param
1ecc0 65 74 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61  eter to the.** a
1ecd0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
1ece0 63 6b 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ck is the name o
1ecf0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 28  f the database (
1ed00 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a  "main", "temp",.
1ed10 2a 2a 20 65 74 63 2e 29 20 69 66 20 61 70 70 6c  ** etc.) if appl
1ed20 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20  icable.)^  ^The 
1ed30 36 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  6th parameter to
1ed40 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1ed50 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74  callback.** is t
1ed60 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69  he name of the i
1ed70 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69 67 67 65  nner-most trigge
1ed80 72 20 6f 72 20 76 69 65 77 20 74 68 61 74 20 69  r or view that i
1ed90 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
1eda0 72 0a 2a 2a 20 74 68 65 20 61 63 63 65 73 73 20  r.** the access 
1edb0 61 74 74 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20  attempt or NULL 
1edc0 69 66 20 74 68 69 73 20 61 63 63 65 73 73 20 61  if this access a
1edd0 74 74 65 6d 70 74 20 69 73 20 64 69 72 65 63 74  ttempt is direct
1ede0 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c  ly from.** top-l
1edf0 65 76 65 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a  evel SQL code..*
1ee00 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  /./*************
1ee10 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ee20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33  ************** 3
1ee30 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20  rd ************ 
1ee40 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f  4th ***********/
1ee50 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ee60 43 52 45 41 54 45 5f 49 4e 44 45 58 20 20 20 20  CREATE_INDEX    
1ee70 20 20 20 20 20 20 31 20 20 20 2f 2a 20 49 6e 64        1   /* Ind
1ee80 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ee90 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1eea0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1eeb0 52 45 41 54 45 5f 54 41 42 4c 45 20 20 20 20 20  REATE_TABLE     
1eec0 20 20 20 20 20 32 20 20 20 2f 2a 20 54 61 62 6c       2   /* Tabl
1eed0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1eee0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1eef0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1ef00 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20  EATE_TEMP_INDEX 
1ef10 20 20 20 20 33 20 20 20 2f 2a 20 49 6e 64 65 78      3   /* Index
1ef20 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1ef30 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1ef40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ef50 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ATE_TEMP_TABLE  
1ef60 20 20 20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20     4   /* Table 
1ef70 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ef80 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ef90 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1efa0 54 45 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  TE_TEMP_TRIGGER 
1efb0 20 20 35 20 20 20 2f 2a 20 54 72 69 67 67 65 72    5   /* Trigger
1efc0 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1efd0 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1efe0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1eff0 45 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  E_TEMP_VIEW     
1f000 20 36 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d   6   /* View Nam
1f010 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f020 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f030 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1f040 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1f050 37 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  7   /* Trigger N
1f060 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1f070 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1f080 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1f090 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 38  VIEW           8
1f0a0 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1f0b0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f0c0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f0d0 20 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 20 20   SQLITE_DELETE  
1f0e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 39 20                9 
1f0f0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f100 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f110 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f120 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45  SQLITE_DROP_INDE
1f130 58 20 20 20 20 20 20 20 20 20 20 20 31 30 20 20  X           10  
1f140 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1f150 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1f160 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f170 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45  QLITE_DROP_TABLE
1f180 20 20 20 20 20 20 20 20 20 20 20 31 31 20 20 20             11   
1f190 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1f1a0 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f1b0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f1c0 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49  LITE_DROP_TEMP_I
1f1d0 4e 44 45 58 20 20 20 20 20 20 31 32 20 20 20 2f  NDEX      12   /
1f1e0 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1f1f0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1f200 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f210 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41  ITE_DROP_TEMP_TA
1f220 42 4c 45 20 20 20 20 20 20 31 33 20 20 20 2f 2a  BLE      13   /*
1f230 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f240 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f250 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f260 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49  TE_DROP_TEMP_TRI
1f270 47 47 45 52 20 20 20 20 31 34 20 20 20 2f 2a 20  GGER    14   /* 
1f280 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1f290 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f2a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f2b0 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57  E_DROP_TEMP_VIEW
1f2c0 20 20 20 20 20 20 20 31 35 20 20 20 2f 2a 20 56         15   /* V
1f2d0 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1f2e0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f2f0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f300 5f 44 52 4f 50 5f 54 52 49 47 47 45 52 20 20 20  _DROP_TRIGGER   
1f310 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 54 72        16   /* Tr
1f320 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1f330 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1f340 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f350 44 52 4f 50 5f 56 49 45 57 20 20 20 20 20 20 20  DROP_VIEW       
1f360 20 20 20 20 20 31 37 20 20 20 2f 2a 20 56 69 65       17   /* Vie
1f370 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1f380 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f390 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
1f3a0 4e 53 45 52 54 20 20 20 20 20 20 20 20 20 20 20  NSERT           
1f3b0 20 20 20 20 31 38 20 20 20 2f 2a 20 54 61 62 6c      18   /* Tabl
1f3c0 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1f3d0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f3e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 52  define SQLITE_PR
1f3f0 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
1f400 20 20 20 31 39 20 20 20 2f 2a 20 50 72 61 67 6d     19   /* Pragm
1f410 61 20 4e 61 6d 65 20 20 20 20 20 31 73 74 20 61  a Name     1st a
1f420 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64  rg or NULL */.#d
1f430 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
1f440 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  D               
1f450 20 20 32 30 20 20 20 2f 2a 20 54 61 62 6c 65 20    20   /* Table 
1f460 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1f470 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1f480 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 45 4c 45  fine SQLITE_SELE
1f490 43 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CT              
1f4a0 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20   21   /* NULL   
1f4b0 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20           NULL   
1f4c0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f4d0 69 6e 65 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ine SQLITE_TRANS
1f4e0 41 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20  ACTION          
1f4f0 32 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f  22   /* Operatio
1f500 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  n       NULL    
1f510 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f520 6e 65 20 53 51 4c 49 54 45 5f 55 50 44 41 54 45  ne SQLITE_UPDATE
1f530 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f540 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  3   /* Table Nam
1f550 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f560 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f570 65 20 53 51 4c 49 54 45 5f 41 54 54 41 43 48 20  e SQLITE_ATTACH 
1f580 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 34                24
1f590 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20     /* Filename  
1f5a0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f5b0 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f5c0 20 53 51 4c 49 54 45 5f 44 45 54 41 43 48 20 20   SQLITE_DETACH  
1f5d0 20 20 20 20 20 20 20 20 20 20 20 20 20 32 35 20               25 
1f5e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61    /* Database Na
1f5f0 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20  me   NULL       
1f600 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f610 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f 54 41 42  SQLITE_ALTER_TAB
1f620 4c 45 20 20 20 20 20 20 20 20 20 20 32 36 20 20  LE          26  
1f630 20 2f 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d   /* Database Nam
1f640 65 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20  e   Table Name  
1f650 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f660 51 4c 49 54 45 5f 52 45 49 4e 44 45 58 20 20 20  QLITE_REINDEX   
1f670 20 20 20 20 20 20 20 20 20 20 20 32 37 20 20 20             27   
1f680 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20  /* Index Name   
1f690 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f6a0 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f6b0 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20  LITE_ANALYZE    
1f6c0 20 20 20 20 20 20 20 20 20 20 32 38 20 20 20 2f            28   /
1f6d0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f6e0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f6f0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f700 49 54 45 5f 43 52 45 41 54 45 5f 56 54 41 42 4c  ITE_CREATE_VTABL
1f710 45 20 20 20 20 20 20 20 20 32 39 20 20 20 2f 2a  E        29   /*
1f720 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f730 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20   Module Name    
1f740 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f750 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c 45 20 20  TE_DROP_VTABLE  
1f760 20 20 20 20 20 20 20 20 33 30 20 20 20 2f 2a 20          30   /* 
1f770 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f780 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20  Module Name     
1f790 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f7a0 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 20  E_FUNCTION      
1f7b0 20 20 20 20 20 20 20 33 31 20 20 20 2f 2a 20 4e         31   /* N
1f7c0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 46  ULL            F
1f7d0 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a  unction Name   *
1f7e0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f7f0 5f 53 41 56 45 50 4f 49 4e 54 20 20 20 20 20 20  _SAVEPOINT      
1f800 20 20 20 20 20 20 33 32 20 20 20 2f 2a 20 4f 70        32   /* Op
1f810 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 53 61  eration       Sa
1f820 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f  vepoint Name  */
1f830 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f840 43 4f 50 59 20 20 20 20 20 20 20 20 20 20 20 20  COPY            
1f850 20 20 20 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20        0   /* No 
1f860 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a 2f 0a 23  longer used */.#
1f870 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45  define SQLITE_RE
1f880 43 55 52 53 49 56 45 20 20 20 20 20 20 20 20 20  CURSIVE         
1f890 20 20 20 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20     33   /* NULL 
1f8a0 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c 20             NULL 
1f8b0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f             */../
1f8c0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54  *.** CAPI3REF: T
1f8d0 72 61 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69  racing And Profi
1f8e0 6c 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a  ling Functions.*
1f8f0 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
1f900 6e 65 73 20 72 65 67 69 73 74 65 72 20 63 61 6c  nes register cal
1f910 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20  lback functions 
1f920 74 68 61 74 20 63 61 6e 20 62 65 20 75 73 65 64  that can be used
1f930 20 66 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20   for.** tracing 
1f940 61 6e 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68  and profiling th
1f950 65 20 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53  e execution of S
1f960 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1f970 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1f980 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1f990 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1f9a0 33 5f 74 72 61 63 65 28 29 20 69 73 20 69 6e 76  3_trace() is inv
1f9b0 6f 6b 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f  oked at.** vario
1f9c0 75 73 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e  us times when an
1f9d0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1f9e0 73 20 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b  s being run by [
1f9f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
1fa00 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fa10 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63  _trace() callbac
1fa20 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
1fa30 68 20 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72  h a UTF-8 render
1fa40 69 6e 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51  ing of the.** SQ
1fa50 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
1fa60 20 61 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e   as the statemen
1fa70 74 20 66 69 72 73 74 20 62 65 67 69 6e 73 20 65  t first begins e
1fa80 78 65 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41  xecuting..** ^(A
1fa90 64 64 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65  dditional sqlite
1faa0 33 5f 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61  3_trace() callba
1fab0 63 6b 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a  cks might occur.
1fac0 2a 2a 20 61 73 20 65 61 63 68 20 74 72 69 67 67  ** as each trigg
1fad0 65 72 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20  ered subprogram 
1fae0 69 73 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65  is entered.  The
1faf0 20 63 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74   callbacks for t
1fb00 72 69 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61  riggers.** conta
1fb10 69 6e 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63  in a UTF-8 SQL c
1fb20 6f 6d 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e  omment that iden
1fb30 74 69 66 69 65 73 20 74 68 65 20 74 72 69 67 67  tifies the trigg
1fb40 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  er.)^.**.** The 
1fb50 5b 53 51 4c 49 54 45 5f 54 52 41 43 45 5f 53 49  [SQLITE_TRACE_SI
1fb60 5a 45 5f 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c  ZE_LIMIT] compil
1fb70 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61  e-time option ca
1fb80 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6c 69 6d  n be used to lim
1fb90 69 74 0a 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68  it.** the length
1fba0 20 6f 66 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d   of [bound param
1fbb0 65 74 65 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20  eter] expansion 
1fbc0 69 6e 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  in the output of
1fbd0 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1fbe0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c  ..**.** ^The cal
1fbf0 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72  lback function r
1fc00 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71 6c  egistered by sql
1fc10 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 69  ite3_profile() i
1fc20 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20  s invoked.** as 
1fc30 65 61 63 68 20 53 51 4c 20 73 74 61 74 65 6d 65  each SQL stateme
1fc40 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20 5e 54  nt finishes.  ^T
1fc50 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62  he profile callb
1fc60 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20  ack contains.** 
1fc70 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74 61  the original sta
1fc80 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e 64 20  tement text and 
1fc90 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66 20 77  an estimate of w
1fca0 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a  all-clock time.*
1fcb0 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68  * of how long th
1fcc0 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f  at statement too
1fcd0 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20  k to run.  ^The 
1fce0 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1fcf0 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e 20 75  .** time is in u
1fd00 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f  nits of nanoseco
1fd10 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74 68 65  nds, however the
1fd20 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65   current impleme
1fd30 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e  ntation.** is on
1fd40 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20 6d 69  ly capable of mi
1fd50 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75  llisecond resolu
1fd60 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69 78 20  tion so the six 
1fd70 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63 61 6e  least significan
1fd80 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e 20 74  t.** digits in t
1fd90 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65 61 6e  he time are mean
1fda0 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75 72 65  ingless.  Future
1fdb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1fdc0 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f  ite.** might pro
1fdd0 76 69 64 65 20 67 72 65 61 74 65 72 20 72 65 73  vide greater res
1fde0 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70  olution on the p
1fdf0 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b  rofiler callback
1fe00 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65  .  The.** sqlite
1fe10 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75 6e 63  3_profile() func
1fe20 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64 65 72  tion is consider
1fe30 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 20  ed experimental 
1fe40 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63  and is.** subjec
1fe50 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e 20 66  t to change in f
1fe60 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
1fe70 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69  f SQLite..*/.voi
1fe80 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61 63 65  d *sqlite3_trace
1fe90 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28  (sqlite3*, void(
1fea0 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a 2c 63  *xTrace)(void*,c
1feb0 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76 6f 69  onst char*), voi
1fec0 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45  d*);.SQLITE_EXPE
1fed0 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73  RIMENTAL void *s
1fee0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 73  qlite3_profile(s
1fef0 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64  qlite3*,.   void
1ff00 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f 69 64  (*xProfile)(void
1ff10 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71  *,const char*,sq
1ff20 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c 20 76  lite3_uint64), v
1ff30 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
1ff40 50 49 33 52 45 46 3a 20 51 75 65 72 79 20 50 72  PI3REF: Query Pr
1ff50 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63 6b 73  ogress Callbacks
1ff60 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1ff70 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e  te3_progress_han
1ff80 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e  dler(D,N,X,P) in
1ff90 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 74  terface causes t
1ffa0 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66  he callback.** f
1ffb0 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62 65 20  unction X to be 
1ffc0 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64 69 63  invoked periodic
1ffd0 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67  ally during long
1ffe0 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74   running calls t
1fff0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78  o.** [sqlite3_ex
20000 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ec()], [sqlite3_
20010 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c  step()] and [sql
20020 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
20030 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73  ] for.** databas
20040 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20  e connection D. 
20050 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73 65 20   An example use 
20060 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65  for this.** inte
20070 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65 65 70  rface is to keep
20080 20 61 20 47 55 49 20 75 70 64 61 74 65 64 20 64   a GUI updated d
20090 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20 71 75  uring a large qu
200a0 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ery..**.** ^The 
200b0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 70  parameter P is p
200c0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
200d0 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65   the only parame
200e0 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63  ter to the .** c
200f0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
20100 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61 6d 65   X.  ^The parame
20110 74 65 72 20 4e 20 69 73 20 74 68 65 20 61 70 70  ter N is the app
20120 72 6f 78 69 6d 61 74 65 20 6e 75 6d 62 65 72 20  roximate number 
20130 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
20140 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
20150 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
20160 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
20170 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
20180 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
20190 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e  e callback X.  ^
201a0 49 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61  If N is less tha
201b0 6e 20 6f 6e 65 20 74 68 65 6e 20 74 68 65 20 70  n one then the p
201c0 72 6f 67 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c  rogress.** handl
201d0 65 72 20 69 73 20 64 69 73 61 62 6c 65 64 2e 0a  er is disabled..
201e0 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69  **.** ^Only a si
201f0 6e 67 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61  ngle progress ha
20200 6e 64 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66  ndler may be def
20210 69 6e 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65  ined at one time
20220 20 70 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73   per.** [databas
20230 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73  e connection]; s
20240 65 74 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f  etting a new pro
20250 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61  gress handler ca
20260 6e 63 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64  ncels the.** old
20270 20 6f 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20   one.  ^Setting 
20280 70 61 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e  parameter X to N
20290 55 4c 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65  ULL disables the
202a0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
202b0 72 2e 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72  r..** ^The progr
202c0 65 73 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61  ess handler is a
202d0 6c 73 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20  lso disabled by 
202e0 73 65 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76  setting N to a v
202f0 61 6c 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61  alue less.** tha
20300 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  n 1..**.** ^If t
20310 68 65 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c  he progress call
20320 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
20330 2d 7a 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61  -zero, the opera
20340 74 69 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72  tion is.** inter
20350 72 75 70 74 65 64 2e 20 20 54 68 69 73 20 66 65  rupted.  This fe
20360 61 74 75 72 65 20 63 61 6e 20 62 65 20 75 73 65  ature can be use
20370 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61  d to implement a
20380 0a 2a 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74  .** "Cancel" but
20390 74 6f 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f  ton on a GUI pro
203a0 67 72 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78  gress dialog box
203b0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67  ..**.** The prog
203c0 72 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c  ress handler cal
203d0 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
203e0 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
203f0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
20400 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
20410 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
20420 6b 65 64 20 74 68 65 20 70 72 6f 67 72 65 73 73  ked the progress
20430 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74   handler..** Not
20440 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  e that [sqlite3_
20450 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
20460 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  d [sqlite3_step(
20470 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74  )] both modify t
20480 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65  heir.** database
20490 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72   connections for
204a0 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20   the meaning of 
204b0 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73  "modify" in this
204c0 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a   paragraph..**.*
204d0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70  /.void sqlite3_p
204e0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
204f0 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69  sqlite3*, int, i
20500 6e 74 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f  nt(*)(void*), vo
20510 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  id*);../*.** CAP
20520 49 33 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41  I3REF: Opening A
20530 20 4e 65 77 20 44 61 74 61 62 61 73 65 20 43 6f   New Database Co
20540 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e  nnection.**.** ^
20550 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
20560 70 65 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61  pen an SQLite da
20570 74 61 62 61 73 65 20 66 69 6c 65 20 61 73 20 73  tabase file as s
20580 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
20590 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  .** filename arg
205a0 75 6d 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65  ument. ^The file
205b0 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73  name argument is
205c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
205d0 55 54 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c  UTF-8 for.** sql
205e0 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20  ite3_open() and 
205f0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
20600 29 20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20  ) and as UTF-16 
20610 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
20620 74 65 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20  te.** order for 
20630 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29  sqlite3_open16()
20640 2e 20 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20  . ^(A [database 
20650 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
20660 6c 65 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a  le is usually.**
20670 20 72 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70   returned in *pp
20680 44 62 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65  Db, even if an e
20690 72 72 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68  rror occurs.  Th
206a0 65 20 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e  e only exception
206b0 20 69 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53   is that.** if S
206c0 51 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20  QLite is unable 
206d0 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f  to allocate memo
206e0 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b  ry to hold the [
206f0 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c  sqlite3] object,
20700 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20  .** a NULL will 
20710 62 65 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20  be written into 
20720 2a 70 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66  *ppDb instead of
20730 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
20740 65 20 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f  e [sqlite3].** o
20750 62 6a 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68  bject.)^ ^(If th
20760 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20770 65 6e 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65  ened (and/or cre
20780 61 74 65 64 29 20 73 75 63 63 65 73 73 66 75 6c  ated) successful
20790 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c  ly, then.** [SQL
207a0 49 54 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72  ITE_OK] is retur
207b0 6e 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20  ned.  Otherwise 
207c0 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
207d0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e  is returned.)^ ^
207e0 54 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  The.** [sqlite3_
207f0 65 72 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71  errmsg()] or [sq
20800 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29  lite3_errmsg16()
20810 5d 20 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62  ] routines can b
20820 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
20830 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c  .** an English l
20840 61 6e 67 75 61 67 65 20 64 65 73 63 72 69 70 74  anguage descript
20850 69 6f 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72  ion of the error
20860 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69   following a fai
20870 6c 75 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  lure of any.** o
20880 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70  f the sqlite3_op
20890 65 6e 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  en() routines..*
208a0 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c  *.** ^The defaul
208b0 74 20 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74  t encoding for t
208c0 68 65 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  he database will
208d0 20 62 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20   be UTF-8 if.** 
208e0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
208f0 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
20900 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e  2() is called an
20910 64 0a 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74  d.** UTF-16 in t
20920 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  he native byte o
20930 72 64 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f  rder if sqlite3_
20940 6f 70 65 6e 31 36 28 29 20 69 73 20 75 73 65 64  open16() is used
20950 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20  ..**.** Whether 
20960 6f 72 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20  or not an error 
20970 6f 63 63 75 72 73 20 77 68 65 6e 20 69 74 20 69  occurs when it i
20980 73 20 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72  s opened, resour
20990 63 65 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  ces.** associate
209a0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
209b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
209c0 20 68 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62   handle should b
209d0 65 20 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a  e released by.**
209e0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
209f0 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d  sqlite3_close()]
20a00 20 77 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c   when it is no l
20a10 6f 6e 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a  onger required..
20a20 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20a30 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65  3_open_v2() inte
20a40 72 66 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65  rface works like
20a50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a   sqlite3_open().
20a60 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20 69  ** except that i
20a70 74 20 61 63 63 65 70 74 73 20 74 77 6f 20 61 64  t accepts two ad
20a80 64 69 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74  ditional paramet
20a90 65 72 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e  ers for addition
20aa0 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76  al control.** ov
20ab0 65 72 20 74 68 65 20 6e 65 77 20 64 61 74 61 62  er the new datab
20ac0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  ase connection. 
20ad0 20 5e 28 54 68 65 20 66 6c 61 67 73 20 70 61 72   ^(The flags par
20ae0 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c  ameter to.** sql
20af0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63  ite3_open_v2() c
20b00 61 6e 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a  an take one of.*
20b10 2a 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * the following 
20b20 74 68 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70  three values, op
20b30 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20b40 64 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b  d with the .** [
20b50 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
20b60 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50  TEX], [SQLITE_OP
20b70 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b  EN_FULLMUTEX], [
20b80 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52  SQLITE_OPEN_SHAR
20b90 45 44 43 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51  EDCACHE],.** [SQ
20ba0 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
20bb0 45 43 41 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20  ECACHE], and/or 
20bc0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
20bd0 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a  ] flags:)^.**.**
20be0 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b   <dl>.** ^(<dt>[
20bf0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
20c00 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ONLY]</dt>.** <d
20c10 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20c20 73 20 6f 70 65 6e 65 64 20 69 6e 20 72 65 61 64  s opened in read
20c30 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20  -only mode.  If 
20c40 74 68 65 20 64 61 74 61 62 61 73 65 20 64 6f 65  the database doe
20c50 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79  s not.** already
20c60 20 65 78 69 73 74 2c 20 61 6e 20 65 72 72 6f 72   exist, an error
20c70 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64   is returned.</d
20c80 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
20c90 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  >[SQLITE_OPEN_RE
20ca0 41 44 57 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a  ADWRITE]</dt>.**
20cb0 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61 73   <dd>The databas
20cc0 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
20cd0 72 65 61 64 69 6e 67 20 61 6e 64 20 77 72 69 74  reading and writ
20ce0 69 6e 67 20 69 66 20 70 6f 73 73 69 62 6c 65 2c  ing if possible,
20cf0 20 6f 72 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f   or reading.** o
20d00 6e 6c 79 20 69 66 20 74 68 65 20 66 69 6c 65 20  nly if the file 
20d10 69 73 20 77 72 69 74 65 20 70 72 6f 74 65 63 74  is write protect
20d20 65 64 20 62 79 20 74 68 65 20 6f 70 65 72 61 74  ed by the operat
20d30 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 49 6e 20  ing system.  In 
20d40 65 69 74 68 65 72 0a 2a 2a 20 63 61 73 65 20 74  either.** case t
20d50 68 65 20 64 61 74 61 62 61 73 65 20 6d 75 73 74  he database must
20d60 20 61 6c 72 65 61 64 79 20 65 78 69 73 74 2c 20   already exist, 
20d70 6f 74 68 65 72 77 69 73 65 20 61 6e 20 65 72 72  otherwise an err
20d80 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 3c  or is returned.<
20d90 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  /dd>)^.**.** ^(<
20da0 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
20db0 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
20dc0 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
20dd0 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  ]</dt>.** <dd>Th
20de0 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70  e database is op
20df0 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e 67  ened for reading
20e00 20 61 6e 64 20 77 72 69 74 69 6e 67 2c 20 61 6e   and writing, an
20e10 64 20 69 73 20 63 72 65 61 74 65 64 20 69 66 0a  d is created if.
20e20 2a 2a 20 69 74 20 64 6f 65 73 20 6e 6f 74 20 61  ** it does not a
20e30 6c 72 65 61 64 79 20 65 78 69 73 74 2e 20 54 68  lready exist. Th
20e40 69 73 20 69 73 20 74 68 65 20 62 65 68 61 76 69  is is the behavi
20e50 6f 72 20 74 68 61 74 20 69 73 20 61 6c 77 61 79  or that is alway
20e60 73 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71  s used for.** sq
20e70 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64  lite3_open() and
20e80 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28   sqlite3_open16(
20e90 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64  ).</dd>)^.** </d
20ea0 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20  l>.**.** If the 
20eb0 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
20ec0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
20ed0 28 29 20 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66  () is not one of
20ee0 20 74 68 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74   the.** combinat
20ef0 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f 76 65  ions shown above
20f00 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62   optionally comb
20f10 69 6e 65 64 20 77 69 74 68 20 6f 74 68 65 72 0a  ined with other.
20f20 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
20f30 52 45 41 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54  READONLY | SQLIT
20f40 45 5f 4f 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a  E_OPEN_* bits].*
20f50 2a 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  * then the behav
20f60 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
20f70 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
20f80 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d  [SQLITE_OPEN_NOM
20f90 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
20fa0 74 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  t, then the data
20fb0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
20fc0 2a 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20  ** opens in the 
20fd0 6d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  multi-thread [th
20fe0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73  reading mode] as
20ff0 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e   long as the sin
21000 67 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f  gle-thread.** mo
21010 64 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20  de has not been 
21020 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
21030 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d  ime or start-tim
21040 65 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b  e.  ^If the.** [
21050 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
21060 4d 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73  MUTEX] flag is s
21070 65 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  et then the data
21080 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
21090 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20  opens.** in the 
210a0 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65  serialized [thre
210b0 61 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65  ading mode] unle
210c0 73 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64  ss single-thread
210d0 20 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73   was.** previous
210e0 6c 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63  ly selected at c
210f0 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73  ompile-time or s
21100 74 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54  tart-time..** ^T
21110 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
21120 53 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61  SHAREDCACHE] fla
21130 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
21140 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21150 20 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62   to be.** eligib
21160 6c 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65  le to use [share
21170 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72  d cache mode], r
21180 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
21190 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
211a0 65 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65  ed.** cache is e
211b0 6e 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71  nabled using [sq
211c0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61  lite3_enable_sha
211d0 72 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e  red_cache()].  ^
211e0 54 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  The.** [SQLITE_O
211f0 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
21200 5d 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68  ] flag causes th
21210 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21220 63 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20  ction to not.** 
21230 70 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b  participate in [
21240 73 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64  shared cache mod
21250 65 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  e] even if it is
21260 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20   enabled..**.** 
21270 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61  ^The fourth para
21280 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
21290 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68  _open_v2() is th
212a0 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
212b0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
212c0 62 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e  bject that defin
212d0 65 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  es the operating
212e0 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63   system interfac
212f0 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65  e that.** the ne
21300 77 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  w database conne
21310 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65  ction should use
21320 2e 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  .  ^If the fourt
21330 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a  h parameter is.*
21340 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  * a NULL pointer
21350 20 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c   then the defaul
21360 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
21370 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a  object is used..
21380 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69  **.** ^If the fi
21390 6c 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f  lename is ":memo
213a0 72 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69  ry:", then a pri
213b0 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20  vate, temporary 
213c0 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
213d0 73 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64  se.** is created
213e0 20 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74   for the connect
213f0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d  ion.  ^This in-m
21400 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77  emory database w
21410 69 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a  ill vanish when.
21420 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
21430 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
21440 6f 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65  osed.  Future ve
21450 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
21460 20 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75   might.** make u
21470 73 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c  se of additional
21480 20 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d   special filenam
21490 65 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69  es that begin wi
214a0 74 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61  th the ":" chara
214b0 63 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72  cter..** It is r
214c0 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20  ecommended that 
214d0 77 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20  when a database 
214e0 66 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c  filename actuall
214f0 79 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74  y does begin wit
21500 68 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61  h.** a ":" chara
21510 63 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20  cter you should 
21520 70 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e  prefix the filen
21530 61 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e  ame with a pathn
21540 61 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22  ame such as.** "
21550 2e 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62  ./" to avoid amb
21560 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iguity..**.** ^I
21570 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  f the filename i
21580 73 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e  s an empty strin
21590 67 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  g, then a privat
215a0 65 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20  e, temporary.** 
215b0 6f 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65  on-disk database
215c0 20 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64   will be created
215d0 2e 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65  .  ^This private
215e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
215f0 65 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  e.** automatical
21600 6c 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f  ly deleted as so
21610 6f 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61  on as the databa
21620 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
21630 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b   closed..**.** [
21640 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 69  [URI filenames i
21650 6e 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  n sqlite3_open()
21660 5d 5d 20 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e  ]] <h3>URI Filen
21670 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ames</h3>.**.** 
21680 5e 49 66 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ^If [URI filenam
21690 65 5d 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  e] interpretatio
216a0 6e 20 69 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e  n is enabled, an
216b0 64 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61  d the filename a
216c0 72 67 75 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e  rgument.** begin
216d0 73 20 77 69 74 68 20 22 66 69 6c 65 3a 22 2c 20  s with "file:", 
216e0 74 68 65 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d  then the filenam
216f0 65 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  e is interpreted
21700 20 61 73 20 61 20 55 52 49 2e 20 5e 55 52 49 0a   as a URI. ^URI.
21710 2a 2a 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  ** filename inte
21720 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65 6e  rpretation is en
21730 61 62 6c 65 64 20 69 66 20 74 68 65 20 5b 53 51  abled if the [SQ
21740 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
21750 6c 61 67 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e  lag is.** set in
21760 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75   the fourth argu
21770 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
21780 6f 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66  open_v2(), or if
21790 20 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20   it has.** been 
217a0 65 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79  enabled globally
217b0 20 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49   using the [SQLI
217c0 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f  TE_CONFIG_URI] o
217d0 70 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a  ption with the.*
217e0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
217f0 67 28 29 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62  g()] method or b
21800 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55 53  y the [SQLITE_US
21810 45 5f 55 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74  E_URI] compile-t
21820 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41  ime option..** A
21830 73 20 6f 66 20 53 51 4c 69 74 65 20 76 65 72 73  s of SQLite vers
21840 69 6f 6e 20 33 2e 37 2e 37 2c 20 55 52 49 20 66  ion 3.7.7, URI f
21850 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
21860 74 61 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  tation is turned
21870 20 6f 66 66 0a 2a 2a 20 62 79 20 64 65 66 61 75   off.** by defau
21880 6c 74 2c 20 62 75 74 20 66 75 74 75 72 65 20 72  lt, but future r
21890 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74  eleases of SQLit
218a0 65 20 6d 69 67 68 74 20 65 6e 61 62 6c 65 20 55  e might enable U
218b0 52 49 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69  RI filename.** i
218c0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 62 79  nterpretation by
218d0 20 64 65 66 61 75 6c 74 2e 20 20 53 65 65 20 22   default.  See "
218e0 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22  [URI filenames]"
218f0 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a   for additional.
21900 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  ** information..
21910 2a 2a 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61  **.** URI filena
21920 6d 65 73 20 61 72 65 20 70 61 72 73 65 64 20 61  mes are parsed a
21930 63 63 6f 72 64 69 6e 67 20 74 6f 20 52 46 43 20  ccording to RFC 
21940 33 39 38 36 2e 20 5e 49 66 20 74 68 65 20 55 52  3986. ^If the UR
21950 49 20 63 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a  I contains an.**
21960 20 61 75 74 68 6f 72 69 74 79 2c 20 74 68 65 6e   authority, then
21970 20 69 74 20 6d 75 73 74 20 62 65 20 65 69 74 68   it must be eith
21980 65 72 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  er an empty stri
21990 6e 67 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67  ng or the string
219a0 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22   .** "localhost"
219b0 2e 20 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72  . ^If the author
219c0 69 74 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d  ity is not an em
219d0 70 74 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c  pty string or "l
219e0 6f 63 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a  ocalhost", an .*
219f0 2a 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72  * error is retur
21a00 6e 65 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65  ned to the calle
21a10 72 2e 20 5e 54 68 65 20 66 72 61 67 6d 65 6e 74  r. ^The fragment
21a20 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
21a30 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
21a40 65 6e 74 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e  ent, is ignored.
21a50 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75  .**.** ^SQLite u
21a60 73 65 73 20 74 68 65 20 70 61 74 68 20 63 6f 6d  ses the path com
21a70 70 6f 6e 65 6e 74 20 6f 66 20 74 68 65 20 55 52  ponent of the UR
21a80 49 20 61 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  I as the name of
21a90 20 74 68 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a   the disk file.*
21aa0 2a 20 77 68 69 63 68 20 63 6f 6e 74 61 69 6e 73  * which contains
21ab0 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 5e   the database. ^
21ac0 49 66 20 74 68 65 20 70 61 74 68 20 62 65 67 69  If the path begi
21ad0 6e 73 20 77 69 74 68 20 61 20 27 2f 27 20 63 68  ns with a '/' ch
21ae0 61 72 61 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65  aracter, .** the
21af0 6e 20 69 74 20 69 73 20 69 6e 74 65 72 70 72 65  n it is interpre
21b00 74 65 64 20 61 73 20 61 6e 20 61 62 73 6f 6c 75  ted as an absolu
21b10 74 65 20 70 61 74 68 2e 20 5e 49 66 20 74 68 65  te path. ^If the
21b20 20 70 61 74 68 20 64 6f 65 73 20 6e 6f 74 20 62   path does not b
21b30 65 67 69 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20  egin .** with a 
21b40 27 2f 27 20 28 6d 65 61 6e 69 6e 67 20 74 68 61  '/' (meaning tha
21b50 74 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  t the authority 
21b60 73 65 63 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74  section is omitt
21b70 65 64 20 66 72 6f 6d 20 74 68 65 20 55 52 49 29  ed from the URI)
21b80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 70 61 74  .** then the pat
21b90 68 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  h is interpreted
21ba0 20 61 73 20 61 20 72 65 6c 61 74 69 76 65 20 70   as a relative p
21bb0 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e  ath. .** ^On win
21bc0 64 6f 77 73 2c 20 74 68 65 20 66 69 72 73 74 20  dows, the first 
21bd0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20  component of an 
21be0 61 62 73 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a  absolute path .*
21bf0 2a 20 69 73 20 61 20 64 72 69 76 65 20 73 70 65  * is a drive spe
21c00 63 69 66 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e  cification (e.g.
21c10 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b   "C:")..**.** [[
21c20 63 6f 72 65 20 55 52 49 20 71 75 65 72 79 20 70  core URI query p
21c30 61 72 61 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54  arameters]].** T
21c40 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  he query compone
21c50 6e 74 20 6f 66 20 61 20 55 52 49 20 6d 61 79 20  nt of a URI may 
21c60 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d 65 74 65  contain paramete
21c70 72 73 20 74 68 61 74 20 61 72 65 20 69 6e 74 65  rs that are inte
21c80 72 70 72 65 74 65 64 0a 2a 2a 20 65 69 74 68 65  rpreted.** eithe
21c90 72 20 62 79 20 53 51 4c 69 74 65 20 69 74 73 65  r by SQLite itse
21ca0 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b 56 46 53  lf, or by a [VFS
21cb0 20 7c 20 63 75 73 74 6f 6d 20 56 46 53 20 69 6d   | custom VFS im
21cc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a  plementation]..*
21cd0 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72  * SQLite interpr
21ce0 65 74 73 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e  ets the followin
21cf0 67 20 74 68 72 65 65 20 71 75 65 72 79 20 70 61  g three query pa
21d00 72 61 6d 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20  rameters:.**.** 
21d10 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  <ul>.**   <li> <
21d20 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20  b>vfs</b>: ^The 
21d30 22 76 66 73 22 20 70 61 72 61 6d 65 74 65 72 20  "vfs" parameter 
21d40 6d 61 79 20 62 65 20 75 73 65 64 20 74 6f 20 73  may be used to s
21d50 70 65 63 69 66 79 20 74 68 65 20 6e 61 6d 65 20  pecify the name 
21d60 6f 66 0a 2a 2a 20 20 20 20 20 61 20 56 46 53 20  of.**     a VFS 
21d70 6f 62 6a 65 63 74 20 74 68 61 74 20 70 72 6f 76  object that prov
21d80 69 64 65 73 20 74 68 65 20 6f 70 65 72 61 74 69  ides the operati
21d90 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65 72 66  ng system interf
21da0 61 63 65 20 74 68 61 74 20 73 68 6f 75 6c 64 0a  ace that should.
21db0 2a 2a 20 20 20 20 20 62 65 20 75 73 65 64 20 74  **     be used t
21dc0 6f 20 61 63 63 65 73 73 20 74 68 65 20 64 61 74  o access the dat
21dd0 61 62 61 73 65 20 66 69 6c 65 20 6f 6e 20 64 69  abase file on di
21de0 73 6b 2e 20 5e 49 66 20 74 68 69 73 20 6f 70 74  sk. ^If this opt
21df0 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a  ion is set to.**
21e00 20 20 20 20 20 61 6e 20 65 6d 70 74 79 20 73 74       an empty st
21e10 72 69 6e 67 20 74 68 65 20 64 65 66 61 75 6c 74  ring the default
21e20 20 56 46 53 20 6f 62 6a 65 63 74 20 69 73 20 75   VFS object is u
21e30 73 65 64 2e 20 5e 53 70 65 63 69 66 79 69 6e 67  sed. ^Specifying
21e40 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20   an unknown.**  
21e50 20 20 20 56 46 53 20 69 73 20 61 6e 20 65 72 72     VFS is an err
21e60 6f 72 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  or. ^If sqlite3_
21e70 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65  open_v2() is use
21e80 64 20 61 6e 64 20 74 68 65 20 76 66 73 20 6f 70  d and the vfs op
21e90 74 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70  tion is.**     p
21ea0 72 65 73 65 6e 74 2c 20 74 68 65 6e 20 74 68 65  resent, then the
21eb0 20 56 46 53 20 73 70 65 63 69 66 69 65 64 20 62   VFS specified b
21ec0 79 20 74 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b  y the option tak
21ed0 65 73 20 70 72 65 63 65 64 65 6e 63 65 20 6f 76  es precedence ov
21ee0 65 72 0a 2a 2a 20 20 20 20 20 74 68 65 20 76 61  er.**     the va
21ef0 6c 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68  lue passed as th
21f00 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21f10 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21f20 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20  en_v2()..**.**  
21f30 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62   <li> <b>mode</b
21f40 3e 3a 20 5e 28 54 68 65 20 6d 6f 64 65 20 70 61  >: ^(The mode pa
21f50 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73  rameter may be s
21f60 65 74 20 74 6f 20 65 69 74 68 65 72 20 22 72 6f  et to either "ro
21f70 22 2c 20 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20  ", "rw",.**     
21f80 22 72 77 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72  "rwc", or "memor
21f90 79 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  y". Attempting t
21fa0 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
21fb0 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 0a 2a  other value is.*
21fc0 2a 20 20 20 20 20 61 6e 20 65 72 72 6f 72 29 5e  *     an error)^
21fd0 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20 22 72  . .**     ^If "r
21fe0 6f 22 20 69 73 20 73 70 65 63 69 66 69 65 64 2c  o" is specified,
21ff0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
22000 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72  se is opened for
22010 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20   read-only .**  
22020 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73 74 20     access, just 
22030 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  as if the [SQLIT
22040 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
22050 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e 20 73   flag had been s
22060 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20  et in the .**   
22070 20 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74    third argument
22080 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
22090 5f 76 32 28 29 2e 20 5e 49 66 20 74 68 65 20 6d  _v2(). ^If the m
220a0 6f 64 65 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ode option is se
220b0 74 20 74 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77  t to .**     "rw
220c0 22 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  ", then the data
220d0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
220e0 6f 72 20 72 65 61 64 2d 77 72 69 74 65 20 28 62  or read-write (b
220f0 75 74 20 6e 6f 74 20 63 72 65 61 74 65 29 20 0a  ut not create) .
22100 2a 2a 20 20 20 20 20 61 63 63 65 73 73 2c 20 61  **     access, a
22110 73 20 69 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e  s if SQLITE_OPEN
22120 5f 52 45 41 44 57 52 49 54 45 20 28 62 75 74 20  _READWRITE (but 
22130 6e 6f 74 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  not SQLITE_OPEN_
22140 43 52 45 41 54 45 29 20 68 61 64 20 0a 2a 2a 20  CREATE) had .** 
22150 20 20 20 20 62 65 65 6e 20 73 65 74 2e 20 5e 56      been set. ^V
22160 61 6c 75 65 20 22 72 77 63 22 20 69 73 20 65 71  alue "rwc" is eq
22170 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
22180 69 6e 67 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20  ing both .**    
22190 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
221a0 44 57 52 49 54 45 20 61 6e 64 20 53 51 4c 49 54  DWRITE and SQLIT
221b0 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2e 20 20  E_OPEN_CREATE.  
221c0 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f 70 74  ^If the mode opt
221d0 69 6f 6e 20 69 73 0a 2a 2a 20 20 20 20 20 73 65  ion is.**     se
221e0 74 20 74 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68  t to "memory" th
221f0 65 6e 20 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65  en a pure [in-me
22200 6d 6f 72 79 20 64 61 74 61 62 61 73 65 5d 20 74  mory database] t
22210 68 61 74 20 6e 65 76 65 72 20 72 65 61 64 73 0a  hat never reads.
22220 2a 2a 20 20 20 20 20 6f 72 20 77 72 69 74 65 73  **     or writes
22230 20 66 72 6f 6d 20 64 69 73 6b 20 69 73 20 75 73   from disk is us
22240 65 64 2e 20 5e 49 74 20 69 73 20 61 6e 20 65 72  ed. ^It is an er
22250 72 6f 72 20 74 6f 20 73 70 65 63 69 66 79 20 61  ror to specify a
22260 20 76 61 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20   value for.**   
22270 20 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d    the mode param
22280 65 74 65 72 20 74 68 61 74 20 69 73 20 6c 65 73  eter that is les
22290 73 20 72 65 73 74 72 69 63 74 69 76 65 20 74 68  s restrictive th
222a0 61 6e 20 74 68 61 74 20 73 70 65 63 69 66 69 65  an that specifie
222b0 64 20 62 79 0a 2a 2a 20 20 20 20 20 74 68 65 20  d by.**     the 
222c0 66 6c 61 67 73 20 70 61 73 73 65 64 20 69 6e 20  flags passed in 
222d0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
222e0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ter to sqlite3_o
222f0 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20  pen_v2()..**.** 
22300 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c    <li> <b>cache<
22310 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63 68 65 20  /b>: ^The cache 
22320 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
22330 20 73 65 74 20 74 6f 20 65 69 74 68 65 72 20 22   set to either "
22340 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20  shared" or.**   
22350 20 20 22 70 72 69 76 61 74 65 22 2e 20 5e 53 65    "private". ^Se
22360 74 74 69 6e 67 20 69 74 20 74 6f 20 22 73 68 61  tting it to "sha
22370 72 65 64 22 20 69 73 20 65 71 75 69 76 61 6c 65  red" is equivale
22380 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68  nt to setting th
22390 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f  e.**     SQLITE_
223a0 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
223b0 20 62 69 74 20 69 6e 20 74 68 65 20 66 6c 61 67   bit in the flag
223c0 73 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  s argument passe
223d0 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69  d to.**     sqli
223e0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e  te3_open_v2(). ^
223f0 53 65 74 74 69 6e 67 20 74 68 65 20 63 61 63 68  Setting the cach
22400 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 22  e parameter to "
22410 70 72 69 76 61 74 65 22 20 69 73 20 0a 2a 2a 20  private" is .** 
22420 20 20 20 20 65 71 75 69 76 61 6c 65 6e 74 20 74      equivalent t
22430 6f 20 73 65 74 74 69 6e 67 20 74 68 65 20 53 51  o setting the SQ
22440 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54  LITE_OPEN_PRIVAT
22450 45 43 41 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20  ECACHE bit..**  
22460 20 20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f     ^If sqlite3_o
22470 70 65 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64  pen_v2() is used
22480 20 61 6e 64 20 74 68 65 20 22 63 61 63 68 65 22   and the "cache"
22490 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
224a0 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20  esent in.**     
224b0 61 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20  a URI filename, 
224c0 69 74 73 20 76 61 6c 75 65 20 6f 76 65 72 72 69  its value overri
224d0 64 65 73 20 61 6e 79 20 62 65 68 61 76 69 6f 72  des any behavior
224e0 20 72 65 71 75 65 73 74 65 64 20 62 79 20 73 65   requested by se
224f0 74 74 69 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c  tting.**     SQL
22500 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
22510 43 41 43 48 45 20 6f 72 20 53 51 4c 49 54 45 5f  CACHE or SQLITE_
22520 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
22530 20 66 6c 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c   flag..**.**  <l
22540 69 3e 20 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20  i> <b>psow</b>: 
22550 5e 54 68 65 20 70 73 6f 77 20 70 61 72 61 6d 65  ^The psow parame
22560 74 65 72 20 6d 61 79 20 62 65 20 22 74 72 75 65  ter may be "true
22570 22 20 28 6f 72 20 22 6f 6e 22 20 6f 72 20 22 79  " (or "on" or "y
22580 65 73 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 31  es" or.**     "1
22590 22 29 20 6f 72 20 22 66 61 6c 73 65 22 20 28 6f  ") or "false" (o
225a0 72 20 22 6f 66 66 22 20 6f 72 20 22 6e 6f 22 20  r "off" or "no" 
225b0 6f 72 20 22 30 22 29 20 74 6f 20 69 6e 64 69 63  or "0") to indic
225c0 61 74 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20  ate that the.** 
225d0 20 20 20 20 5b 70 6f 77 65 72 73 61 66 65 20 6f      [powersafe o
225e0 76 65 72 77 72 69 74 65 5d 20 70 72 6f 70 65 72  verwrite] proper
225f0 74 79 20 64 6f 65 73 20 6f 72 20 64 6f 65 73 20  ty does or does 
22600 6e 6f 74 20 61 70 70 6c 79 20 74 6f 20 74 68 65  not apply to the
22610 0a 2a 2a 20 20 20 20 20 73 74 6f 72 61 67 65 20  .**     storage 
22620 6d 65 64 69 61 20 6f 6e 20 77 68 69 63 68 20 74  media on which t
22630 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22640 20 72 65 73 69 64 65 73 2e 20 20 5e 54 68 65 20   resides.  ^The 
22650 70 73 6f 77 20 71 75 65 72 79 0a 2a 2a 20 20 20  psow query.**   
22660 20 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 6c 79    parameter only
22670 20 77 6f 72 6b 73 20 66 6f 72 20 74 68 65 20 62   works for the b
22680 75 69 6c 74 2d 69 6e 20 75 6e 69 78 20 61 6e 64  uilt-in unix and
22690 20 57 69 6e 64 6f 77 73 20 56 46 53 65 73 2e 0a   Windows VFSes..
226a0 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e  **.**  <li> <b>n
226b0 6f 6c 6f 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20  olock</b>: ^The 
226c0 6e 6f 6c 6f 63 6b 20 70 61 72 61 6d 65 74 65 72  nolock parameter
226d0 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75   is a boolean qu
226e0 65 72 79 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ery parameter.**
226f0 20 20 20 20 20 77 68 69 63 68 20 69 66 20 73 65       which if se
22700 74 20 64 69 73 61 62 6c 65 73 20 66 69 6c 65 20  t disables file 
22710 6c 6f 63 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62  locking in rollb
22720 61 63 6b 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65  ack journal mode
22730 73 2e 20 20 54 68 69 73 0a 2a 2a 20 20 20 20 20  s.  This.**     
22740 69 73 20 75 73 65 66 75 6c 20 66 6f 72 20 61 63  is useful for ac
22750 63 65 73 73 69 6e 67 20 61 20 64 61 74 61 62 61  cessing a databa
22760 73 65 20 6f 6e 20 61 20 66 69 6c 65 73 79 73 74  se on a filesyst
22770 65 6d 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74  em that does not
22780 0a 2a 2a 20 20 20 20 20 73 75 70 70 6f 72 74 20  .**     support 
22790 6c 6f 63 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f  locking.  Cautio
227a0 6e 3a 20 20 44 61 74 61 62 61 73 65 20 63 6f 72  n:  Database cor
227b0 72 75 70 74 69 6f 6e 20 6d 69 67 68 74 20 72 65  ruption might re
227c0 73 75 6c 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20  sult if two.**  
227d0 20 20 20 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65     or more proce
227e0 73 73 65 73 20 77 72 69 74 65 20 74 6f 20 74 68  sses write to th
227f0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
22800 61 6e 64 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74  and any one of t
22810 68 6f 73 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63  hose.**     proc
22820 65 73 73 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63  esses uses noloc
22830 6b 3d 31 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e  k=1..**.**  <li>
22840 20 3c 62 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62   <b>immutable</b
22850 3e 3a 20 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c  >: ^The immutabl
22860 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  e parameter is a
22870 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a   boolean query.*
22880 2a 20 20 20 20 20 70 61 72 61 6d 65 74 65 72 20  *     parameter 
22890 74 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 74  that indicates t
228a0 68 61 74 20 74 68 65 20 64 61 74 61 62 61 73 65  hat the database
228b0 20 66 69 6c 65 20 69 73 20 73 74 6f 72 65 64 20   file is stored 
228c0 6f 6e 0a 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f  on.**     read-o
228d0 6e 6c 79 20 6d 65 64 69 61 2e 20 20 5e 57 68 65  nly media.  ^Whe
228e0 6e 20 69 6d 6d 75 74 61 62 6c 65 20 69 73 20 73  n immutable is s
228f0 65 74 2c 20 53 51 4c 69 74 65 20 61 73 73 75 6d  et, SQLite assum
22900 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20  es that the.**  
22910 20 20 20 64 61 74 61 62 61 73 65 20 66 69 6c 65     database file
22920 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
22930 65 64 2c 20 65 76 65 6e 20 62 79 20 61 20 70 72  ed, even by a pr
22940 6f 63 65 73 73 20 77 69 74 68 20 68 69 67 68 65  ocess with highe
22950 72 0a 2a 2a 20 20 20 20 20 70 72 69 76 69 6c 65  r.**     privile
22960 67 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20 64  ge, and so the d
22970 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
22980 64 20 72 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20  d read-only and 
22990 61 6c 6c 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20  all locking.**  
229a0 20 20 20 61 6e 64 20 63 68 61 6e 67 65 20 64 65     and change de
229b0 74 65 63 74 69 6f 6e 20 69 73 20 64 69 73 61 62  tection is disab
229c0 6c 65 64 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53  led.  Caution: S
229d0 65 74 74 69 6e 67 20 74 68 65 20 69 6d 6d 75 74  etting the immut
229e0 61 62 6c 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70  able.**     prop
229f0 65 72 74 79 20 6f 6e 20 61 20 64 61 74 61 62 61  erty on a databa
22a00 73 65 20 66 69 6c 65 20 74 68 61 74 20 64 6f 65  se file that doe
22a10 73 20 69 6e 20 66 61 63 74 20 63 68 61 6e 67 65  s in fact change
22a20 20 63 61 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20   can result.**  
22a30 20 20 20 69 6e 20 69 6e 63 6f 72 72 65 63 74 20     in incorrect 
22a40 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 61 6e  query results an
22a50 64 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52  d/or [SQLITE_COR
22a60 52 55 50 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a  RUPT] errors..**
22a70 20 20 20 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b       See also: [
22a80 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
22a90 55 54 41 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20  UTABLE]..**     
22aa0 20 20 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a    .** </ul>.**.*
22ab0 2a 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  * ^Specifying an
22ac0 20 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74   unknown paramet
22ad0 65 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20  er in the query 
22ae0 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55  component of a U
22af0 52 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20  RI is not an.** 
22b00 65 72 72 6f 72 2e 20 20 46 75 74 75 72 65 20 76  error.  Future v
22b10 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
22b20 65 20 6d 69 67 68 74 20 75 6e 64 65 72 73 74 61  e might understa
22b30 6e 64 20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75  nd additional qu
22b40 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
22b50 73 2e 20 20 53 65 65 20 22 5b 71 75 65 72 79 20  s.  See "[query 
22b60 70 61 72 61 6d 65 74 65 72 73 20 77 69 74 68 20  parameters with 
22b70 73 70 65 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20  special meaning 
22b80 74 6f 20 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a  to SQLite]" for.
22b90 2a 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** additional in
22ba0 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
22bb0 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 20   [[URI filename 
22bc0 65 78 61 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55  examples]] <h3>U
22bd0 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d  RI filename exam
22be0 70 6c 65 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20  ples</h3>.**.** 
22bf0 3c 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31  <table border="1
22c00 22 20 61 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63  " align=center c
22c10 65 6c 6c 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a  ellpadding=5>.**
22c20 20 3c 74 72 3e 3c 74 68 3e 20 55 52 49 20 66 69   <tr><th> URI fi
22c30 6c 65 6e 61 6d 65 73 20 3c 74 68 3e 20 52 65 73  lenames <th> Res
22c40 75 6c 74 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  ults.** <tr><td>
22c50 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74   file:data.db <t
22c60 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22c70 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64  Open the file "d
22c80 61 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63  ata.db" in the c
22c90 75 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79  urrent directory
22ca0 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22cb0 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
22cc0 74 61 2e 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20  ta.db<br>.**    
22cd0 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f        file:///ho
22ce0 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22cf0 3c 62 72 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <br> .**        
22d00 20 20 66 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f    file://localho
22d10 73 74 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  st/home/fred/dat
22d20 61 2e 64 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a  a.db <br> <td> .
22d30 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22d50 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  le "/home/fred/d
22d60 61 74 61 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e  ata.db"..** <tr>
22d70 3c 74 64 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b  <td> file://dark
22d80 73 74 61 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64  star/home/fred/d
22d90 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
22da0 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f           An erro
22db0 72 2e 20 22 64 61 72 6b 73 74 61 72 22 20 69 73  r. "darkstar" is
22dc0 20 6e 6f 74 20 61 20 72 65 63 6f 67 6e 69 7a 65   not a recognize
22dd0 64 20 61 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20  d authority..** 
22de0 3c 74 72 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77  <tr><td style="w
22df0 68 69 74 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61  hite-space:nowra
22e00 70 22 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  p"> .**         
22e10 20 66 69 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75   file:///C:/Docu
22e20 6d 65 6e 74 73 25 32 30 61 6e 64 25 32 30 53 65  ments%20and%20Se
22e30 74 74 69 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b  ttings/fred/Desk
22e40 74 6f 70 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20  top/data.db.**  
22e50 20 20 20 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20     <td> Windows 
22e60 6f 6e 6c 79 3a 20 4f 70 65 6e 20 74 68 65 20 66  only: Open the f
22e70 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 6f 6e  ile "data.db" on
22e80 20 66 72 65 64 27 73 20 64 65 73 6b 74 6f 70 20   fred's desktop 
22e90 6f 6e 20 64 72 69 76 65 0a 2a 2a 20 20 20 20 20  on drive.**     
22ea0 20 20 20 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68       C:. Note th
22eb0 61 74 20 74 68 65 20 25 32 30 20 65 73 63 61 70  at the %20 escap
22ec0 69 6e 67 20 69 6e 20 74 68 69 73 20 65 78 61 6d  ing in this exam
22ed0 70 6c 65 20 69 73 20 6e 6f 74 20 73 74 72 69 63  ple is not stric
22ee0 74 6c 79 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  tly .**         
22ef0 20 6e 65 63 65 73 73 61 72 79 20 2d 20 73 70 61   necessary - spa
22f00 63 65 20 63 68 61 72 61 63 74 65 72 73 20 63 61  ce characters ca
22f10 6e 20 62 65 20 75 73 65 64 20 6c 69 74 65 72 61  n be used litera
22f20 6c 6c 79 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  lly.**          
22f30 69 6e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  in URI filenames
22f40 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
22f50 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d  le:data.db?mode=
22f60 72 6f 26 63 61 63 68 65 3d 70 72 69 76 61 74 65  ro&cache=private
22f70 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
22f80 20 20 20 4f 70 65 6e 20 66 69 6c 65 20 22 64 61     Open file "da
22f90 74 61 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75  ta.db" in the cu
22fa0 72 72 65 6e 74 20 64 69 72 65 63 74 6f 72 79 20  rrent directory 
22fb0 66 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63  for read-only ac
22fc0 63 65 73 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20  cess..**        
22fd0 20 20 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20    Regardless of 
22fe0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 73  whether or not s
22ff0 68 61 72 65 64 2d 63 61 63 68 65 20 6d 6f 64 65  hared-cache mode
23000 20 69 73 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a   is enabled by.*
23010 2a 20 20 20 20 20 20 20 20 20 20 64 65 66 61 75  *          defau
23020 6c 74 2c 20 75 73 65 20 61 20 70 72 69 76 61 74  lt, use a privat
23030 65 20 63 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e  e cache..** <tr>
23040 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f  <td> file:/home/
23050 66 72 65 64 2f 64 61 74 61 2e 64 62 3f 76 66 73  fred/data.db?vfs
23060 3d 75 6e 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74  =unix-dotfile <t
23070 64 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f  d>.**          O
23080 70 65 6e 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f  pen file "/home/
23090 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e 20 55  fred/data.db". U
230a0 73 65 20 74 68 65 20 73 70 65 63 69 61 6c 20 56  se the special V
230b0 46 53 20 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65  FS "unix-dotfile
230c0 22 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 74 68  ".**          th
230d0 61 74 20 75 73 65 73 20 64 6f 74 2d 66 69 6c 65  at uses dot-file
230e0 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f  s in place of po
230f0 73 69 78 20 61 64 76 69 73 6f 72 79 20 6c 6f 63  six advisory loc
23100 6b 69 6e 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  king..** <tr><td
23110 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d  > file:data.db?m
23120 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64  ode=readonly <td
23130 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 41  > .**          A
23140 6e 20 65 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e  n error. "readon
23150 6c 79 22 20 69 73 20 6e 6f 74 20 61 20 76 61 6c  ly" is not a val
23160 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68  id option for th
23170 65 20 22 6d 6f 64 65 22 20 70 61 72 61 6d 65 74  e "mode" paramet
23180 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  er..** </table>.
23190 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65 78 61 64  **.** ^URI hexad
231a0 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
231b0 71 75 65 6e 63 65 73 20 28 25 48 48 29 20 61 72  quences (%HH) ar
231c0 65 20 73 75 70 70 6f 72 74 65 64 20 77 69 74 68  e supported with
231d0 69 6e 20 74 68 65 20 70 61 74 68 20 61 6e 64 0a  in the path and.
231e0 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  ** query compone
231f0 6e 74 73 20 6f 66 20 61 20 55 52 49 2e 20 41 20  nts of a URI. A 
23200 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23210 70 65 20 73 65 71 75 65 6e 63 65 20 63 6f 6e 73  pe sequence cons
23220 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72  ists of a.** per
23230 63 65 6e 74 20 73 69 67 6e 20 2d 20 22 25 22 20  cent sign - "%" 
23240 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78  - followed by ex
23250 61 63 74 6c 79 20 74 77 6f 20 68 65 78 61 64 65  actly two hexade
23260 63 69 6d 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a  cimal digits .**
23270 20 73 70 65 63 69 66 79 69 6e 67 20 61 6e 20 6f   specifying an o
23280 63 74 65 74 20 76 61 6c 75 65 2e 20 5e 42 65 66  ctet value. ^Bef
23290 6f 72 65 20 74 68 65 20 70 61 74 68 20 6f 72 20  ore the path or 
232a0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
232b0 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c   of a.** URI fil
232c0 65 6e 61 6d 65 20 61 72 65 20 69 6e 74 65 72 70  ename are interp
232d0 72 65 74 65 64 2c 20 74 68 65 79 20 61 72 65 20  reted, they are 
232e0 65 6e 63 6f 64 65 64 20 75 73 69 6e 67 20 55 54  encoded using UT
232f0 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20  F-8 and all .** 
23300 68 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61  hexadecimal esca
23310 70 65 20 73 65 71 75 65 6e 63 65 73 20 72 65 70  pe sequences rep
23320 6c 61 63 65 64 20 62 79 20 61 20 73 69 6e 67 6c  laced by a singl
23330 65 20 62 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e  e byte containin
23340 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70  g the.** corresp
23350 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e 20 49 66  onding octet. If
23360 20 74 68 69 73 20 70 72 6f 63 65 73 73 20 67 65   this process ge
23370 6e 65 72 61 74 65 73 20 61 6e 20 69 6e 76 61 6c  nerates an inval
23380 69 64 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  id UTF-8 encodin
23390 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74  g,.** the result
233a0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
233b0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
233c0 6f 20 57 69 6e 64 6f 77 73 20 75 73 65 72 73 3a  o Windows users:
233d0 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63 6f 64 69  </b>  The encodi
233e0 6e 67 20 75 73 65 64 20 66 6f 72 20 74 68 65 20  ng used for the 
233f0 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
23400 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  t.** of sqlite3_
23410 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
23420 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73  e3_open_v2() mus
23430 74 20 62 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20  t be UTF-8, not 
23440 77 68 61 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65  whatever.** code
23450 70 61 67 65 20 69 73 20 63 75 72 72 65 6e 74 6c  page is currentl
23460 79 20 64 65 66 69 6e 65 64 2e 20 20 46 69 6c 65  y defined.  File
23470 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67  names containing
23480 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a   international.*
23490 2a 20 63 68 61 72 61 63 74 65 72 73 20 6d 75 73  * characters mus
234a0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 20 74  t be converted t
234b0 6f 20 55 54 46 2d 38 20 70 72 69 6f 72 20 74 6f  o UTF-8 prior to
234c0 20 70 61 73 73 69 6e 67 20 74 68 65 6d 20 69 6e   passing them in
234d0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70  to.** sqlite3_op
234e0 65 6e 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  en() or sqlite3_
234f0 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  open_v2()..**.**
23500 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64   <b>Note to Wind
23510 6f 77 73 20 52 75 6e 74 69 6d 65 20 75 73 65 72  ows Runtime user
23520 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74 65 6d 70  s:</b>  The temp
23530 6f 72 61 72 79 20 64 69 72 65 63 74 6f 72 79 20  orary directory 
23540 6d 75 73 74 20 62 65 20 73 65 74 0a 2a 2a 20 70  must be set.** p
23550 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
23560 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f  sqlite3_open() o
23570 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  r sqlite3_open_v
23580 32 28 29 2e 20 20 4f 74 68 65 72 77 69 73 65 2c  2().  Otherwise,
23590 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74   various.** feat
235a0 75 72 65 73 20 74 68 61 74 20 72 65 71 75 69 72  ures that requir
235b0 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 65 6d  e the use of tem
235c0 70 6f 72 61 72 79 20 66 69 6c 65 73 20 6d 61 79  porary files may
235d0 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   fail..**.** See
235e0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
235f0 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a  temp_directory].
23600 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  */.int sqlite3_o
23610 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  pen(.  const cha
23620 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
23630 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23640 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
23650 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20   sqlite3 **ppDb 
23660 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
23670 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
23680 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  e */.);.int sqli
23690 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f  te3_open16(.  co
236a0 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61  nst void *filena
236b0 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73  me,   /* Databas
236c0 65 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d  e filename (UTF-
236d0 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  16) */.  sqlite3
236e0 20 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20   **ppDb         
236f0 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20   /* OUT: SQLite 
23700 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a  db handle */.);.
23710 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
23720 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  _v2(.  const cha
23730 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f  r *filename,   /
23740 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e  * Database filen
23750 61 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20  ame (UTF-8) */. 
23760 20 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c   sqlite3 **ppDb,
23770 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a           /* OUT:
23780 20 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c   SQLite db handl
23790 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73  e */.  int flags
237a0 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f  ,              /
237b0 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e  * Flags */.  con
237c0 73 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20  st char *zVfs   
237d0 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
237e0 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73  VFS module to us
237f0 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
23800 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20  API3REF: Obtain 
23810 56 61 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50  Values For URI P
23820 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
23830 54 68 65 73 65 20 61 72 65 20 75 74 69 6c 69 74  These are utilit
23840 79 20 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66  y routines, usef
23850 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d  ul to VFS implem
23860 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20  entations, that 
23870 63 68 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20  check.** to see 
23880 69 66 20 61 20 64 61 74 61 62 61 73 65 20 66 69  if a database fi
23890 6c 65 20 77 61 73 20 61 20 55 52 49 20 74 68 61  le was a URI tha
238a0 74 20 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70  t contained a sp
238b0 65 63 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a  ecific query .**
238c0 20 70 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20   parameter, and 
238d0 69 66 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68  if so obtains th
238e0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  e value of that 
238f0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e  query parameter.
23900 0a 2a 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74  .**.** If F is t
23910 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
23920 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73  name pointer pas
23930 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
23940 65 6e 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a  en() method of .
23950 2a 2a 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65  ** a VFS impleme
23960 6e 74 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65  ntation when the
23970 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
23980 20 74 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20   to xOpen() has 
23990 6f 6e 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20  one or .** more 
239a0 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  of the [SQLITE_O
239b0 50 45 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c  PEN_URI] or [SQL
239c0 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42  ITE_OPEN_MAIN_DB
239d0 5d 20 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a  ] bits set and.*
239e0 2a 20 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20  * P is the name 
239f0 6f 66 20 74 68 65 20 71 75 65 72 79 20 70 61 72  of the query par
23a00 61 6d 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20  ameter, then.** 
23a10 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23a20 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23a30 6e 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ns the value of 
23a40 74 68 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74  the P.** paramet
23a50 65 72 20 69 66 20 69 74 20 65 78 69 73 74 73 20  er if it exists 
23a60 6f 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  or a NULL pointe
23a70 72 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20  r if P does not 
23a80 61 70 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20  appear as a .** 
23a90 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23aa0 6f 6e 20 46 2e 20 20 49 66 20 50 20 69 73 20 61  on F.  If P is a
23ab0 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72   query parameter
23ac0 20 6f 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20   of F.** has no 
23ad0 65 78 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20  explicit value, 
23ae0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
23af0 5f 70 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20  _parameter(F,P) 
23b00 72 65 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69  returns.** a poi
23b10 6e 74 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79  nter to an empty
23b20 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54   string..**.** T
23b30 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23b40 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23b50 75 74 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68  utine assumes th
23b60 61 74 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61  at P is a boolea
23b70 6e 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61  n.** parameter a
23b80 6e 64 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  nd returns true 
23b90 28 31 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29  (1) or false (0)
23ba0 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68   according to th
23bb0 65 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e  e value.** of P.
23bc0 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72    The sqlite3_ur
23bd0 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29  i_boolean(F,P,B)
23be0 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
23bf0 20 74 72 75 65 20 28 31 29 20 69 66 20 74 68 65   true (1) if the
23c00 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65  .** value of que
23c10 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23c20 73 20 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20  s one of "yes", 
23c30 22 74 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20  "true", or "on" 
23c40 69 6e 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f  in any.** case o
23c50 72 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62  r if the value b
23c60 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e  egins with a non
23c70 2d 7a 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54  -zero number.  T
23c80 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  he .** sqlite3_u
23c90 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23ca0 29 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  ) routines retur
23cb0 6e 73 20 66 61 6c 73 65 20 28 30 29 20 69 66 20  ns false (0) if 
23cc0 74 68 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  the value of.** 
23cd0 71 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20  query parameter 
23ce0 50 20 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22  P is one of "no"
23cf0 2c 20 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f  , "false", or "o
23d00 66 66 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20  ff" in any case 
23d10 6f 72 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c  or.** if the val
23d20 75 65 20 62 65 67 69 6e 73 20 77 69 74 68 20 61  ue begins with a
23d30 20 6e 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20   numeric zero.  
23d40 49 66 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75  If P is not a qu
23d50 65 72 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ery.** parameter
23d60 20 6f 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20   on F or if the 
23d70 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f  value of P is do
23d80 65 73 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79  es not match any
23d90 20 6f 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65   of the.** above
23da0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75  , then sqlite3_u
23db0 72 69 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42  ri_boolean(F,P,B
23dc0 29 20 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29  ) returns (B!=0)
23dd0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
23de0 74 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c  te3_uri_int64(F,
23df0 50 2c 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e  P,D) routine con
23e00 76 65 72 74 73 20 74 68 65 20 76 61 6c 75 65 20  verts the value 
23e10 6f 66 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36  of P into a.** 6
23e20 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74  4-bit signed int
23e30 65 67 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73  eger and returns
23e40 20 74 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f   that integer, o
23e50 72 20 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f  r D if P does no
23e60 74 0a 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20  t.** exist.  If 
23e70 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69  the value of P i
23e80 73 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  s something othe
23e90 72 20 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65  r than an intege
23ea0 72 2c 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20  r, then.** zero 
23eb0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
23ec0 0a 2a 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55  .** If F is a NU
23ed0 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e  LL pointer, then
23ee0 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72   sqlite3_uri_par
23ef0 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75  ameter(F,P) retu
23f00 72 6e 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20  rns NULL and.** 
23f10 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23f20 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72  ean(F,P,B) retur
23f30 6e 73 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e  ns B.  If F is n
23f40 6f 74 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ot a NULL pointe
23f50 72 20 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20  r and.** is not 
23f60 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23f70 70 61 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72  pathname pointer
23f80 20 74 68 61 74 20 53 51 4c 69 74 65 20 70 61 73   that SQLite pas
23f90 73 65 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70  sed into the xOp
23fa0 65 6e 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64  en.** VFS method
23fb0 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
23fc0 69 6f 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ior of this rout
23fd0 69 6e 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ine is undefined
23fe0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a   and probably.**
23ff0 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f   undesirable..*/
24000 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24010 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
24020 65 72 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  er(const char *z
24030 46 69 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20  Filename, const 
24040 63 68 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69  char *zParam);.i
24050 6e 74 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  nt sqlite3_uri_b
24060 6f 6f 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61  oolean(const cha
24070 72 20 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20  r *zFile, const 
24080 63 68 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e  char *zParam, in
24090 74 20 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c  t bDefault);.sql
240a0 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74  ite3_int64 sqlit
240b0 65 33 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e  e3_uri_int64(con
240c0 73 74 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20  st char*, const 
240d0 63 68 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69  char*, sqlite3_i
240e0 6e 74 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  nt64);.../*.** C
240f0 41 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43  API3REF: Error C
24100 6f 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65  odes And Message
24110 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
24120 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69  ite3_errcode() i
24130 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24140 20 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65   the numeric [re
24150 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a  sult code] or.**
24160 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
24170 74 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  t code] for the 
24180 6d 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c  most recent fail
24190 65 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49  ed sqlite3_* API
241a0 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61   call.** associa
241b0 74 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61  ted with a [data
241c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
241d0 2e 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49  . If a prior API
241e0 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20   call failed.** 
241f0 62 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63  but the most rec
24200 65 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63  ent API call suc
24210 63 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75  ceeded, the retu
24220 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a  rn value from.**
24230 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65   sqlite3_errcode
24240 28 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  () is undefined.
24250 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65    ^The sqlite3_e
24260 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28  xtended_errcode(
24270 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69  ).** interface i
24280 73 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70  s the same excep
24290 74 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73  t that it always
242a0 20 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a   returns the .**
242b0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
242c0 74 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65  t code] even whe
242d0 6e 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  n extended resul
242e0 74 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64  t codes are.** d
242f0 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  isabled..**.** ^
24300 54 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  The sqlite3_errm
24310 73 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  sg() and sqlite3
24320 5f 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75  _errmsg16() retu
24330 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75  rn English-langu
24340 61 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74  age.** text that
24350 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65   describes the e
24360 72 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20  rror, as either 
24370 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20  UTF-8 or UTF-16 
24380 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
24390 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c   ^(Memory to hol
243a0 64 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  d the error mess
243b0 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61  age string is ma
243c0 6e 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  naged internally
243d0 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
243e0 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65  tion does not ne
243f0 65 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75  ed to worry abou
24400 74 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65  t freeing the re
24410 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72  sult..** However
24420 2c 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69  , the error stri
24430 6e 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72  ng might be over
24440 77 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c  written or deall
24450 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62  ocated by.** sub
24460 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f  sequent calls to
24470 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
24480 74 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e  terface function
24490 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  s.)^.**.** ^The 
244a0 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 29  sqlite3_errstr()
244b0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
244c0 6e 73 20 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c  ns the English-l
244d0 61 6e 67 75 61 67 65 20 74 65 78 74 0a 2a 2a 20  anguage text.** 
244e0 74 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74  that describes t
244f0 68 65 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d  he [result code]
24500 2c 20 61 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e  , as UTF-8..** ^
24510 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
24520 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
24530 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
24540 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a  ged internally.*
24550 2a 20 61 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62  * and must not b
24560 65 20 66 72 65 65 64 20 62 79 20 74 68 65 20 61  e freed by the a
24570 70 70 6c 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a  pplication)^..**
24580 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 73 65 72  .** When the ser
24590 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
245a0 6e 67 20 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75  ng mode] is in u
245b0 73 65 2c 20 69 74 20 6d 69 67 68 74 20 62 65 20  se, it might be 
245c0 74 68 65 0a 2a 2a 20 63 61 73 65 20 74 68 61 74  the.** case that
245d0 20 61 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20   a second error 
245e0 6f 63 63 75 72 73 20 6f 6e 20 61 20 73 65 70 61  occurs on a sepa
245f0 72 61 74 65 20 74 68 72 65 61 64 20 69 6e 20 62  rate thread in b
24600 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69  etween.** the ti
24610 6d 65 20 6f 66 20 74 68 65 20 66 69 72 73 74 20  me of the first 
24620 65 72 72 6f 72 20 61 6e 64 20 74 68 65 20 63 61  error and the ca
24630 6c 6c 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  ll to these inte
24640 72 66 61 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20  rfaces..** When 
24650 74 68 61 74 20 68 61 70 70 65 6e 73 2c 20 74 68  that happens, th
24660 65 20 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 77  e second error w
24670 69 6c 6c 20 62 65 20 72 65 70 6f 72 74 65 64 20  ill be reported 
24680 73 69 6e 63 65 20 74 68 65 73 65 0a 2a 2a 20 69  since these.** i
24690 6e 74 65 72 66 61 63 65 73 20 61 6c 77 61 79 73  nterfaces always
246a0 20 72 65 70 6f 72 74 20 74 68 65 20 6d 6f 73 74   report the most
246b0 20 72 65 63 65 6e 74 20 72 65 73 75 6c 74 2e 20   recent result. 
246c0 20 54 6f 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69   To avoid.** thi
246d0 73 2c 20 65 61 63 68 20 74 68 72 65 61 64 20 63  s, each thread c
246e0 61 6e 20 6f 62 74 61 69 6e 20 65 78 63 6c 75 73  an obtain exclus
246f0 69 76 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b  ive use of the [
24700 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24710 69 6f 6e 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76  ion] D.** by inv
24720 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d  oking [sqlite3_m
24730 75 74 65 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c  utex_enter]([sql
24740 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44  ite3_db_mutex](D
24750 29 29 20 62 65 66 6f 72 65 20 62 65 67 69 6e 6e  )) before beginn
24760 69 6e 67 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20  ing.** to use D 
24770 61 6e 64 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71  and invoking [sq
24780 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76  lite3_mutex_leav
24790 65 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d  e]([sqlite3_db_m
247a0 75 74 65 78 5d 28 44 29 29 20 61 66 74 65 72 0a  utex](D)) after.
247b0 2a 2a 20 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20  ** all calls to 
247c0 74 68 65 20 69 6e 74 65 72 66 61 63 65 73 20 6c  the interfaces l
247d0 69 73 74 65 64 20 68 65 72 65 20 61 72 65 20 63  isted here are c
247e0 6f 6d 70 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20  ompleted..**.** 
247f0 49 66 20 61 6e 20 69 6e 74 65 72 66 61 63 65 20  If an interface 
24800 66 61 69 6c 73 20 77 69 74 68 20 53 51 4c 49 54  fails with SQLIT
24810 45 5f 4d 49 53 55 53 45 2c 20 74 68 61 74 20 6d  E_MISUSE, that m
24820 65 61 6e 73 20 74 68 65 20 69 6e 74 65 72 66 61  eans the interfa
24830 63 65 0a 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65  ce.** was invoke
24840 64 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 62 79  d incorrectly by
24850 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
24860 2e 20 20 49 6e 20 74 68 61 74 20 63 61 73 65 2c  .  In that case,
24870 20 74 68 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f   the.** error co
24880 64 65 20 61 6e 64 20 6d 65 73 73 61 67 65 20 6d  de and message m
24890 61 79 20 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65  ay or may not be
248a0 20 73 65 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c   set..*/.int sql
248b0 69 74 65 33 5f 65 72 72 63 6f 64 65 28 73 71 6c  ite3_errcode(sql
248c0 69 74 65 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73  ite3 *db);.int s
248d0 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f  qlite3_extended_
248e0 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
248f0 2a 64 62 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  *db);.const char
24900 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
24910 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73  (sqlite3*);.cons
24920 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
24930 65 72 72 6d 73 67 31 36 28 73 71 6c 69 74 65 33  errmsg16(sqlite3
24940 2a 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  *);.const char *
24950 73 71 6c 69 74 65 33 5f 65 72 72 73 74 72 28 69  sqlite3_errstr(i
24960 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
24970 33 52 45 46 3a 20 53 51 4c 20 53 74 61 74 65 6d  3REF: SQL Statem
24980 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45  ent Object.** KE
24990 59 57 4f 52 44 53 3a 20 7b 70 72 65 70 61 72 65  YWORDS: {prepare
249a0 64 20 73 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72  d statement} {pr
249b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
249c0 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74  s}.**.** An inst
249d0 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a  ance of this obj
249e0 65 63 74 20 72 65 70 72 65 73 65 6e 74 73 20 61  ect represents a
249f0 20 73 69 6e 67 6c 65 20 53 51 4c 20 73 74 61 74   single SQL stat
24a00 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f  ement..** This o
24a10 62 6a 65 63 74 20 69 73 20 76 61 72 69 6f 75 73  bject is various
24a20 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70  ly known as a "p
24a30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
24a40 74 22 20 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70  t" or a.** "comp
24a50 69 6c 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  iled SQL stateme
24a60 6e 74 22 20 6f 72 20 73 69 6d 70 6c 79 20 61 73  nt" or simply as
24a70 20 61 20 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a   a "statement"..
24a80 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f  **.** The life o
24a90 66 20 61 20 73 74 61 74 65 6d 65 6e 74 20 6f 62  f a statement ob
24aa0 6a 65 63 74 20 67 6f 65 73 20 73 6f 6d 65 74 68  ject goes someth
24ab0 69 6e 67 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a  ing like this:.*
24ac0 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
24ad0 3e 20 43 72 65 61 74 65 20 74 68 65 20 6f 62 6a  > Create the obj
24ae0 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24af0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
24b00 20 6f 72 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a   or a related.**
24b10 20 20 20 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a        function..
24b20 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c  ** <li> Bind val
24b30 75 65 73 20 74 6f 20 5b 68 6f 73 74 20 70 61 72  ues to [host par
24b40 61 6d 65 74 65 72 73 5d 20 75 73 69 6e 67 20 74  ameters] using t
24b50 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
24b60 2a 28 29 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65  *().**      inte
24b70 72 66 61 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20  rfaces..** <li> 
24b80 52 75 6e 20 74 68 65 20 53 51 4c 20 62 79 20 63  Run the SQL by c
24b90 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
24ba0 73 74 65 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d  step()] one or m
24bb0 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c  ore times..** <l
24bc0 69 3e 20 52 65 73 65 74 20 74 68 65 20 73 74 61  i> Reset the sta
24bd0 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71  tement using [sq
24be0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
24bf0 68 65 6e 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20  hen go back.**  
24c00 20 20 20 20 74 6f 20 73 74 65 70 20 32 2e 20 20      to step 2.  
24c10 44 6f 20 74 68 69 73 20 7a 65 72 6f 20 6f 72 20  Do this zero or 
24c20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c  more times..** <
24c30 6c 69 3e 20 44 65 73 74 72 6f 79 20 74 68 65 20  li> Destroy the 
24c40 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73 71  object using [sq
24c50 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
24c60 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  ]..** </ol>.**.*
24c70 2a 20 52 65 66 65 72 20 74 6f 20 64 6f 63 75 6d  * Refer to docum
24c80 65 6e 74 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  entation on indi
24c90 76 69 64 75 61 6c 20 6d 65 74 68 6f 64 73 20 61  vidual methods a
24ca0 62 6f 76 65 20 66 6f 72 20 61 64 64 69 74 69 6f  bove for additio
24cb0 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
24cc0 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  on..*/.typedef s
24cd0 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 73 74  truct sqlite3_st
24ce0 6d 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b  mt sqlite3_stmt;
24cf0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24d00 3a 20 52 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74  : Run-time Limit
24d10 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69  s.**.** ^(This i
24d20 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 20  nterface allows 
24d30 74 68 65 20 73 69 7a 65 20 6f 66 20 76 61 72 69  the size of vari
24d40 6f 75 73 20 63 6f 6e 73 74 72 75 63 74 73 20 74  ous constructs t
24d50 6f 20 62 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20  o be limited.** 
24d60 6f 6e 20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  on a connection 
24d70 62 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61  by connection ba
24d80 73 69 73 2e 20 20 54 68 65 20 66 69 72 73 74 20  sis.  The first 
24d90 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
24da0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
24db0 6e 6e 65 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20  nnection] whose 
24dc0 6c 69 6d 69 74 20 69 73 20 74 6f 20 62 65 20 73  limit is to be s
24dd0 65 74 20 6f 72 20 71 75 65 72 69 65 64 2e 20 20  et or queried.  
24de0 54 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61  The.** second pa
24df0 72 61 6d 65 74 65 72 20 69 73 20 6f 6e 65 20 6f  rameter is one o
24e00 66 20 74 68 65 20 5b 6c 69 6d 69 74 20 63 61 74  f the [limit cat
24e10 65 67 6f 72 69 65 73 5d 20 74 68 61 74 20 64 65  egories] that de
24e20 66 69 6e 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20  fine a.** class 
24e30 6f 66 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f  of constructs to
24e40 20 62 65 20 73 69 7a 65 20 6c 69 6d 69 74 65 64   be size limited
24e50 2e 20 20 54 68 65 20 74 68 69 72 64 20 70 61 72  .  The third par
24e60 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24e70 20 6e 65 77 20 6c 69 6d 69 74 20 66 6f 72 20 74   new limit for t
24e80 68 61 74 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e  hat construct.)^
24e90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e  .**.** ^If the n
24ea0 65 77 20 6c 69 6d 69 74 20 69 73 20 61 20 6e 65  ew limit is a ne
24eb0 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2c 20 74  gative number, t
24ec0 68 65 20 6c 69 6d 69 74 20 69 73 20 75 6e 63 68  he limit is unch
24ed0 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20  anged..** ^(For 
24ee0 65 61 63 68 20 6c 69 6d 69 74 20 63 61 74 65 67  each limit categ
24ef0 6f 72 79 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ory SQLITE_LIMIT
24f00 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65  _<i>NAME</i> the
24f10 72 65 20 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d  re is a .** [lim
24f20 69 74 73 20 7c 20 68 61 72 64 20 75 70 70 65 72  its | hard upper
24f30 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61   bound].** set a
24f40 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62  t compile-time b
24f50 79 20 61 20 43 20 70 72 65 70 72 6f 63 65 73 73  y a C preprocess
24f60 6f 72 20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a  or macro called.
24f70 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c  ** [limits | SQL
24f80 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c  ITE_MAX_<i>NAME<
24f90 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f  /i>]..** (The "_
24fa0 4c 49 4d 49 54 5f 22 20 69 6e 20 74 68 65 20 6e  LIMIT_" in the n
24fb0 61 6d 65 20 69 73 20 63 68 61 6e 67 65 64 20 74  ame is changed t
24fc0 6f 20 22 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a  o "_MAX_".))^.**
24fd0 20 5e 41 74 74 65 6d 70 74 73 20 74 6f 20 69 6e   ^Attempts to in
24fe0 63 72 65 61 73 65 20 61 20 6c 69 6d 69 74 20 61  crease a limit a
24ff0 62 6f 76 65 20 69 74 73 20 68 61 72 64 20 75 70  bove its hard up
25000 70 65 72 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a  per bound are.**
25010 20 73 69 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61   silently trunca
25020 74 65 64 20 74 6f 20 74 68 65 20 68 61 72 64 20  ted to the hard 
25030 75 70 70 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a  upper bound..**.
25040 2a 2a 20 5e 52 65 67 61 72 64 6c 65 73 73 20 6f  ** ^Regardless o
25050 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  f whether or not
25060 20 74 68 65 20 6c 69 6d 69 74 20 77 61 73 20 63   the limit was c
25070 68 61 6e 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20  hanged, the .** 
25080 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25090 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ] interface retu
250a0 72 6e 73 20 74 68 65 20 70 72 69 6f 72 20 76 61  rns the prior va
250b0 6c 75 65 20 6f 66 20 74 68 65 20 6c 69 6d 69 74  lue of the limit
250c0 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20  ..** ^Hence, to 
250d0 66 69 6e 64 20 74 68 65 20 63 75 72 72 65 6e 74  find the current
250e0 20 76 61 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69   value of a limi
250f0 74 20 77 69 74 68 6f 75 74 20 63 68 61 6e 67 69  t without changi
25100 6e 67 20 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79  ng it,.** simply
25110 20 69 6e 76 6f 6b 65 20 74 68 69 73 20 69 6e 74   invoke this int
25120 65 72 66 61 63 65 20 77 69 74 68 20 74 68 65 20  erface with the 
25130 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
25140 73 65 74 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a  set to -1..**.**
25150 20 52 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73   Run-time limits
25160 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f   are intended fo
25170 72 20 75 73 65 20 69 6e 20 61 70 70 6c 69 63 61  r use in applica
25180 74 69 6f 6e 73 20 74 68 61 74 20 6d 61 6e 61 67  tions that manag
25190 65 0a 2a 2a 20 62 6f 74 68 20 74 68 65 69 72 20  e.** both their 
251a0 6f 77 6e 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  own internal dat
251b0 61 62 61 73 65 20 61 6e 64 20 61 6c 73 6f 20 64  abase and also d
251c0 61 74 61 62 61 73 65 73 20 74 68 61 74 20 61 72  atabases that ar
251d0 65 20 63 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20  e controlled.** 
251e0 62 79 20 75 6e 74 72 75 73 74 65 64 20 65 78 74  by untrusted ext
251f0 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 2e 20 20  ernal sources.  
25200 41 6e 20 65 78 61 6d 70 6c 65 20 61 70 70 6c 69  An example appli
25210 63 61 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20  cation might be 
25220 61 0a 2a 2a 20 77 65 62 20 62 72 6f 77 73 65 72  a.** web browser
25230 20 74 68 61 74 20 68 61 73 20 69 74 73 20 6f 77   that has its ow
25240 6e 20 64 61 74 61 62 61 73 65 73 20 66 6f 72 20  n databases for 
25250 73 74 6f 72 69 6e 67 20 68 69 73 74 6f 72 79 20  storing history 
25260 61 6e 64 0a 2a 2a 20 73 65 70 61 72 61 74 65 20  and.** separate 
25270 64 61 74 61 62 61 73 65 73 20 63 6f 6e 74 72 6f  databases contro
25280 6c 6c 65 64 20 62 79 20 4a 61 76 61 53 63 72 69  lled by JavaScri
25290 70 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  pt applications 
252a0 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66  downloaded.** of
252b0 66 20 74 68 65 20 49 6e 74 65 72 6e 65 74 2e 20  f the Internet. 
252c0 20 54 68 65 20 69 6e 74 65 72 6e 61 6c 20 64 61   The internal da
252d0 74 61 62 61 73 65 73 20 63 61 6e 20 62 65 20 67  tabases can be g
252e0 69 76 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67  iven the.** larg
252f0 65 2c 20 64 65 66 61 75 6c 74 20 6c 69 6d 69 74  e, default limit
25300 73 2e 20 20 44 61 74 61 62 61 73 65 73 20 6d 61  s.  Databases ma
25310 6e 61 67 65 64 20 62 79 20 65 78 74 65 72 6e 61  naged by externa
25320 6c 20 73 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a  l sources can.**
25330 20 62 65 20 67 69 76 65 6e 20 6d 75 63 68 20 73   be given much s
25340 6d 61 6c 6c 65 72 20 6c 69 6d 69 74 73 20 64 65  maller limits de
25350 73 69 67 6e 65 64 20 74 6f 20 70 72 65 76 65 6e  signed to preven
25360 74 20 61 20 64 65 6e 69 61 6c 20 6f 66 20 73 65  t a denial of se
25370 72 76 69 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e  rvice.** attack.
25380 20 20 44 65 76 65 6c 6f 70 65 72 73 20 6d 69 67    Developers mig
25390 68 74 20 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20  ht also want to 
253a0 75 73 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  use the [sqlite3
253b0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
253c0 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  )].** interface 
253d0 74 6f 20 66 75 72 74 68 65 72 20 63 6f 6e 74 72  to further contr
253e0 6f 6c 20 75 6e 74 72 75 73 74 65 64 20 53 51 4c  ol untrusted SQL
253f0 2e 20 20 54 68 65 20 73 69 7a 65 20 6f 66 20 74  .  The size of t
25400 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
25410 72 65 61 74 65 64 20 62 79 20 61 6e 20 75 6e 74  reated by an unt
25420 72 75 73 74 65 64 20 73 63 72 69 70 74 20 63 61  rusted script ca
25430 6e 20 62 65 20 63 6f 6e 74 61 69 6e 65 64 20 75  n be contained u
25440 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78  sing the.** [max
25450 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
25460 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  AGMA]..**.** New
25470 20 72 75 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20   run-time limit 
25480 63 61 74 65 67 6f 72 69 65 73 20 6d 61 79 20 62  categories may b
25490 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
254a0 65 20 72 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69  e releases..*/.i
254b0 6e 74 20 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  nt sqlite3_limit
254c0 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69  (sqlite3*, int i
254d0 64 2c 20 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a  d, int newVal);.
254e0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
254f0 20 52 75 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20   Run-Time Limit 
25500 43 61 74 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45  Categories.** KE
25510 59 57 4f 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63  YWORDS: {limit c
25520 61 74 65 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74  ategory} {*limit
25530 20 63 61 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a   categories}.**.
25540 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
25550 74 73 20 64 65 66 69 6e 65 20 76 61 72 69 6f 75  ts define variou
25560 73 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69  s performance li
25570 6d 69 74 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  mits.** that can
25580 20 62 65 20 6c 6f 77 65 72 65 64 20 61 74 20 72   be lowered at r
25590 75 6e 2d 74 69 6d 65 20 75 73 69 6e 67 20 5b 73  un-time using [s
255a0 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e  qlite3_limit()].
255b0 0a 2a 2a 20 54 68 65 20 73 79 6e 6f 70 73 69 73  .** The synopsis
255c0 20 6f 66 20 74 68 65 20 6d 65 61 6e 69 6e 67 73   of the meanings
255d0 20 6f 66 20 74 68 65 20 76 61 72 69 6f 75 73 20   of the various 
255e0 6c 69 6d 69 74 73 20 69 73 20 73 68 6f 77 6e 20  limits is shown 
255f0 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69  below..** Additi
25600 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
25610 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20 61 74   is available at
25620 20 5b 6c 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74   [limits | Limit
25630 73 20 69 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a  s in SQLite]..**
25640 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51  .** <dl>.** [[SQ
25650 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
25660 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
25670 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64  _LIMIT_LENGTH</d
25680 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25690 78 69 6d 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e  ximum size of an
256a0 79 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  y string or BLOB
256b0 20 6f 72 20 74 61 62 6c 65 20 72 6f 77 2c 20 69   or table row, i
256c0 6e 20 62 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a  n bytes.<dd>)^.*
256d0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
256e0 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d  MIT_SQL_LENGTH]]
256f0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25700 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f  MIT_SQL_LENGTH</
25710 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25720 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25730 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
25740 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64  t, in bytes.</dd
25750 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25760 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d  TE_LIMIT_COLUMN]
25770 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  ] ^(<dt>SQLITE_L
25780 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e  IMIT_COLUMN</dt>
25790 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
257a0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  mum number of co
257b0 6c 75 6d 6e 73 20 69 6e 20 61 20 74 61 62 6c 65  lumns in a table
257c0 20 64 65 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69   definition or i
257d0 6e 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  n the.** result 
257e0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
257f0 5d 20 6f 72 20 74 68 65 20 6d 61 78 69 6d 75 6d  ] or the maximum
25800 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25810 6e 73 20 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a  ns in an index.*
25820 2a 20 6f 72 20 69 6e 20 61 6e 20 4f 52 44 45 52  * or in an ORDER
25830 20 42 59 20 6f 72 20 47 52 4f 55 50 20 42 59 20   BY or GROUP BY 
25840 63 6c 61 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a  clause.</dd>)^.*
25850 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25860 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d  MIT_EXPR_DEPTH]]
25870 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25880 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f  MIT_EXPR_DEPTH</
25890 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
258a0 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20  aximum depth of 
258b0 74 68 65 20 70 61 72 73 65 20 74 72 65 65 20 6f  the parse tree o
258c0 6e 20 61 6e 79 20 65 78 70 72 65 73 73 69 6f 6e  n any expression
258d0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
258e0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  [SQLITE_LIMIT_CO
258f0 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20  MPOUND_SELECT]] 
25900 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d  ^(<dt>SQLITE_LIM
25910 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
25920 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  CT</dt>.** <dd>T
25930 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65  he maximum numbe
25940 72 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 61 20  r of terms in a 
25950 63 6f 6d 70 6f 75 6e 64 20 53 45 4c 45 43 54 20  compound SELECT 
25960 73 74 61 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29  statement.</dd>)
25970 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
25980 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d  _LIMIT_VDBE_OP]]
25990 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
259a0 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e  MIT_VDBE_OP</dt>
259b0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
259c0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e  mum number of in
259d0 73 74 72 75 63 74 69 6f 6e 73 20 69 6e 20 61 20  structions in a 
259e0 76 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20  virtual machine 
259f0 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20  program.** used 
25a00 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20  to implement an 
25a10 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
25a20 54 68 69 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f  This limit is no
25a30 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65  t currently.** e
25a40 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75 67 68 20  nforced, though 
25a50 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 61 64  that might be ad
25a60 64 65 64 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ded in some futu
25a70 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
25a80 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a   SQLite.</dd>)^.
25a90 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25aa0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
25ab0 47 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  G]] ^(<dt>SQLITE
25ac0 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25ad0 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ARG</dt>.** <dd>
25ae0 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  The maximum numb
25af0 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20  er of arguments 
25b00 6f 6e 20 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f  on a function.</
25b10 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
25b20 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43  LITE_LIMIT_ATTAC
25b30 48 45 44 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  HED]] ^(<dt>SQLI
25b40 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45  TE_LIMIT_ATTACHE
25b50 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
25b60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
25b70 20 6f 66 20 5b 41 54 54 41 43 48 20 7c 20 61 74   of [ATTACH | at
25b80 74 61 63 68 65 64 20 64 61 74 61 62 61 73 65 73  tached databases
25b90 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  ].)^</dd>.**.** 
25ba0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
25bb0 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
25bc0 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  TH]].** ^(<dt>SQ
25bd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
25be0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f  PATTERN_LENGTH</
25bf0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25c00 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
25c10 20 74 68 65 20 70 61 74 74 65 72 6e 20 61 72 67   the pattern arg
25c20 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49  ument to the [LI
25c30 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d  KE] or.** [GLOB]
25c40 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e   operators.</dd>
25c50 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
25c60 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
25c70 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c  _NUMBER]].** ^(<
25c80 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
25c90 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c  VARIABLE_NUMBER<
25ca0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25cb0 6d 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75  maximum index nu
25cc0 6d 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72  mber of any [par
25cd0 61 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51  ameter] in an SQ
25ce0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a  L statement.)^.*
25cf0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25d00 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25d10 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  H]] ^(<dt>SQLITE
25d20 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
25d30 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
25d40 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
25d50 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
25d60 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
25d70 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
25d80 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25d90 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
25da0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25db0 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
25dc0 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
25dd0 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
25de0 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
25df0 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
25e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25e10 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
25e20 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
25e30 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
25e40 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
25e50 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
25e60 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
25e70 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
25e80 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
25e90 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
25ea0 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
25eb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
25ec0 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
25ed0 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
25ee0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
25ef0 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
25f00 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
25f10 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
25f20 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
25f30 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
25f40 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
25f50 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
25f60 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
25f70 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
25f80 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
25f90 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
25fa0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
25fb0 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
25fc0 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
25fd0 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
25fe0 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
25ff0 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
26000 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
26010 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
26020 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
26030 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
26040 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
26050 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
26060 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
26070 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
26080 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
26090 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
260a0 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
260b0 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
260c0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
260d0 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
260e0 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
260f0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
26100 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
26110 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26120 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
26130 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
26140 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
26150 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
26160 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
26170 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
26180 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
26190 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
261a0 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
261b0 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
261c0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
261d0 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
261e0 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
261f0 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
26200 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
26210 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
26220 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
26230 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
26240 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
26250 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
26260 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
26270 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
26280 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
26290 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
262a0 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
262b0 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
262c0 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
262d0 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
262e0 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
262f0 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
26300 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
26310 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
26320 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
26330 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
26340 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
26350 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
26360 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
26370 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
26380 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
26390 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
263a0 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
263b0 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
263c0 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
263d0 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
263e0 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
263f0 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
26400 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
26410 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
26420 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
26430 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
26440 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
26450 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
26460 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
26470 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
26480 6f 72 20 62 79 74 65 73 20 61 73 20 74 68 69 73  or bytes as this
26490 20 73 61 76 65 73 20 53 51 4c 69 74 65 20 66 72   saves SQLite fr
264a0 6f 6d 20 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20  om having to.** 
264b0 6d 61 6b 65 20 61 20 63 6f 70 79 20 6f 66 20 74  make a copy of t
264c0 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e  he input string.
264d0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69  .**.** ^If pzTai
264e0 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68  l is not NULL th
264f0 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61  en *pzTail is ma
26500 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74  de to point to t
26510 68 65 20 66 69 72 73 74 20 62 79 74 65 0a 2a 2a  he first byte.**
26520 20 70 61 73 74 20 74 68 65 20 65 6e 64 20 6f 66   past the end of
26530 20 74 68 65 20 66 69 72 73 74 20 53 51 4c 20 73   the first SQL s
26540 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c  tatement in zSql
26550 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  .  These routine
26560 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c  s only.** compil
26570 65 20 74 68 65 20 66 69 72 73 74 20 73 74 61 74  e the first stat
26580 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73  ement in zSql, s
26590 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c 65 66  o *pzTail is lef
265a0 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a  t pointing to.**
265b0 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20 75 6e   what remains un
265c0 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  compiled..**.** 
265d0 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65 66 74  ^*ppStmt is left
265e0 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61 20 63   pointing to a c
265f0 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61 72 65  ompiled [prepare
26600 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
26610 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63  t can be.** exec
26620 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  uted using [sqli
26630 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49  te3_step()].  ^I
26640 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 65 72  f there is an er
26650 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69 73 20  ror, *ppStmt is 
26660 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20  set.** to NULL. 
26670 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74 20 74   ^If the input t
26680 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20  ext contains no 
26690 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e 70 75  SQL (if the inpu
266a0 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a  t is an empty.**
266b0 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d   string or a com
266c0 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70 53 74  ment) then *ppSt
266d0 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e 55 4c  mt is set to NUL
266e0 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e  L..** The callin
266f0 67 20 70 72 6f 63 65 64 75 72 65 20 69 73 20 72  g procedure is r
26700 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64  esponsible for d
26710 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f 6d 70  eleting the comp
26720 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74  iled.** SQL stat
26730 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c  ement using [sql
26740 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
26750 20 61 66 74 65 72 20 69 74 20 68 61 73 20 66 69   after it has fi
26760 6e 69 73 68 65 64 20 77 69 74 68 20 69 74 2e 0a  nished with it..
26770 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f  ** ppStmt may no
26780 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  t be NULL..**.**
26790 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20 74 68   ^On success, th
267a0 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  e sqlite3_prepar
267b0 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f  e() family of ro
267c0 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
267d0 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74  QLITE_OK];.** ot
267e0 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72 72 6f  herwise an [erro
267f0 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75 72  r code] is retur
26800 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ned..**.** The s
26810 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
26820 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  2() and sqlite3_
26830 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 20 69  prepare16_v2() i
26840 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a 2a 2a  nterfaces are.**
26850 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72   recommended for
26860 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d   all new program
26870 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64 65 72  s. The two older
26880 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
26890 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20  retained.** for 
268a0 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74  backwards compat
268b0 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74 68 65  ibility, but the
268c0 69 72 20 75 73 65 20 69 73 20 64 69 73 63 6f 75  ir use is discou
268d0 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68  raged..** ^In th
268e0 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
268f0 73 2c 20 74 68 65 20 70 72 65 70 61 72 65 64 20  s, the prepared 
26900 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61  statement.** tha
26910 74 20 69 73 20 72 65 74 75 72 6e 65 64 20 28 74  t is returned (t
26920 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74  he [sqlite3_stmt
26930 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74 61 69  ] object) contai
26940 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  ns a copy of the
26950 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c  .** original SQL
26960 20 74 65 78 74 2e 20 54 68 69 73 20 63 61 75 73   text. This caus
26970 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  es the [sqlite3_
26980 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66 61 63  step()] interfac
26990 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64  e to.** behave d
269a0 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20 74 68  ifferently in th
269b0 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20  ree ways:.**.** 
269c0 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  <ol>.** <li>.** 
269d0 5e 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65  ^If the database
269e0 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 73 2c   schema changes,
269f0 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65 74 75   instead of retu
26a00 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43  rning [SQLITE_SC
26a10 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61  HEMA] as it.** a
26a20 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20 64 6f  lways used to do
26a30 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
26a40 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69  )] will automati
26a50 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20  cally recompile 
26a60 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65  the SQL.** state
26a70 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74 6f 20  ment and try to 
26a80 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 20 41 73  run it again. As
26a90 20 6d 61 6e 79 20 61 73 20 5b 53 51 4c 49 54 45   many as [SQLITE
26aa0 5f 4d 41 58 5f 53 43 48 45 4d 41 5f 52 45 54 52  _MAX_SCHEMA_RETR
26ab0 59 5d 0a 2a 2a 20 72 65 74 72 69 65 73 20 77 69  Y].** retries wi
26ac0 6c 6c 20 6f 63 63 75 72 20 62 65 66 6f 72 65 20  ll occur before 
26ad0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 67  sqlite3_step() g
26ae0 69 76 65 73 20 75 70 20 61 6e 64 20 72 65 74 75  ives up and retu
26af0 72 6e 73 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a  rns an error..**
26b00 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   </li>.**.** <li
26b10 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72  >.** ^When an er
26b20 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c  ror occurs, [sql
26b30 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c  ite3_step()] wil
26b40 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20  l return one of 
26b50 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20  the detailed.** 
26b60 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72  [error codes] or
26b70 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72   [extended error
26b80 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c   codes].  ^The l
26b90 65 67 61 63 79 20 62 65 68 61 76 69 6f 72 20 77  egacy behavior w
26ba0 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69  as that.** [sqli
26bb0 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c  te3_step()] woul
26bc0 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20 61 20  d only return a 
26bd0 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54 45 5f  generic [SQLITE_
26be0 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f  ERROR] result co
26bf0 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20 61 70  de.** and the ap
26c00 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20  plication would 
26c10 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61 20 73  have to make a s
26c20 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73  econd call to [s
26c30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 0a  qlite3_reset()].
26c40 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 66  ** in order to f
26c50 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c 79 69  ind the underlyi
26c60 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68 65 20  ng cause of the 
26c70 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20 74 68  problem. With th
26c80 65 20 22 76 32 22 20 70 72 65 70 61 72 65 0a 2a  e "v2" prepare.*
26c90 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  * interfaces, th
26ca0 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72 65 61  e underlying rea
26cb0 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72 72 6f  son for the erro
26cc0 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d  r is returned im
26cd0 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f  mediately..** </
26ce0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
26cf0 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63 69 66  * ^If the specif
26d00 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64 20 74  ic value bound t
26d10 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c 20 68  o [parameter | h
26d20 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d 20 69  ost parameter] i
26d30 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52 45 20  n the .** WHERE 
26d40 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69 6e 66  clause might inf
26d50 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f 69 63  luence the choic
26d60 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20  e of query plan 
26d70 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e 74 2c  for a statement,
26d80 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73 74 61  .** then the sta
26d90 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20 61  tement will be a
26da0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 65 63  utomatically rec
26db0 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66 20 74  ompiled, as if t
26dc0 68 65 72 65 20 68 61 64 20 62 65 65 6e 20 0a 2a  here had been .*
26dd0 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67  * a schema chang
26de0 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73 74 20  e, on the first 
26df0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
26e00 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67  ] call following
26e10 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74   any change.** t
26e20 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  o the [sqlite3_b
26e30 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e 64 69  ind_text | bindi
26e40 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b 70 61  ngs] of that [pa
26e50 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54  rameter]. .** ^T
26e60 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
26e70 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61 75 73  e of WHERE-claus
26e80 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 6d 69  e [parameter] mi
26e90 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20 74 68  ght influence th
26ea0 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20  e .** choice of 
26eb0 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20 74 68  query plan if th
26ec0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  e parameter is t
26ed0 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73 69 64  he left-hand sid
26ee0 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a  e of a [LIKE].**
26ef0 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61   or [GLOB] opera
26f00 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20 70 61  tor or if the pa
26f10 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d 70 61  rameter is compa
26f20 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65 78 65  red to an indexe
26f30 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20  d column.** and 
26f40 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42  the [SQLITE_ENAB
26f50 4c 45 5f 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c  LE_STAT3] compil
26f60 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73  e-time option is
26f70 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c   enabled..** </l
26f80 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69  i>.** </ol>.*/.i
26f90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26fa0 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  re(.  sqlite3 *d
26fb0 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
26fc0 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
26fd0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
26fe0 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
26ff0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
27000 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
27010 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
27020 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
27030 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
27040 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
27050 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
27060 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
27070 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
27080 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
27090 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
270a0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
270b0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
270c0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
270d0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
270e0 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c 69  epare_v2(.  sqli
270f0 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
27100 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
27110 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27120 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20  t char *zSql,   
27130 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
27140 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f  ment, UTF-8 enco
27150 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
27160 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
27170 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
27180 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
27190 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
271a0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
271b0 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
271c0 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
271d0 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a 54  const char **pzT
271e0 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
271f0 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
27200 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
27210 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
27220 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a 20  te3_prepare16(. 
27230 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
27240 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
27250 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
27260 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71   const void *zSq
27270 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
27280 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31  statement, UTF-1
27290 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  6 encoded */.  i
272a0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
272b0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
272c0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
272d0 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
272e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
272f0 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
27300 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
27310 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
27320 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
27330 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
27340 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
27350 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
27360 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
27370 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  e16_v2(.  sqlite
27380 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
27390 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61    /* Database ha
273a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
273b0 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20  void *zSql,     
273c0 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65    /* SQL stateme
273d0 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f 64  nt, UTF-16 encod
273e0 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74  ed */.  int nByt
273f0 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  e,              
27400 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  /* Maximum lengt
27410 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74  h of zSql in byt
27420 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33  es. */.  sqlite3
27430 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20  _stmt **ppStmt, 
27440 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65   /* OUT: Stateme
27450 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63  nt handle */.  c
27460 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61  onst void **pzTa
27470 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50  il     /* OUT: P
27480 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64  ointer to unused
27490 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c   portion of zSql
274a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
274b0 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76 69  PI3REF: Retrievi
274c0 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51 4c  ng Statement SQL
274d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
274e0 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75 73  erface can be us
274f0 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20 61  ed to retrieve a
27500 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20 74   saved copy of t
27510 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53  he original.** S
27520 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f 20  QL text used to 
27530 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61 72  create a [prepar
27540 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 66  ed statement] if
27550 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20   that statement 
27560 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20  was.** compiled 
27570 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
27580 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
27590 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
275a0 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
275b0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
275c0 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c 69  sqlite3_sql(sqli
275d0 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29  te3_stmt *pStmt)
275e0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
275f0 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20  F: Determine If 
27600 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
27610 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74 61   Writes The Data
27620 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  base.**.** ^The 
27630 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61  sqlite3_stmt_rea
27640 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66 61  donly(X) interfa
27650 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65 20  ce returns true 
27660 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a  (non-zero) if.**
27670 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
27680 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27690 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f  ment] X makes no
276a0 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73 20   direct changes 
276b0 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e  to.** the conten
276c0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
276d0 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  e file..**.** No
276e0 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63 61  te that [applica
276f0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
27700 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a   functions] or.*
27710 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  * [virtual table
27720 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20  s] might change 
27730 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e 64  the database ind
27740 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69 64  irectly as a sid
27750 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e  e effect.  .** ^
27760 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69 66  (For example, if
27770 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
27780 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74 69  defines a functi
27790 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61 74  on "eval()" that
277a0 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69   .** calls [sqli
277b0 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68 65  te3_exec()], the
277c0 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  n the following 
277d0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 6f  SQL statement wo
277e0 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68  uld.** change th
277f0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
27800 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66 66  through side-eff
27810 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  ects:.**.** <blo
27820 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
27830 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c 28      SELECT eval(
27840 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31 27  'DELETE FROM t1'
27850 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f  ) FROM t2;.** </
27860 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
27870 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61  >.**.** But beca
27880 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54 5d  use the [SELECT]
27890 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20   statement does 
278a0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  not change the d
278b0 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20  atabase file.** 
278c0 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74 65  directly, sqlite
278d0 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
278e0 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65  ) would still re
278f0 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a  turn true.)^.**.
27900 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20  ** ^Transaction 
27910 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e  control statemen
27920 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47 49  ts such as [BEGI
27930 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52  N], [COMMIT], [R
27940 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41  OLLBACK],.** [SA
27950 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52  VEPOINT], and [R
27960 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73 71  ELEASE] cause sq
27970 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f  lite3_stmt_reado
27980 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e 20  nly() to return 
27990 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74  true,.** since t
279a0 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74 68  he statements th
279b0 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20  emselves do not 
279c0 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20  actually modify 
279d0 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75 74  the database but
279e0 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79 20  .** rather they 
279f0 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d 69  control the timi
27a00 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65 72  ng of when other
27a10 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69   statements modi
27a20 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61 62  fy the .** datab
27a30 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54 41  ase.  ^The [ATTA
27a40 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48 5d  CH] and [DETACH]
27a50 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f   statements also
27a60 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65   cause.** sqlite
27a70 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
27a80 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
27a90 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74 68   since, while th
27aa0 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  ose statements.*
27ab0 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f 6e  * change the con
27ac0 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61 20  figuration of a 
27ad0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
27ae0 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74  ion, they do not
27af0 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65   make .** change
27b00 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74  s to the content
27b10 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
27b20 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a   files on disk..
27b30 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73  */.int sqlite3_s
27b40 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c  tmt_readonly(sql
27b50 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
27b60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
27b70 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
27b80 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
27b90 65 6d 65 6e 74 20 48 61 73 20 42 65 65 6e 20 52  ement Has Been R
27ba0 65 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eset.**.** ^The 
27bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73  sqlite3_stmt_bus
27bc0 79 28 53 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(S) interface r
27bd0 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
27be0 2d 7a 65 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a  -zero) if the.**
27bf0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27c00 6d 65 6e 74 5d 20 53 20 68 61 73 20 62 65 65 6e  ment] S has been
27c10 20 73 74 65 70 70 65 64 20 61 74 20 6c 65 61 73   stepped at leas
27c20 74 20 6f 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a  t once using .**
27c30 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
27c40 29 5d 20 62 75 74 20 68 61 73 20 6e 6f 74 20 72  )] but has not r
27c50 75 6e 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  un to completion
27c60 20 61 6e 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20   and/or has not 
27c70 0a 2a 2a 20 62 65 65 6e 20 72 65 73 65 74 20 75  .** been reset u
27c80 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72 65  sing [sqlite3_re
27c90 73 65 74 28 53 29 5d 2e 20 20 5e 54 68 65 20 73  set(S)].  ^The s
27ca0 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
27cb0 28 53 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  (S).** interface
27cc0 20 72 65 74 75 72 6e 73 20 66 61 6c 73 65 20 69   returns false i
27cd0 66 20 53 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f S is a NULL po
27ce0 69 6e 74 65 72 2e 20 20 49 66 20 53 20 69 73 20  inter.  If S is 
27cf0 6e 6f 74 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70  not a .** NULL p
27d00 6f 69 6e 74 65 72 20 61 6e 64 20 69 73 20 6e 6f  ointer and is no
27d10 74 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  t a pointer to a
27d20 20 76 61 6c 69 64 20 5b 70 72 65 70 61 72 65 64   valid [prepared
27d30 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f   statement].** o
27d40 62 6a 65 63 74 2c 20 74 68 65 6e 20 74 68 65 20  bject, then the 
27d50 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
27d60 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62 61 62  fined and probab
27d70 6c 79 20 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a  ly undesirable..
27d80 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72  **.** This inter
27d90 66 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64  face can be used
27da0 20 69 6e 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20   in combination 
27db0 5b 73 71 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74  [sqlite3_next_st
27dc0 6d 74 28 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61  mt()].** to loca
27dd0 74 65 20 61 6c 6c 20 70 72 65 70 61 72 65 64 20  te all prepared 
27de0 73 74 61 74 65 6d 65 6e 74 73 20 61 73 73 6f 63  statements assoc
27df0 69 61 74 65 64 20 77 69 74 68 20 61 20 64 61 74  iated with a dat
27e00 61 62 61 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63  abase .** connec
27e10 74 69 6f 6e 20 74 68 61 74 20 61 72 65 20 69 6e  tion that are in
27e20 20 6e 65 65 64 20 6f 66 20 62 65 69 6e 67 20 72   need of being r
27e30 65 73 65 74 2e 20 20 54 68 69 73 20 63 61 6e 20  eset.  This can 
27e40 62 65 20 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20  be used,.** for 
27e50 65 78 61 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67  example, in diag
27e60 6e 6f 73 74 69 63 20 72 6f 75 74 69 6e 65 73 20  nostic routines 
27e70 74 6f 20 73 65 61 72 63 68 20 66 6f 72 20 70 72  to search for pr
27e80 65 70 61 72 65 64 20 0a 2a 2a 20 73 74 61 74 65  epared .** state
27e90 6d 65 6e 74 73 20 74 68 61 74 20 61 72 65 20 68  ments that are h
27ea0 6f 6c 64 69 6e 67 20 61 20 74 72 61 6e 73 61 63  olding a transac
27eb0 74 69 6f 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e  tion open..*/.in
27ec0 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62  t sqlite3_stmt_b
27ed0 75 73 79 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  usy(sqlite3_stmt
27ee0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27ef0 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
27f00 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
27f10 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
27f20 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
27f30 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
27f40 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27f50 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
27f60 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
27f70 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27f80 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
27f90 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
27fa0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
27fb0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
27fc0 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
27fd0 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
27fe0 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
27ff0 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
28000 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
28010 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28020 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
28030 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
28040 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
28050 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
28060 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
28070 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
28080 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
28090 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
280a0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
280b0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
280c0 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
280d0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
280e0 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
280f0 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
28100 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
28110 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
28120 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
28130 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
28140 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
28150 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
28160 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
28170 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
28180 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
28190 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
281a0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
281b0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
281c0 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
281d0 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
281e0 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
281f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
28200 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
28210 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
28220 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
28230 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
28240 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
28250 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
28260 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
28270 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
28280 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
28290 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
282a0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
282b0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
282c0 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
282d0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
282e0 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
282f0 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
28300 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
28310 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
28320 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
28330 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
28340 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
28350 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
28360 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
28370 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
28380 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
28390 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
283a0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
283b0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
283c0 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
283d0 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
283e0 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
283f0 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
28400 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
28410 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
28420 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
28430 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
28440 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
28450 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
28460 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
28470 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
28480 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
28490 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
284a0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
284b0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
284c0 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
284d0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
284e0 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
284f0 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
28500 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
28510 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
28520 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
28530 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
28540 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
28550 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
28560 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
28570 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
28580 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
28590 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
285a0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
285b0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
285c0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
285d0 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
285e0 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
285f0 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
28600 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
28610 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
28620 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
28630 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
28640 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
28650 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
28660 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
28670 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
28680 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
28690 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
286a0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
286b0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
286c0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
286d0 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
286e0 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
286f0 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
28700 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
28710 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
28720 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
28730 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
28740 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
28750 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
28760 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
28770 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
28780 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
28790 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
287a0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
287b0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
287c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
287d0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
287e0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
287f0 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
28800 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
28810 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
28820 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
28830 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
28840 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
28850 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
28860 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
28870 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
28880 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
28890 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
288a0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
288b0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
288c0 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
288d0 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
288e0 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
288f0 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
28900 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
28910 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
28920 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
28930 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
28940 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
28950 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
28960 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
28970 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
28980 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
28990 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
289a0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
289b0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
289c0 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
289d0 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
289e0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
289f0 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
28a00 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
28a10 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
28a20 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
28a30 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
28a40 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
28a50 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
28a60 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
28a70 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
28a80 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
28a90 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
28aa0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
28ab0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
28ac0 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
28ad0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
28ae0 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
28af0 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
28b00 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
28b10 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
28b20 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
28b30 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
28b40 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
28b50 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
28b60 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
28b70 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
28b80 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
28b90 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
28ba0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
28bb0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
28bc0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
28bd0 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
28be0 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
28bf0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
28c00 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
28c10 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
28c20 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
28c30 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
28c40 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
28c50 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
28c60 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
28c70 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28c80 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
28c90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
28ca0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
28cb0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
28cc0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
28cd0 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
28ce0 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
28cf0 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
28d00 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
28d10 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
28d20 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
28d30 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
28d40 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
28d50 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
28d60 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
28d70 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
28d80 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
28d90 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
28da0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
28db0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
28dc0 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
28dd0 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
28de0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
28df0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
28e00 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
28e10 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
28e20 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
28e30 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
28e40 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
28e50 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
28e60 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
28e70 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
28e80 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
28e90 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
28ea0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
28eb0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
28ec0 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
28ed0 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
28ee0 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
28ef0 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
28f00 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20  rameter..** ^If 
28f10 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
28f20 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ter to sqlite3_b
28f30 69 6e 64 5f 74 65 78 74 28 29 20 6f 72 20 73 71  ind_text() or sq
28f40 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31  lite3_bind_text1
28f50 36 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  6().** or sqlite
28f60 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73  3_bind_blob() is
28f70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
28f80 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20  then the fourth 
28f90 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20  parameter.** is 
28fa0 69 67 6e 6f 72 65 64 20 61 6e 64 20 74 68 65 20  ignored and the 
28fb0 65 6e 64 20 72 65 73 75 6c 74 20 69 73 20 74 68  end result is th
28fc0 65 20 73 61 6d 65 20 61 73 20 73 71 6c 69 74 65  e same as sqlite
28fd0 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a  3_bind_null()..*
28fe0 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20  *.** ^(In those 
28ff0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 68 61  routines that ha
29000 76 65 20 61 20 66 6f 75 72 74 68 20 61 72 67 75  ve a fourth argu
29010 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c 75 65 20  ment, its value 
29020 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72  is the.** number
29030 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
29040 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 6f 20   parameter.  To 
29050 62 65 20 63 6c 65 61 72 3a 20 74 68 65 20 76 61  be clear: the va
29060 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75  lue is the.** nu
29070 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79 74 65 73  mber of <u>bytes
29080 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76 61 6c 75  </u> in the valu
29090 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  e, not the numbe
290a0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
290b0 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f  )^.** ^If the fo
290c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  urth parameter t
290d0 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
290e0 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
290f0 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
29100 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  * is negative, t
29110 68 65 6e 20 74 68 65 20 6c 65 6e 67 74 68 20 6f  hen the length o
29120 66 20 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a  f the string is.
29130 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
29140 20 62 79 74 65 73 20 75 70 20 74 6f 20 74 68 65   bytes up to the
29150 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d   first zero term
29160 69 6e 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68  inator..** If th
29170 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
29180 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  er to sqlite3_bi
29190 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 6e 65 67  nd_blob() is neg
291a0 61 74 69 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74  ative, then.** t
291b0 68 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75  he behavior is u
291c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
291d0 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66  a non-negative f
291e0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
291f0 69 73 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73  is provided to s
29200 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
29210 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  ().** or sqlite3
29220 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 74  _bind_text16() t
29230 68 65 6e 20 74 68 61 74 20 70 61 72 61 6d 65 74  hen that paramet
29240 65 72 20 6d 75 73 74 20 62 65 20 74 68 65 20 62  er must be the b
29250 79 74 65 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68  yte offset.** wh
29260 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d  ere the NUL term
29270 69 6e 61 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63  inator would occ
29280 75 72 20 61 73 73 75 6d 69 6e 67 20 74 68 65 20  ur assuming the 
29290 73 74 72 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a  string were NUL.
292a0 2a 2a 20 74 65 72 6d 69 6e 61 74 65 64 2e 20 20  ** terminated.  
292b0 49 66 20 61 6e 79 20 4e 55 4c 20 63 68 61 72 61  If any NUL chara
292c0 63 74 65 72 73 20 6f 63 63 75 72 20 61 74 20 62  cters occur at b
292d0 79 74 65 20 6f 66 66 73 65 74 73 20 6c 65 73 73  yte offsets less
292e0 20 74 68 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61   than .** the va
292f0 6c 75 65 20 6f 66 20 74 68 65 20 66 6f 75 72 74  lue of the fourt
29300 68 20 70 61 72 61 6d 65 74 65 72 20 74 68 65 6e  h parameter then
29310 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
29320 74 72 69 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c  tring value will
29330 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65  .** contain embe
29340 64 64 65 64 20 4e 55 4c 73 2e 20 20 54 68 65 20  dded NULs.  The 
29350 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
29360 73 69 6f 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20  sions involving 
29370 73 74 72 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20  strings.** with 
29380 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
29390 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
293a0 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72 67  * ^The fifth arg
293b0 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
293c0 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71  _bind_blob(), sq
293d0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
293e0 29 2c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65  ), and.** sqlite
293f0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
29400 69 73 20 61 20 64 65 73 74 72 75 63 74 6f 72 20  is a destructor 
29410 75 73 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20  used to dispose 
29420 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a  of the BLOB or.*
29430 2a 20 73 74 72 69 6e 67 20 61 66 74 65 72 20 53  * string after S
29440 51 4c 69 74 65 20 68 61 73 20 66 69 6e 69 73 68  QLite has finish
29450 65 64 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68  ed with it.  ^Th
29460 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
29470 63 61 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73  called.** to dis
29480 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42  pose of the BLOB
29490 20 6f 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20   or string even 
294a0 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73  if the call to s
294b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
294c0 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  (),.** sqlite3_b
294d0 69 6e 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73  ind_text(), or s
294e0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
294f0 31 36 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a  16() fails.  .**
29500 20 5e 49 66 20 74 68 65 20 66 69 66 74 68 20 61   ^If the fifth a
29510 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68  rgument is.** th
29520 65 20 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20  e special value 
29530 5b 53 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c  [SQLITE_STATIC],
29540 20 74 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73   then SQLite ass
29550 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a  umes that the.**
29560 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20   information is 
29570 69 6e 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e  in static, unman
29580 61 67 65 64 20 73 70 61 63 65 20 61 6e 64 20 64  aged space and d
29590 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
295a0 62 65 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66  be freed..** ^If
295b0 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
295c0 65 6e 74 20 68 61 73 20 74 68 65 20 76 61 6c 75  ent has the valu
295d0 65 20 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49  e [SQLITE_TRANSI
295e0 45 4e 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  ENT], then.** SQ
295f0 4c 69 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f  Lite makes its o
29600 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20  wn private copy 
29610 6f 66 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65  of the data imme
29620 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a  diately, before.
29630 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ** the sqlite3_b
29640 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20  ind_*() routine 
29650 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e  returns..**.** ^
29660 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
29670 5f 7a 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74  _zeroblob() rout
29680 69 6e 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42  ine binds a BLOB
29690 20 6f 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61   of length N tha
296a0 74 0a 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77  t.** is filled w
296b0 69 74 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20  ith zeroes.  ^A 
296c0 7a 65 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20  zeroblob uses a 
296d0 66 69 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20  fixed amount of 
296e0 6d 65 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20  memory.** (just 
296f0 61 6e 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f  an integer to ho
29700 6c 64 20 69 74 73 20 73 69 7a 65 29 20 77 68 69  ld its size) whi
29710 6c 65 20 69 74 20 69 73 20 62 65 69 6e 67 20 70  le it is being p
29720 72 6f 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72  rocessed..** Zer
29730 6f 62 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e  oblobs are inten
29740 64 65 64 20 74 6f 20 73 65 72 76 65 20 61 73 20  ded to serve as 
29750 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72  placeholders for
29760 20 42 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20   BLOBs whose.** 
29770 63 6f 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72  content is later
29780 20 77 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a   written using.*
29790 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f  * [sqlite3_blob_
297a0 6f 70 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74  open | increment
297b0 61 6c 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75  al BLOB I/O] rou
297c0 74 69 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67  tines..** ^A neg
297d0 61 74 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20  ative value for 
297e0 74 68 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73  the zeroblob res
297f0 75 6c 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c  ults in a zero-l
29800 65 6e 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a  ength BLOB..**.*
29810 2a 20 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65  * ^If any of the
29820 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
29830 29 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  ) routines are c
29840 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c  alled with a NUL
29850 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72  L pointer.** for
29860 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
29870 74 61 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74  tatement] or wit
29880 68 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  h a prepared sta
29890 74 65 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68  tement for which
298a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
298b0 70 28 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61  p()] has been ca
298c0 6c 6c 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74  lled more recent
298d0 6c 79 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33  ly than [sqlite3
298e0 5f 72 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68  _reset()],.** th
298f0 65 6e 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c  en the call will
29900 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
29910 4d 49 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79  MISUSE].  If any
29920 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29   sqlite3_bind_()
29930 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70  .** routine is p
29940 61 73 73 65 64 20 61 20 5b 70 72 65 70 61 72 65  assed a [prepare
29950 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
29960 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c  t has been final
29970 69 7a 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73  ized, the.** res
29980 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ult is undefined
29990 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61   and probably ha
299a0 72 6d 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69  rmful..**.** ^Bi
299b0 6e 64 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63  ndings are not c
299c0 6c 65 61 72 65 64 20 62 79 20 74 68 65 20 5b 73  leared by the [s
299d0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
299e0 72 6f 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62  routine..** ^Unb
299f0 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20  ound parameters 
29a00 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
29a10 61 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  as NULL..**.** ^
29a20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  The sqlite3_bind
29a30 5f 2a 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  _* routines retu
29a40 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f  rn [SQLITE_OK] o
29a50 6e 20 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a  n success or an.
29a60 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  ** [error code] 
29a70 69 66 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73  if anything goes
29a80 20 77 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c   wrong..** ^[SQL
29a90 49 54 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65  ITE_RANGE] is re
29aa0 74 75 72 6e 65 64 20 69 66 20 74 68 65 20 70 61  turned if the pa
29ab0 72 61 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78  rameter.** index
29ac0 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65   is out of range
29ad0 2e 20 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  .  ^[SQLITE_NOME
29ae0 4d 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69  M] is returned i
29af0 66 20 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73  f malloc() fails
29b00 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29b10 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
29b20 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
29b30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
29b40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
29b50 61 6d 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c  ame()], and [sql
29b60 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29b70 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29b80 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29b90 64 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73  d_blob(sqlite3_s
29ba0 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
29bb0 20 76 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76   void*, int n, v
29bc0 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
29bd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29be0 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f  _double(sqlite3_
29bf0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62  stmt*, int, doub
29c00 6c 65 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  le);.int sqlite3
29c10 5f 62 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65  _bind_int(sqlite
29c20 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e  3_stmt*, int, in
29c30 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  t);.int sqlite3_
29c40 62 69 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74  bind_int64(sqlit
29c50 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73  e3_stmt*, int, s
29c60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69  qlite3_int64);.i
29c70 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29c80 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d  null(sqlite3_stm
29c90 74 2a 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71  t*, int);.int sq
29ca0 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
29cb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
29cc0 6e 74 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c  nt, const char*,
29cd0 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28   int n, void(*)(
29ce0 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c  void*));.int sql
29cf0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
29d00 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29d10 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  int, const void*
29d20 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76  , int, void(*)(v
29d30 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69  oid*));.int sqli
29d40 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73  te3_bind_value(s
29d50 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29d60 74 2c 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  t, const sqlite3
29d70 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
29d80 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62  lite3_bind_zerob
29d90 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
29da0 2a 2c 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a  *, int, int n);.
29db0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
29dc0 20 4e 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50   Number Of SQL P
29dd0 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20  arameters.**.** 
29de0 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61  ^This routine ca
29df0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e  n be used to fin
29e00 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  d the number of 
29e10 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d  [SQL parameters]
29e20 0a 2a 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72  .** in a [prepar
29e30 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20  ed statement].  
29e40 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61  SQL parameters a
29e50 72 65 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65  re tokens of the
29e60 0a 2a 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f  .** form "?", "?
29e70 4e 4e 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24  NNN", ":AAA", "$
29e80 41 41 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20  AAA", or "@AAA" 
29e90 74 68 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a  that serve as.**
29ea0 20 70 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f   placeholders fo
29eb0 72 20 76 61 6c 75 65 73 20 74 68 61 74 20 61 72  r values that ar
29ec0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
29ed0 62 6c 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a  blob | bound].**
29ee0 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65   to the paramete
29ef0 72 73 20 61 74 20 61 20 6c 61 74 65 72 20 74 69  rs at a later ti
29f00 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73  me..**.** ^(This
29f10 20 72 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c   routine actuall
29f20 79 20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e  y returns the in
29f30 64 65 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65  dex of the large
29f40 73 74 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a  st (rightmost).*
29f50 2a 20 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72  * parameter. For
29f60 20 61 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70   all forms excep
29f70 74 20 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c  t ?NNN, this wil
29f80 6c 20 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20  l correspond to 
29f90 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
29fa0 20 75 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65   unique paramete
29fb0 72 73 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65  rs.  If paramete
29fc0 72 73 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66  rs of the ?NNN f
29fd0 6f 72 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a  orm are used,.**
29fe0 20 74 68 65 72 65 20 6d 61 79 20 62 65 20 67 61   there may be ga
29ff0 70 73 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29  ps in the list.)
2a000 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ^.**.** See also
2a010 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  : [sqlite3_bind_
2a020 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e  blob|sqlite3_bin
2a030 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  d()],.** [sqlite
2a040 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a050 5f 6e 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a  _name()], and.**
2a060 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a070 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29  arameter_index()
2a080 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
2a090 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a0a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a0b0 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2a0c0 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20  PI3REF: Name Of 
2a0d0 41 20 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72  A Host Parameter
2a0e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a0f0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a100 65 72 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74  er_name(P,N) int
2a110 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a  erface returns.*
2a120 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  * the name of th
2a130 65 20 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61  e N-th [SQL para
2a140 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70  meter] in the [p
2a150 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a160 74 5d 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70  t] P..** ^(SQL p
2a170 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
2a180 20 66 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20   form "?NNN" or 
2a190 22 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22  ":AAA" or "@AAA"
2a1a0 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61   or "$AAA".** ha
2a1b0 76 65 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20  ve a name which 
2a1c0 69 73 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f  is the string "?
2a1d0 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f  NNN" or ":AAA" o
2a1e0 72 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41  r "@AAA" or "$AA
2a1f0 41 22 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65  A".** respective
2a200 6c 79 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20  ly..** In other 
2a210 77 6f 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69  words, the initi
2a220 61 6c 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72  al ":" or "$" or
2a230 20 22 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69   "@" or "?".** i
2a240 73 20 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61  s included as pa
2a250 72 74 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29  rt of the name.)
2a260 5e 0a 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73  ^.** ^Parameters
2a270 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22   of the form "?"
2a280 20 77 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f   without a follo
2a290 77 69 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76  wing integer hav
2a2a0 65 20 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64  e no name.** and
2a2b0 20 61 72 65 20 72 65 66 65 72 72 65 64 20 74 6f   are referred to
2a2c0 20 61 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f   as "nameless" o
2a2d0 72 20 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72  r "anonymous par
2a2e0 61 6d 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20  ameters"..**.** 
2a2f0 5e 54 68 65 20 66 69 72 73 74 20 68 6f 73 74 20  ^The first host 
2a300 70 61 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e  parameter has an
2a310 20 69 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74   index of 1, not
2a320 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68   0..**.** ^If th
2a330 65 20 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74  e value N is out
2a340 20 6f 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20   of range or if 
2a350 74 68 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74  the N-th paramet
2a360 65 72 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73  er is.** nameles
2a370 73 2c 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20  s, then NULL is 
2a380 72 65 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20  returned.  ^The 
2a390 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
2a3a0 69 73 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20  is.** always in 
2a3b0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65  UTF-8 encoding e
2a3c0 76 65 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64  ven if the named
2a3d0 20 70 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a   parameter was.*
2a3e0 2a 20 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65  * originally spe
2a3f0 63 69 66 69 65 64 20 61 73 20 55 54 46 2d 31 36  cified as UTF-16
2a400 20 69 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   in [sqlite3_pre
2a410 70 61 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  pare16()] or.** 
2a420 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2a430 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
2a440 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
2a450 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
2a460 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
2a470 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
2a480 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
2a490 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2a4a0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a4b0 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63  r_index()]..*/.c
2a4c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2a4d0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
2a4e0 72 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73  r_name(sqlite3_s
2a4f0 74 6d 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a  tmt*, int);../*.
2a500 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64  ** CAPI3REF: Ind
2a510 65 78 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65  ex Of A Paramete
2a520 72 20 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e  r With A Given N
2a530 61 6d 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72  ame.**.** ^Retur
2a540 6e 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61  n the index of a
2a550 6e 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20  n SQL parameter 
2a560 67 69 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20  given its name. 
2a570 20 5e 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76   ^The.** index v
2a580 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 69 73  alue returned is
2a590 20 73 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73   suitable for us
2a5a0 65 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a  e as the second.
2a5b0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  ** parameter to 
2a5c0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a5d0 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
2a5e0 29 5d 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20  )].  ^A zero.** 
2a5f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e  is returned if n
2a600 6f 20 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d  o matching param
2a610 65 74 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20  eter is found.  
2a620 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a  ^The parameter.*
2a630 2a 20 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67  * name must be g
2a640 69 76 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76  iven in UTF-8 ev
2a650 65 6e 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e  en if the origin
2a660 61 6c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  al statement.** 
2a670 77 61 73 20 70 72 65 70 61 72 65 64 20 66 72 6f  was prepared fro
2a680 6d 20 55 54 46 2d 31 36 20 74 65 78 74 20 75 73  m UTF-16 text us
2a690 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  ing [sqlite3_pre
2a6a0 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a  pare16_v2()]..**
2a6b0 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
2a6c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
2a6d0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
2a6e0 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
2a6f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
2a700 6e 74 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  nt()], and.** [s
2a710 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a720 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
2a730 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
2a740 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
2a750 64 65 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  dex(sqlite3_stmt
2a760 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
2a770 4e 61 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Name);../*.** CA
2a780 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c  PI3REF: Reset Al
2a790 6c 20 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20  l Bindings On A 
2a7a0 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
2a7b0 6e 74 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61  nt.**.** ^Contra
2a7c0 72 79 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74  ry to the intuit
2a7d0 69 6f 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71  ion of many, [sq
2a7e0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64  lite3_reset()] d
2a7f0 6f 65 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a  oes not reset.**
2a800 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69   the [sqlite3_bi
2a810 6e 64 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e  nd_blob | bindin
2a820 67 73 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  gs] on a [prepar
2a830 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2a840 2a 20 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74  * ^Use this rout
2a850 69 6e 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c  ine to reset all
2a860 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73   host parameters
2a870 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74   to NULL..*/.int
2a880 20 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62   sqlite3_clear_b
2a890 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f  indings(sqlite3_
2a8a0 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  stmt*);../*.** C
2a8b0 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20  API3REF: Number 
2a8c0 4f 66 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20  Of Columns In A 
2a8d0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2a8e0 20 5e 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d   ^Return the num
2a8f0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
2a900 6e 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74  n the result set
2a910 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
2a920 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2a930 61 74 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20  atement]. ^This 
2a940 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
2a950 30 20 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e  0 if pStmt is an
2a960 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
2a970 74 20 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20  t that does not 
2a980 72 65 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72  return data (for
2a990 20 65 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44   example an [UPD
2a9a0 41 54 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ATE])..**.** See
2a9b0 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a9c0 64 61 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f  data_count()].*/
2a9d0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2a9e0 75 6d 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65  umn_count(sqlite
2a9f0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2aa00 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2aa10 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e   Column Names In
2aa20 20 41 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a   A Result Set.**
2aa30 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
2aa40 6e 65 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e  nes return the n
2aa50 61 6d 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20  ame assigned to 
2aa60 61 20 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c  a particular col
2aa70 75 6d 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65  umn.** in the re
2aa80 73 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53  sult set of a [S
2aa90 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
2aaa0 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
2aab0 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a  column_name().**
2aac0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2aad0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2aae0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2aaf0 64 20 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a  d UTF-8 string.*
2ab00 2a 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  * and sqlite3_co
2ab10 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65  lumn_name16() re
2ab20 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
2ab30 74 6f 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  to a zero-termin
2ab40 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73  ated.** UTF-16 s
2ab50 74 72 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72  tring.  ^The fir
2ab60 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  st parameter is 
2ab70 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2ab80 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74  atement].** that
2ab90 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20   implements the 
2aba0 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65  [SELECT] stateme
2abb0 6e 74 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  nt. ^The second 
2abc0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2abd0 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65  .** column numbe
2abe0 72 2e 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73  r.  ^The leftmos
2abf0 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62  t column is numb
2ac00 65 72 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er 0..**.** ^The
2ac10 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2ac20 20 70 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69   pointer is vali
2ac30 64 20 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74  d until either t
2ac40 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
2ac50 74 65 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65  tement].** is de
2ac60 73 74 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69  stroyed by [sqli
2ac70 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2ac80 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2ac90 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2aca0 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2acb0 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2acc0 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2acd0 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2ace0 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2acf0 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2ad00 20 6e 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a   next call to.**
2ad10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ad20 6e 61 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65  name() or sqlite
2ad30 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28  3_column_name16(
2ad40 29 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f  ) on the same co
2ad50 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  lumn..**.** ^If 
2ad60 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
2ad70 20 66 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68   fails during th
2ad80 65 20 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20  e processing of 
2ad90 65 69 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a  either routine.*
2ada0 2a 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64  * (for example d
2adb0 75 72 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69  uring a conversi
2adc0 6f 6e 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f  on from UTF-8 to
2add0 20 55 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a   UTF-16) then a.
2ade0 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
2adf0 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a  is returned..**.
2ae00 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20  ** ^The name of 
2ae10 61 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  a result column 
2ae20 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
2ae30 74 68 65 20 22 41 53 22 20 63 6c 61 75 73 65 20  the "AS" clause 
2ae40 66 6f 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75  for.** that colu
2ae50 6d 6e 2c 20 69 66 20 74 68 65 72 65 20 69 73 20  mn, if there is 
2ae60 61 6e 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49  an AS clause.  I
2ae70 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53  f there is no AS
2ae80 20 63 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20   clause.** then 
2ae90 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
2aea0 63 6f 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63  column is unspec
2aeb0 69 66 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68  ified and may ch
2aec0 61 6e 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65  ange from.** one
2aed0 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69   release of SQLi
2aee0 74 65 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a  te to the next..
2aef0 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
2af00 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
2af10 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2af20 2c 20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20  , int N);.const 
2af30 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2af40 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69  lumn_name16(sqli
2af50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e  te3_stmt*, int N
2af60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2af70 45 46 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61  EF: Source Of Da
2af80 74 61 20 49 6e 20 41 20 51 75 65 72 79 20 52 65  ta In A Query Re
2af90 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  sult.**.** ^Thes
2afa0 65 20 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69  e routines provi
2afb0 64 65 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65  de a means to de
2afc0 74 65 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61  termine the data
2afd0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2afe0 0a 2a 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  .** table column
2aff0 20 74 68 61 74 20 69 73 20 74 68 65 20 6f 72 69   that is the ori
2b000 67 69 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75  gin of a particu
2b010 6c 61 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  lar result colum
2b020 6e 20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d  n in.** [SELECT]
2b030 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e   statement..** ^
2b040 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
2b050 64 61 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c  database or tabl
2b060 65 20 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20  e or column can 
2b070 62 65 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a  be returned as.*
2b080 2a 20 65 69 74 68 65 72 20 61 20 55 54 46 2d 38  * either a UTF-8
2b090 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e   or UTF-16 strin
2b0a0 67 2e 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61  g.  ^The _databa
2b0b0 73 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  se_ routines ret
2b0c0 75 72 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  urn.** the datab
2b0d0 61 73 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74  ase name, the _t
2b0e0 61 62 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72  able_ routines r
2b0f0 65 74 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20  eturn the table 
2b100 6e 61 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65  name, and.** the
2b110 20 6f 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65   origin_ routine
2b120 73 20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c  s return the col
2b130 75 6d 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68  umn name..** ^Th
2b140 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
2b150 67 20 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c  g is valid until
2b160 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
2b170 74 61 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73  tatement] is des
2b180 74 72 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20  troyed.** using 
2b190 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2b1a0 65 28 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68  e()] or until th
2b1b0 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61  e statement is a
2b1c0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20  utomatically.** 
2b1d0 72 65 70 72 65 70 61 72 65 64 20 62 79 20 74 68  reprepared by th
2b1e0 65 20 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20  e first call to 
2b1f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2b200 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61   for a particula
2b210 72 20 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69  r run.** or unti
2b220 6c 20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72  l the same infor
2b230 6d 61 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73  mation is reques
2b240 74 65 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20  ted.** again in 
2b250 61 20 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f  a different enco
2b260 64 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ding..**.** ^The
2b270 20 6e 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20   names returned 
2b280 61 72 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  are the original
2b290 20 75 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65   un-aliased name
2b2a0 73 20 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61  s of the.** data
2b2b0 62 61 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64  base, table, and
2b2c0 20 63 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e   column..**.** ^
2b2d0 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
2b2e0 6e 74 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65  nt to these inte
2b2f0 72 66 61 63 65 73 20 69 73 20 61 20 5b 70 72 65  rfaces is a [pre
2b300 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b310 2e 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  ..** ^These func
2b320 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66  tions return inf
2b330 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74  ormation about t
2b340 68 65 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f  he Nth result co
2b350 6c 75 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79  lumn returned by
2b360 0a 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e  .** the statemen
2b370 74 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  t, where N is th
2b380 65 20 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f  e second functio
2b390 6e 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  n argument..** ^
2b3a0 54 68 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f  The left-most co
2b3b0 6c 75 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30  lumn is column 0
2b3c0 20 66 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69   for these routi
2b3d0 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  nes..**.** ^If t
2b3e0 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65  he Nth column re
2b3f0 74 75 72 6e 65 64 20 62 79 20 74 68 65 20 73 74  turned by the st
2b400 61 74 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78  atement is an ex
2b410 70 72 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73  pression or.** s
2b420 75 62 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e  ubquery and is n
2b430 6f 74 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75  ot a column valu
2b440 65 2c 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74  e, then all of t
2b450 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  hese functions r
2b460 65 74 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20  eturn.** NULL.  
2b470 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d  ^These routine m
2b480 69 67 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e  ight also return
2b490 20 4e 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72   NULL if a memor
2b4a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2b4b0 6f 72 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e  or.** occurs.  ^
2b4c0 4f 74 68 65 72 77 69 73 65 2c 20 74 68 65 79 20  Otherwise, they 
2b4d0 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
2b4e0 6f 66 20 74 68 65 20 61 74 74 61 63 68 65 64 20  of the attached 
2b4f0 64 61 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c  database, table,
2b500 0a 2a 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68  .** or column th
2b510 61 74 20 71 75 65 72 79 20 72 65 73 75 6c 74 20  at query result 
2b520 63 6f 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61  column was extra
2b530 63 74 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a  cted from..**.**
2b540 20 5e 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74   ^As with all ot
2b550 68 65 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c  her SQLite APIs,
2b560 20 74 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d   those whose nam
2b570 65 73 20 65 6e 64 20 77 69 74 68 20 22 31 36 22  es end with "16"
2b580 20 72 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31   return.** UTF-1
2b590 36 20 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67  6 encoded string
2b5a0 73 20 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20  s and the other 
2b5b0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2b5c0 20 55 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54   UTF-8..**.** ^T
2b5d0 68 65 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e  hese APIs are on
2b5e0 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20  ly available if 
2b5f0 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73 20  the library was 
2b600 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68  compiled with th
2b610 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41  e.** [SQLITE_ENA
2b620 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44  BLE_COLUMN_METAD
2b630 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73  ATA] C-preproces
2b640 73 6f 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a  sor symbol..**.*
2b650 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65  * If two or more
2b660 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e   threads call on
2b670 65 20 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65  e or more of the
2b680 73 65 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69  se routines agai
2b690 6e 73 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  nst the same.** 
2b6a0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b6b0 6e 74 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74  nt and column at
2b6c0 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74   the same time t
2b6d0 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
2b6e0 61 72 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64  are.** undefined
2b6f0 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f  ..**.** If two o
2b700 72 20 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63  r more threads c
2b710 61 6c 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a  all one or more.
2b720 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2b730 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2b740 20 7c 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61   | column metada
2b750 74 61 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a  ta interfaces].*
2b760 2a 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b  * for the same [
2b770 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2b780 6e 74 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63  nt] and result c
2b790 6f 6c 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20  olumn.** at the 
2b7a0 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2b7b0 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2b7c0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e  ndefined..*/.con
2b7d0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
2b7e0 5f 63 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65  _column_database
2b7f0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b800 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2b810 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2b820 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2b830 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  me16(sqlite3_stm
2b840 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63  t*,int);.const c
2b850 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
2b860 75 6d 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73  umn_table_name(s
2b870 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
2b880 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2b890 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61  qlite3_column_ta
2b8a0 62 6c 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74  ble_name16(sqlit
2b8b0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2b8c0 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
2b8d0 65 33 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e  e3_column_origin
2b8e0 5f 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74  _name(sqlite3_st
2b8f0 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2b900 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2b910 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2b920 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2b930 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
2b940 50 49 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64  PI3REF: Declared
2b950 20 44 61 74 61 74 79 70 65 20 4f 66 20 41 20 51   Datatype Of A Q
2b960 75 65 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a  uery Result.**.*
2b970 2a 20 5e 28 54 68 65 20 66 69 72 73 74 20 70 61  * ^(The first pa
2b980 72 61 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72  rameter is a [pr
2b990 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2b9a0 5d 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74  ]..** If this st
2b9b0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45  atement is a [SE
2b9c0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20  LECT] statement 
2b9d0 61 6e 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  and the Nth colu
2b9e0 6d 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74  mn of the.** ret
2b9f0 75 72 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74  urned result set
2ba00 20 6f 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54   of that [SELECT
2ba10 5d 20 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c  ] is a table col
2ba20 75 6d 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65  umn (not an.** e
2ba30 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
2ba40 71 75 65 72 79 29 20 74 68 65 6e 20 74 68 65 20  query) then the 
2ba50 64 65 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66  declared type of
2ba60 20 74 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f   the table.** co
2ba70 6c 75 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64  lumn is returned
2ba80 2e 29 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68  .)^  ^If the Nth
2ba90 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72   column of the r
2baa0 65 73 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a  esult set is an.
2bab0 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72  ** expression or
2bac0 20 73 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20   subquery, then 
2bad0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2bae0 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e  s returned..** ^
2baf0 54 68 65 20 72 65 74 75 72 6e 65 64 20 73 74 72  The returned str
2bb00 69 6e 67 20 69 73 20 61 6c 77 61 79 73 20 55 54  ing is always UT
2bb10 46 2d 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a  F-8 encoded..**.
2bb20 2a 2a 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65  ** ^(For example
2bb30 2c 20 67 69 76 65 6e 20 74 68 65 20 64 61 74 61  , given the data
2bb40 62 61 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a  base schema:.**.
2bb50 2a 2a 20 43 52 45 41 54 45 20 54 41 42 4c 45 20  ** CREATE TABLE 
2bb60 74 31 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a  t1(c1 VARIANT);.
2bb70 2a 2a 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f  **.** and the fo
2bb80 6c 6c 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e  llowing statemen
2bb90 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64  t to be compiled
2bba0 3a 0a 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63  :.**.** SELECT c
2bbb0 31 20 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74  1 + 1, c1 FROM t
2bbc0 31 3b 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f  1;.**.** this ro
2bbd0 75 74 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75  utine would retu
2bbe0 72 6e 20 74 68 65 20 73 74 72 69 6e 67 20 22 56  rn the string "V
2bbf0 41 52 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20  ARIANT" for the 
2bc00 73 65 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a  second result.**
2bc10 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20   column (i==1), 
2bc20 61 6e 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  and a NULL point
2bc30 65 72 20 66 6f 72 20 74 68 65 20 66 69 72 73 74  er for the first
2bc40 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28   result column (
2bc50 69 3d 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  i==0).)^.**.** ^
2bc60 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
2bc70 6d 69 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70  mic run-time typ
2bc80 69 6e 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62  ing.  ^So just b
2bc90 65 63 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a  ecause a column.
2bca0 2a 2a 20 69 73 20 64 65 63 6c 61 72 65 64 20 74  ** is declared t
2bcb0 6f 20 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74  o contain a part
2bcc0 69 63 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73  icular type does
2bcd0 20 6e 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74   not mean that t
2bce0 68 65 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65  he.** data store
2bcf0 64 20 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e  d in that column
2bd00 20 69 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61   is of the decla
2bd10 72 65 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74  red type.  SQLit
2bd20 65 20 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79  e is.** strongly
2bd30 20 74 79 70 65 64 2c 20 62 75 74 20 74 68 65 20   typed, but the 
2bd40 74 79 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69  typing is dynami
2bd50 63 20 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e  c not static.  ^
2bd60 54 79 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63  Type.** is assoc
2bd70 69 61 74 65 64 20 77 69 74 68 20 69 6e 64 69 76  iated with indiv
2bd80 69 64 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f  idual values, no
2bd90 74 20 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61  t with the conta
2bda0 69 6e 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f  iners.** used to
2bdb0 20 68 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75   hold those valu
2bdc0 65 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61  es..*/.const cha
2bdd0 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
2bde0 6e 5f 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74  n_decltype(sqlit
2bdf0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
2be00 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2be10 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79  e3_column_declty
2be20 70 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  pe16(sqlite3_stm
2be30 74 2a 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  t*,int);../*.** 
2be40 43 41 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61  CAPI3REF: Evalua
2be50 74 65 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d  te An SQL Statem
2be60 65 6e 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20  ent.**.** After 
2be70 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  a [prepared stat
2be80 65 6d 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20  ement] has been 
2be90 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 65  prepared using e
2bea0 69 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ither.** [sqlite
2beb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2bec0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2bed0 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f  are16_v2()] or o
2bee0 6e 65 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79  ne of the legacy
2bef0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b  .** interfaces [
2bf00 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
2bf10 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70  )] or [sqlite3_p
2bf20 72 65 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69  repare16()], thi
2bf30 73 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75  s function.** mu
2bf40 73 74 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65  st be called one
2bf50 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74   or more times t
2bf60 6f 20 65 76 61 6c 75 61 74 65 20 74 68 65 20 73  o evaluate the s
2bf70 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  tatement..**.** 
2bf80 54 68 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74  The details of t
2bf90 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74  he behavior of t
2bfa0 68 65 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  he sqlite3_step(
2bfb0 29 20 69 6e 74 65 72 66 61 63 65 20 64 65 70 65  ) interface depe
2bfc0 6e 64 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72  nd.** on whether
2bfd0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77   the statement w
2bfe0 61 73 20 70 72 65 70 61 72 65 64 20 75 73 69 6e  as prepared usin
2bff0 67 20 74 68 65 20 6e 65 77 65 72 20 22 76 32 22  g the newer "v2"
2c000 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73   interface.** [s
2c010 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2c020 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  2()] and [sqlite
2c030 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
2c040 5d 20 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c  ] or the older l
2c050 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2c060 63 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ce [sqlite3_prep
2c070 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  are()] and [sqli
2c080 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
2c090 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2c0a0 65 0a 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e  e.** new "v2" in
2c0b0 74 65 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d  terface is recom
2c0c0 6d 65 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61  mended for new a
2c0d0 70 70 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20  pplications but 
2c0e0 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e  the legacy.** in
2c0f0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e  terface will con
2c100 74 69 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70  tinue to be supp
2c110 6f 72 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  orted..**.** ^In
2c120 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2c130 72 66 61 63 65 2c 20 74 68 65 20 72 65 74 75 72  rface, the retur
2c140 6e 20 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20  n value will be 
2c150 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42  either [SQLITE_B
2c160 55 53 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  USY],.** [SQLITE
2c170 5f 44 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  _DONE], [SQLITE_
2c180 52 4f 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52  ROW], [SQLITE_ER
2c190 52 4f 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45  ROR], or [SQLITE
2c1a0 5f 4d 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69  _MISUSE]..** ^Wi
2c1b0 74 68 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  th the "v2" inte
2c1c0 72 66 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68  rface, any of th
2c1d0 65 20 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20  e other [result 
2c1e0 63 6f 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78  codes] or.** [ex
2c1f0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
2c200 64 65 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65  des] might be re
2c210 74 75 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a  turned as well..
2c220 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42  **.** ^[SQLITE_B
2c230 55 53 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20  USY] means that 
2c240 74 68 65 20 64 61 74 61 62 61 73 65 20 65 6e 67  the database eng
2c250 69 6e 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74  ine was unable t
2c260 6f 20 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a  o acquire the.**
2c270 20 64 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20   database locks 
2c280 69 74 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69  it needs to do i
2c290 74 73 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65  ts job.  ^If the
2c2a0 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20   statement is a 
2c2b0 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f  [COMMIT].** or o
2c2c0 63 63 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66  ccurs outside of
2c2d0 20 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61   an explicit tra
2c2e0 6e 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79  nsaction, then y
2c2f0 6f 75 20 63 61 6e 20 72 65 74 72 79 20 74 68 65  ou can retry the
2c300 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  .** statement.  
2c310 49 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  If the statement
2c320 20 69 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49   is not a [COMMI
2c330 54 5d 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69  T] and occurs wi
2c340 74 68 69 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69  thin an.** expli
2c350 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  cit transaction 
2c360 74 68 65 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20  then you should 
2c370 72 6f 6c 6c 62 61 63 6b 20 74 68 65 20 74 72 61  rollback the tra
2c380 6e 73 61 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a  nsaction before.
2c390 2a 2a 20 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a  ** continuing..*
2c3a0 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f  *.** ^[SQLITE_DO
2c3b0 4e 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  NE] means that t
2c3c0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73  he statement has
2c3d0 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
2c3e0 69 6e 67 0a 2a 2a 20 73 75 63 63 65 73 73 66 75  ing.** successfu
2c3f0 6c 6c 79 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  lly.  sqlite3_st
2c400 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2c410 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2c420 6f 6e 20 74 68 69 73 20 76 69 72 74 75 61 6c 0a  on this virtual.
2c430 2a 2a 20 6d 61 63 68 69 6e 65 20 77 69 74 68 6f  ** machine witho
2c440 75 74 20 66 69 72 73 74 20 63 61 6c 6c 69 6e 67  ut first calling
2c450 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2c460 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2c470 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69  virtual.** machi
2c480 6e 65 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69  ne back to its i
2c490 6e 69 74 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a  nitial state..**
2c4a0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 53 51 4c 20  .** ^If the SQL 
2c4b0 73 74 61 74 65 6d 65 6e 74 20 62 65 69 6e 67 20  statement being 
2c4c0 65 78 65 63 75 74 65 64 20 72 65 74 75 72 6e 73  executed returns
2c4d0 20 61 6e 79 20 64 61 74 61 2c 20 74 68 65 6e 20   any data, then 
2c4e0 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20  [SQLITE_ROW].** 
2c4f0 69 73 20 72 65 74 75 72 6e 65 64 20 65 61 63 68  is returned each
2c500 20 74 69 6d 65 20 61 20 6e 65 77 20 72 6f 77 20   time a new row 
2c510 6f 66 20 64 61 74 61 20 69 73 20 72 65 61 64 79  of data is ready
2c520 20 66 6f 72 20 70 72 6f 63 65 73 73 69 6e 67 20   for processing 
2c530 62 79 20 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72  by the.** caller
2c540 2e 20 54 68 65 20 76 61 6c 75 65 73 20 6d 61 79  . The values may
2c550 20 62 65 20 61 63 63 65 73 73 65 64 20 75 73 69   be accessed usi
2c560 6e 67 20 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61  ng the [column a
2c570 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2c580 2e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 65  ..** sqlite3_ste
2c590 70 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 67  p() is called ag
2c5a0 61 69 6e 20 74 6f 20 72 65 74 72 69 65 76 65 20  ain to retrieve 
2c5b0 74 68 65 20 6e 65 78 74 20 72 6f 77 20 6f 66 20  the next row of 
2c5c0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51  data..**.** ^[SQ
2c5d0 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e  LITE_ERROR] mean
2c5e0 73 20 74 68 61 74 20 61 20 72 75 6e 2d 74 69 6d  s that a run-tim
2c5f0 65 20 65 72 72 6f 72 20 28 73 75 63 68 20 61 73  e error (such as
2c600 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a   a constraint.**
2c610 20 76 69 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20   violation) has 
2c620 6f 63 63 75 72 72 65 64 2e 20 20 73 71 6c 69 74  occurred.  sqlit
2c630 65 33 5f 73 74 65 70 28 29 20 73 68 6f 75 6c 64  e3_step() should
2c640 20 6e 6f 74 20 62 65 20 63 61 6c 6c 65 64 20 61   not be called a
2c650 67 61 69 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56  gain on.** the V
2c660 4d 2e 20 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74  M. More informat
2c670 69 6f 6e 20 6d 61 79 20 62 65 20 66 6f 75 6e 64  ion may be found
2c680 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
2c690 69 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a  ite3_errmsg()]..
2c6a0 2a 2a 20 5e 57 69 74 68 20 74 68 65 20 6c 65 67  ** ^With the leg
2c6b0 61 63 79 20 69 6e 74 65 72 66 61 63 65 2c 20 61  acy interface, a
2c6c0 20 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65   more specific e
2c6d0 72 72 6f 72 20 63 6f 64 65 20 28 66 6f 72 20 65  rror code (for e
2c6e0 78 61 6d 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49  xample,.** [SQLI
2c6f0 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b  TE_INTERRUPT], [
2c700 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20  SQLITE_SCHEMA], 
2c710 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
2c720 2c 20 61 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a  , and so forth).
2c730 2a 2a 20 63 61 6e 20 62 65 20 6f 62 74 61 69 6e  ** can be obtain
2c740 65 64 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73  ed by calling [s
2c750 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c760 6f 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61  on the.** [prepa
2c770 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20  red statement]. 
2c780 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20 69 6e   ^In the "v2" in
2c790 74 65 72 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20  terface,.** the 
2c7a0 6d 6f 72 65 20 73 70 65 63 69 66 69 63 20 65 72  more specific er
2c7b0 72 6f 72 20 63 6f 64 65 20 69 73 20 72 65 74 75  ror code is retu
2c7c0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 20 62 79  rned directly by
2c7d0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e   sqlite3_step().
2c7e0 0a 2a 2a 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d  .**.** [SQLITE_M
2c7f0 49 53 55 53 45 5d 20 6d 65 61 6e 73 20 74 68 61  ISUSE] means tha
2c800 74 20 74 68 65 20 74 68 69 73 20 72 6f 75 74 69  t the this routi
2c810 6e 65 20 77 61 73 20 63 61 6c 6c 65 64 20 69 6e  ne was called in
2c820 61 70 70 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a  appropriately..*
2c830 2a 20 50 65 72 68 61 70 73 20 69 74 20 77 61 73  * Perhaps it was
2c840 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72   called on a [pr
2c850 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c860 5d 20 74 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c  ] that has.** al
2c870 72 65 61 64 79 20 62 65 65 6e 20 5b 73 71 6c 69  ready been [sqli
2c880 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66  te3_finalize | f
2c890 69 6e 61 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20  inalized] or on 
2c8a0 6f 6e 65 20 74 68 61 74 20 68 61 64 0a 2a 2a 20  one that had.** 
2c8b0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
2c8c0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  ned [SQLITE_ERRO
2c8d0 52 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f  R] or [SQLITE_DO
2c8e0 4e 45 5d 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c  NE].  Or it coul
2c8f0 64 0a 2a 2a 20 62 65 20 74 68 65 20 63 61 73 65  d.** be the case
2c900 20 74 68 61 74 20 74 68 65 20 73 61 6d 65 20 64   that the same d
2c910 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2c920 6f 6e 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  on is being used
2c930 20 62 79 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f   by two or.** mo
2c940 72 65 20 74 68 72 65 61 64 73 20 61 74 20 74 68  re threads at th
2c950 65 20 73 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e  e same moment in
2c960 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72   time..**.** For
2c970 20 61 6c 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66   all versions of
2c980 20 53 51 4c 69 74 65 20 75 70 20 74 6f 20 61 6e   SQLite up to an
2c990 64 20 69 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e  d including 3.6.
2c9a0 32 33 2e 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a  23.1, a call to.
2c9b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2c9c0 74 28 29 5d 20 77 61 73 20 72 65 71 75 69 72 65  t()] was require
2c9d0 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f  d after sqlite3_
2c9e0 73 74 65 70 28 29 20 72 65 74 75 72 6e 65 64 20  step() returned 
2c9f0 61 6e 79 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65  anything.** othe
2ca00 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2ca10 4f 57 5d 20 62 65 66 6f 72 65 20 61 6e 79 20 73  OW] before any s
2ca20 75 62 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61  ubsequent invoca
2ca30 74 69 6f 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74  tion of.** sqlit
2ca40 65 33 5f 73 74 65 70 28 29 2e 20 20 46 61 69 6c  e3_step().  Fail
2ca50 75 72 65 20 74 6f 20 72 65 73 65 74 20 74 68 65  ure to reset the
2ca60 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
2ca70 65 6e 74 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  ent using .** [s
2ca80 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2ca90 77 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e 20  would result in 
2caa0 61 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  an [SQLITE_MISUS
2cab0 45 5d 20 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a  E] return from.*
2cac0 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2cad0 2e 20 20 42 75 74 20 61 66 74 65 72 20 76 65 72  .  But after ver
2cae0 73 69 6f 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73  sion 3.6.23.1, s
2caf0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 62 65  qlite3_step() be
2cb00 67 61 6e 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b  gan.** calling [
2cb10 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2cb20 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69   automatically i
2cb30 6e 20 74 68 69 73 20 63 69 72 63 75 6d 73 74 61  n this circumsta
2cb40 6e 63 65 20 72 61 74 68 65 72 0a 2a 2a 20 74 68  nce rather.** th
2cb50 61 6e 20 72 65 74 75 72 6e 69 6e 67 20 5b 53 51  an returning [SQ
2cb60 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54  LITE_MISUSE].  T
2cb70 68 69 73 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69  his is not consi
2cb80 64 65 72 65 64 20 61 20 63 6f 6d 70 61 74 69 62  dered a compatib
2cb90 69 6c 69 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62  ility.** break b
2cba0 65 63 61 75 73 65 20 61 6e 79 20 61 70 70 6c 69  ecause any appli
2cbb0 63 61 74 69 6f 6e 20 74 68 61 74 20 65 76 65 72  cation that ever
2cbc0 20 72 65 63 65 69 76 65 73 20 61 6e 20 53 51 4c   receives an SQL
2cbd0 49 54 45 5f 4d 49 53 55 53 45 20 65 72 72 6f 72  ITE_MISUSE error
2cbe0 0a 2a 2a 20 69 73 20 62 72 6f 6b 65 6e 20 62 79  .** is broken by
2cbf0 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
2cc00 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41  e [SQLITE_OMIT_A
2cc10 55 54 4f 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c  UTORESET] compil
2cc20 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a  e-time option.**
2cc30 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
2cc40 72 65 73 74 6f 72 65 20 74 68 65 20 6c 65 67 61  restore the lega
2cc50 63 79 20 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a  cy behavior..**.
2cc60 2a 2a 20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65  ** <b>Goofy Inte
2cc70 72 66 61 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e  rface Alert:</b>
2cc80 20 49 6e 20 74 68 65 20 6c 65 67 61 63 79 20 69   In the legacy i
2cc90 6e 74 65 72 66 61 63 65 2c 20 74 68 65 20 73 71  nterface, the sq
2cca0 6c 69 74 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20  lite3_step().** 
2ccb0 41 50 49 20 61 6c 77 61 79 73 20 72 65 74 75 72  API always retur
2ccc0 6e 73 20 61 20 67 65 6e 65 72 69 63 20 65 72 72  ns a generic err
2ccd0 6f 72 20 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45  or code, [SQLITE
2cce0 5f 45 52 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69  _ERROR], followi
2ccf0 6e 67 20 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20  ng any.** error 
2cd00 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2cd10 54 45 5f 42 55 53 59 5d 20 61 6e 64 20 5b 53 51  TE_BUSY] and [SQ
2cd20 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59  LITE_MISUSE].  Y
2cd30 6f 75 20 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20  ou must call.** 
2cd40 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2cd50 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69  ] or [sqlite3_fi
2cd60 6e 61 6c 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64  nalize()] in ord
2cd70 65 72 20 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f  er to find one o
2cd80 66 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  f the.** specifi
2cd90 63 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  c [error codes] 
2cda0 74 68 61 74 20 62 65 74 74 65 72 20 64 65 73 63  that better desc
2cdb0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2e  ribes the error.
2cdc0 0a 2a 2a 20 57 65 20 61 64 6d 69 74 20 74 68 61  .** We admit tha
2cdd0 74 20 74 68 69 73 20 69 73 20 61 20 67 6f 6f 66  t this is a goof
2cde0 79 20 64 65 73 69 67 6e 2e 20 20 54 68 65 20 70  y design.  The p
2cdf0 72 6f 62 6c 65 6d 20 68 61 73 20 62 65 65 6e 20  roblem has been 
2ce00 66 69 78 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  fixed.** with th
2ce10 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2ce20 2e 20 20 49 66 20 79 6f 75 20 70 72 65 70 61 72  .  If you prepar
2ce30 65 20 61 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51  e all of your SQ
2ce40 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20  L statements.** 
2ce50 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73 71  using either [sq
2ce60 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2ce70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
2ce80 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
2ce90 69 6e 73 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68  instead.** of th
2cea0 65 20 6c 65 67 61 63 79 20 5b 73 71 6c 69 74 65  e legacy [sqlite
2ceb0 33 5f 70 72 65 70 61 72 65 28 29 5d 20 61 6e 64  3_prepare()] and
2cec0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2ced0 65 31 36 28 29 5d 20 69 6e 74 65 72 66 61 63 65  e16()] interface
2cee0 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d  s,.** then the m
2cef0 6f 72 65 20 73 70 65 63 69 66 69 63 20 5b 65 72  ore specific [er
2cf00 72 6f 72 20 63 6f 64 65 73 5d 20 61 72 65 20 72  ror codes] are r
2cf10 65 74 75 72 6e 65 64 20 64 69 72 65 63 74 6c 79  eturned directly
2cf20 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 73  .** by sqlite3_s
2cf30 74 65 70 28 29 2e 20 20 54 68 65 20 75 73 65 20  tep().  The use 
2cf40 6f 66 20 74 68 65 20 22 76 32 22 20 69 6e 74 65  of the "v2" inte
2cf50 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
2cf60 6e 64 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  nded..*/.int sql
2cf70 69 74 65 33 5f 73 74 65 70 28 73 71 6c 69 74 65  ite3_step(sqlite
2cf80 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  3_stmt*);../*.**
2cf90 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62 65   CAPI3REF: Numbe
2cfa0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
2cfb0 61 20 72 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a  a result set.**.
2cfc0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2cfd0 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e  data_count(P) in
2cfe0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cff0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  the number of co
2d000 6c 75 6d 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20  lumns in the.** 
2d010 63 75 72 72 65 6e 74 20 72 6f 77 20 6f 66 20 74  current row of t
2d020 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  he result set of
2d030 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2d040 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20  ment] P..** ^If 
2d050 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2d060 6e 74 20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61  nt P does not ha
2d070 76 65 20 72 65 73 75 6c 74 73 20 72 65 61 64 79  ve results ready
2d080 20 74 6f 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76   to return.** (v
2d090 69 61 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20  ia calls to the 
2d0a0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2d0b0 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f  int | sqlite3_co
2d0c0 6c 75 6d 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20  lumn_*()] of.** 
2d0d0 69 6e 74 65 72 66 61 63 65 73 29 20 74 68 65 6e  interfaces) then
2d0e0 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d0f0 75 6e 74 28 50 29 20 72 65 74 75 72 6e 73 20 30  unt(P) returns 0
2d100 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
2d110 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 20  3_data_count(P) 
2d120 72 6f 75 74 69 6e 65 20 61 6c 73 6f 20 72 65 74  routine also ret
2d130 75 72 6e 73 20 30 20 69 66 20 50 20 69 73 20 61  urns 0 if P is a
2d140 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
2d150 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2d160 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2d170 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2d180 66 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 63  f the previous c
2d190 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2d1a0 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75  e3_step](P) retu
2d1b0 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  rned [SQLITE_DON
2d1c0 45 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  E].  ^The sqlite
2d1d0 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a  3_data_count(P).
2d1e0 2a 2a 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e  ** will return n
2d1f0 6f 6e 2d 7a 65 72 6f 20 69 66 20 70 72 65 76 69  on-zero if previ
2d200 6f 75 73 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ous call to [sql
2d210 69 74 65 33 5f 73 74 65 70 5d 28 50 29 20 72 65  ite3_step](P) re
2d220 74 75 72 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54  turned.** [SQLIT
2d230 45 5f 52 4f 57 5d 2c 20 65 78 63 65 70 74 20 69  E_ROW], except i
2d240 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 74 68  n the case of th
2d250 65 20 5b 50 52 41 47 4d 41 20 69 6e 63 72 65 6d  e [PRAGMA increm
2d260 65 6e 74 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a  ental_vacuum].**
2d270 20 77 68 65 72 65 20 69 74 20 61 6c 77 61 79 73   where it always
2d280 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 73 69   returns zero si
2d290 6e 63 65 20 65 61 63 68 20 73 74 65 70 20 6f 66  nce each step of
2d2a0 20 74 68 61 74 20 6d 75 6c 74 69 2d 73 74 65 70   that multi-step
2d2b0 0a 2a 2a 20 70 72 61 67 6d 61 20 72 65 74 75 72  .** pragma retur
2d2c0 6e 73 20 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20  ns 0 columns of 
2d2d0 64 61 74 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  data..**.** See 
2d2e0 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63  also: [sqlite3_c
2d2f0 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a  olumn_count()].*
2d300 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 61  /.int sqlite3_da
2d310 74 61 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33  ta_count(sqlite3
2d320 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
2d330 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d340 46 75 6e 64 61 6d 65 6e 74 61 6c 20 44 61 74 61  Fundamental Data
2d350 74 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  types.** KEYWORD
2d360 53 3a 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a  S: SQLITE_TEXT.*
2d370 2a 0a 2a 2a 20 5e 28 45 76 65 72 79 20 76 61 6c  *.** ^(Every val
2d380 75 65 20 69 6e 20 53 51 4c 69 74 65 20 68 61 73  ue in SQLite has
2d390 20 6f 6e 65 20 6f 66 20 66 69 76 65 20 66 75 6e   one of five fun
2d3a0 64 61 6d 65 6e 74 61 6c 20 64 61 74 61 74 79 70  damental datatyp
2d3b0 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
2d3c0 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74 20 73 69  * <li> 64-bit si
2d3d0 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
2d3e0 3c 6c 69 3e 20 36 34 2d 62 69 74 20 49 45 45 45  <li> 64-bit IEEE
2d3f0 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20   floating point 
2d400 6e 75 6d 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73  number.** <li> s
2d410 74 72 69 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c  tring.** <li> BL
2d420 4f 42 0a 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a  OB.** <li> NULL.
2d430 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a  ** </ul>)^.**.**
2d440 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73   These constants
2d450 20 61 72 65 20 63 6f 64 65 73 20 66 6f 72 20 65   are codes for e
2d460 61 63 68 20 6f 66 20 74 68 6f 73 65 20 74 79 70  ach of those typ
2d470 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  es..**.** Note t
2d480 68 61 74 20 74 68 65 20 53 51 4c 49 54 45 5f 54  hat the SQLITE_T
2d490 45 58 54 20 63 6f 6e 73 74 61 6e 74 20 77 61 73  EXT constant was
2d4a0 20 61 6c 73 6f 20 75 73 65 64 20 69 6e 20 53 51   also used in SQ
2d4b0 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a  Lite version 2.*
2d4c0 2a 20 66 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65  * for a complete
2d4d0 6c 79 20 64 69 66 66 65 72 65 6e 74 20 6d 65 61  ly different mea
2d4e0 6e 69 6e 67 2e 20 20 53 6f 66 74 77 61 72 65 20  ning.  Software 
2d4f0 74 68 61 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e  that links again
2d500 73 74 20 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74  st both.** SQLit
2d510 65 20 76 65 72 73 69 6f 6e 20 32 20 61 6e 64 20  e version 2 and 
2d520 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
2d530 20 73 68 6f 75 6c 64 20 75 73 65 20 53 51 4c 49   should use SQLI
2d540 54 45 33 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a  TE3_TEXT, not.**
2d550 20 53 51 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f   SQLITE_TEXT..*/
2d560 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
2d570 49 4e 54 45 47 45 52 20 20 31 0a 23 64 65 66 69  INTEGER  1.#defi
2d580 6e 65 20 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20  ne SQLITE_FLOAT 
2d590 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
2d5a0 49 54 45 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23  ITE_BLOB     4.#
2d5b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55  define SQLITE_NU
2d5c0 4c 4c 20 20 20 20 20 35 0a 23 69 66 64 65 66 20  LL     5.#ifdef 
2d5d0 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 20 75 6e  SQLITE_TEXT.# un
2d5e0 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54 0a  def SQLITE_TEXT.
2d5f0 23 65 6c 73 65 0a 23 20 64 65 66 69 6e 65 20 53  #else.# define S
2d600 51 4c 49 54 45 5f 54 45 58 54 20 20 20 20 20 33  QLITE_TEXT     3
2d610 0a 23 65 6e 64 69 66 0a 23 64 65 66 69 6e 65 20  .#endif.#define 
2d620 53 51 4c 49 54 45 33 5f 54 45 58 54 20 20 20 20  SQLITE3_TEXT    
2d630 20 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52   3../*.** CAPI3R
2d640 45 46 3a 20 52 65 73 75 6c 74 20 56 61 6c 75 65  EF: Result Value
2d650 73 20 46 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a  s From A Query.*
2d660 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c  * KEYWORDS: {col
2d670 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
2d680 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ions}.**.** Thes
2d690 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20  e routines form 
2d6a0 74 68 65 20 22 72 65 73 75 6c 74 20 73 65 74 22  the "result set"
2d6b0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
2d6c0 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
2d6d0 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
2d6e0 74 69 6f 6e 20 61 62 6f 75 74 20 61 20 73 69 6e  tion about a sin
2d6f0 67 6c 65 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68  gle column of th
2d700 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73  e current.** res
2d710 75 6c 74 20 72 6f 77 20 6f 66 20 61 20 71 75 65  ult row of a que
2d720 72 79 2e 20 20 5e 49 6e 20 65 76 65 72 79 20 63  ry.  ^In every c
2d730 61 73 65 20 74 68 65 20 66 69 72 73 74 20 61 72  ase the first ar
2d740 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
2d750 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70  ter.** to the [p
2d760 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2d770 74 5d 20 74 68 61 74 20 69 73 20 62 65 69 6e 67  t] that is being
2d780 20 65 76 61 6c 75 61 74 65 64 20 28 74 68 65 20   evaluated (the 
2d790 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a  [sqlite3_stmt*].
2d7a0 2a 2a 20 74 68 61 74 20 77 61 73 20 72 65 74 75  ** that was retu
2d7b0 72 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  rned from [sqlit
2d7c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2d7d0 20 6f 72 20 6f 6e 65 20 6f 66 20 69 74 73 20 76   or one of its v
2d7e0 61 72 69 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20  ariants).** and 
2d7f0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
2d800 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65 78  ent is the index
2d810 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66   of the column f
2d820 6f 72 20 77 68 69 63 68 20 69 6e 66 6f 72 6d 61  or which informa
2d830 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62  tion.** should b
2d840 65 20 72 65 74 75 72 6e 65 64 2e 20 5e 54 68 65  e returned. ^The
2d850 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e   leftmost column
2d860 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 73   of the result s
2d870 65 74 20 68 61 73 20 74 68 65 20 69 6e 64 65 78  et has the index
2d880 20 30 2e 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62   0..** ^The numb
2d890 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
2d8a0 20 74 68 65 20 72 65 73 75 6c 74 20 63 61 6e 20   the result can 
2d8b0 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 75 73  be determined us
2d8c0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
2d8d0 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e  column_count()].
2d8e0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 53 51  .**.** If the SQ
2d8f0 4c 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  L statement does
2d900 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 20 70   not currently p
2d910 6f 69 6e 74 20 74 6f 20 61 20 76 61 6c 69 64 20  oint to a valid 
2d920 72 6f 77 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a  row, or if the.*
2d930 2a 20 63 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69  * column index i
2d940 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2c 20  s out of range, 
2d950 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 75 6e  the result is un
2d960 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73  defined..** Thes
2d970 65 20 72 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f  e routines may o
2d980 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 77 68  nly be called wh
2d990 65 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  en the most rece
2d9a0 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73  nt call to.** [s
2d9b0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 68  qlite3_step()] h
2d9c0 61 73 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c  as returned [SQL
2d9d0 49 54 45 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69  ITE_ROW] and nei
2d9e0 74 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ther.** [sqlite3
2d9f0 5f 72 65 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73  _reset()] nor [s
2da00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2da10 29 5d 20 68 61 76 65 20 62 65 65 6e 20 63 61 6c  )] have been cal
2da20 6c 65 64 20 73 75 62 73 65 71 75 65 6e 74 6c 79  led subsequently
2da30 2e 0a 2a 2a 20 49 66 20 61 6e 79 20 6f 66 20 74  ..** If any of t
2da40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
2da50 65 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  e called after [
2da60 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2da70 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
2da80 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  finalize()] or a
2da90 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 73 74  fter [sqlite3_st
2daa0 65 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e  ep()] has return
2dab0 65 64 0a 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20  ed.** something 
2dac0 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
2dad0 54 45 5f 52 4f 57 5d 2c 20 74 68 65 20 72 65 73  TE_ROW], the res
2dae0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
2daf0 65 64 2e 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74  ed..** If [sqlit
2db00 65 33 5f 73 74 65 70 28 29 5d 20 6f 72 20 5b 73  e3_step()] or [s
2db10 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2db20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
2db30 6c 69 7a 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63  lize()].** are c
2db40 61 6c 6c 65 64 20 66 72 6f 6d 20 61 20 64 69 66  alled from a dif
2db50 66 65 72 65 6e 74 20 74 68 72 65 61 64 20 77 68  ferent thread wh
2db60 69 6c 65 20 61 6e 79 20 6f 66 20 74 68 65 73 65  ile any of these
2db70 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65   routines.** are
2db80 20 70 65 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74   pending, then t
2db90 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2dba0 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  ndefined..**.** 
2dbb0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2dbc0 75 6d 6e 5f 74 79 70 65 28 29 20 72 6f 75 74 69  umn_type() routi
2dbd0 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 0a 2a  ne returns the.*
2dbe0 2a 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  * [SQLITE_INTEGE
2dbf0 52 20 7c 20 64 61 74 61 74 79 70 65 20 63 6f 64  R | datatype cod
2dc00 65 5d 20 66 6f 72 20 74 68 65 20 69 6e 69 74 69  e] for the initi
2dc10 61 6c 20 64 61 74 61 20 74 79 70 65 0a 2a 2a 20  al data type.** 
2dc20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 63 6f  of the result co
2dc30 6c 75 6d 6e 2e 20 20 5e 54 68 65 20 72 65 74 75  lumn.  ^The retu
2dc40 72 6e 65 64 20 76 61 6c 75 65 20 69 73 20 6f 6e  rned value is on
2dc50 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54  e of [SQLITE_INT
2dc60 45 47 45 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  EGER],.** [SQLIT
2dc70 45 5f 46 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54  E_FLOAT], [SQLIT
2dc80 45 5f 54 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45  E_TEXT], [SQLITE
2dc90 5f 42 4c 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49  _BLOB], or [SQLI
2dca0 54 45 5f 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76  TE_NULL].  The v
2dcb0 61 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64  alue.** returned
2dcc0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2dcd0 6d 6e 5f 74 79 70 65 28 29 20 69 73 20 6f 6e 6c  mn_type() is onl
2dce0 79 20 6d 65 61 6e 69 6e 67 66 75 6c 20 69 66 20  y meaningful if 
2dcf0 6e 6f 20 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65  no type.** conve
2dd00 72 73 69 6f 6e 73 20 68 61 76 65 20 6f 63 63 75  rsions have occu
2dd10 72 72 65 64 20 61 73 20 64 65 73 63 72 69 62 65  rred as describe
2dd20 64 20 62 65 6c 6f 77 2e 20 20 41 66 74 65 72 20  d below.  After 
2dd30 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  a type conversio
2dd40 6e 2c 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n,.** the value 
2dd50 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2dd60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
2dd70 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
2dd80 20 46 75 74 75 72 65 0a 2a 2a 20 76 65 72 73 69   Future.** versi
2dd90 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  ons of SQLite ma
2dda0 79 20 63 68 61 6e 67 65 20 74 68 65 20 62 65 68  y change the beh
2ddb0 61 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33  avior of sqlite3
2ddc0 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a  _column_type().*
2ddd0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79  * following a ty
2dde0 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  pe conversion..*
2ddf0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2de00 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2de10 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20 74 68   UTF-8 string th
2de20 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2de30 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a  olumn_bytes().**
2de40 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
2de50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2de60 79 74 65 73 20 69 6e 20 74 68 61 74 20 42 4c 4f  ytes in that BLO
2de70 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20  B or string..** 
2de80 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2de90 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2dea0 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  g, then sqlite3_
2deb0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 63  column_bytes() c
2dec0 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73  onverts.** the s
2ded0 74 72 69 6e 67 20 74 6f 20 55 54 46 2d 38 20 61  tring to UTF-8 a
2dee0 6e 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20  nd then returns 
2def0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
2df00 74 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  tes..** ^If the 
2df10 72 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65  result is a nume
2df20 72 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73  ric value then s
2df30 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2df40 74 65 73 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  tes() uses.** [s
2df50 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
2df60 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
2df70 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
2df80 46 2d 38 20 73 74 72 69 6e 67 20 61 6e 64 20 72  F-8 string and r
2df90 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75  eturns.** the nu
2dfa0 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e  mber of bytes in
2dfb0 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a   that string..**
2dfc0 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2dfd0 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71  is NULL, then sq
2dfe0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2dff0 65 73 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72  es() returns zer
2e000 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  o..**.** ^If the
2e010 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c 4f   result is a BLO
2e020 42 20 6f 72 20 55 54 46 2d 31 36 20 73 74 72 69  B or UTF-16 stri
2e030 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
2e040 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2e050 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  16().** routine 
2e060 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
2e070 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
2e080 68 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69  hat BLOB or stri
2e090 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
2e0a0 65 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 38  esult is a UTF-8
2e0b0 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
2e0c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e0d0 65 73 31 36 28 29 20 63 6f 6e 76 65 72 74 73 0a  es16() converts.
2e0e0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f  ** the string to
2e0f0 20 55 54 46 2d 31 36 20 61 6e 64 20 74 68 65 6e   UTF-16 and then
2e100 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
2e110 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a  ber of bytes..**
2e120 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2e130 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76 61 6c  is a numeric val
2e140 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ue then sqlite3_
2e150 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2e160 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2e170 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2e180 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2e190 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 31 36 20  lue to a UTF-16 
2e1a0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2e1b0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2e1c0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2e1d0 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2e1e0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2e1f0 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2e200 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2e210 28 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e  () returns zero.
2e220 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75  .**.** ^The valu
2e230 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  es returned by [
2e240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e250 79 74 65 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20  ytes()] and .** 
2e260 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e270 62 79 74 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f  bytes16()] do no
2e280 74 20 69 6e 63 6c 75 64 65 20 74 68 65 20 7a 65  t include the ze
2e290 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 73 20 61  ro terminators a
2e2a0 74 20 74 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20  t the end.** of 
2e2b0 74 68 65 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f  the string.  ^Fo
2e2c0 72 20 63 6c 61 72 69 74 79 3a 20 74 68 65 20 76  r clarity: the v
2e2d0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
2e2e0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  y.** [sqlite3_co
2e2f0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
2e300 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d [sqlite3_colum
2e310 6e 5f 62 79 74 65 73 31 36 28 29 5d 20 61 72 65  n_bytes16()] are
2e320 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
2e330 2a 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 73  * bytes in the s
2e340 74 72 69 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e  tring, not the n
2e350 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74  umber of charact
2e360 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69  ers..**.** ^Stri
2e370 6e 67 73 20 72 65 74 75 72 6e 65 64 20 62 79 20  ngs returned by 
2e380 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2e390 65 78 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ext() and sqlite
2e3a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
2e3b0 29 2c 0a 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79  ),.** even empty
2e3c0 20 73 74 72 69 6e 67 73 2c 20 61 72 65 20 61 6c   strings, are al
2e3d0 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e  ways zero-termin
2e3e0 61 74 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  ated.  ^The retu
2e3f0 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d  rn.** value from
2e400 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2e410 62 6c 6f 62 28 29 20 66 6f 72 20 61 20 7a 65 72  blob() for a zer
2e420 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f 42 20 69 73  o-length BLOB is
2e430 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
2e440 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65  .**.** ^The obje
2e450 63 74 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ct returned by [
2e460 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2e470 61 6c 75 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a  alue()] is an.**
2e480 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
2e490 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
2e4a0 65 63 74 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65  ect.  An unprote
2e4b0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e4c0 75 65 20 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79  ue object.** may
2e4d0 20 6f 6e 6c 79 20 62 65 20 75 73 65 64 20 77 69   only be used wi
2e4e0 74 68 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  th [sqlite3_bind
2e4f0 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73  _value()] and [s
2e500 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2e510 6c 75 65 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68  lue()]..** If th
2e520 65 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  e [unprotected s
2e530 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2e540 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
2e550 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2e560 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
2e570 75 73 65 64 20 69 6e 20 61 6e 79 20 6f 74 68 65  used in any othe
2e580 72 20 77 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67  r way, including
2e590 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75   calls.** to rou
2e5a0 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
2e5b0 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d  te3_value_int()]
2e5c0 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  , [sqlite3_value
2e5d0 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20  _text()],.** or 
2e5e0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
2e5f0 79 74 65 73 28 29 5d 2c 20 74 68 65 6e 20 74 68  ytes()], then th
2e600 65 20 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e  e behavior is un
2e610 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
2e620 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 74  hese routines at
2e630 74 65 6d 70 74 20 74 6f 20 63 6f 6e 76 65 72 74  tempt to convert
2e640 20 74 68 65 20 76 61 6c 75 65 20 77 68 65 72 65   the value where
2e650 20 61 70 70 72 6f 70 72 69 61 74 65 2e 20 20 5e   appropriate.  ^
2e660 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
2e670 69 66 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20  if the internal 
2e680 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 69  representation i
2e690 73 20 46 4c 4f 41 54 20 61 6e 64 20 61 20 74 65  s FLOAT and a te
2e6a0 78 74 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  xt result.** is 
2e6b0 72 65 71 75 65 73 74 65 64 2c 20 5b 73 71 6c 69  requested, [sqli
2e6c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2e6d0 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
2e6e0 6c 79 20 74 6f 20 70 65 72 66 6f 72 6d 20 74 68  ly to perform th
2e6f0 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e.** conversion 
2e700 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20  automatically.  
2e710 5e 28 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  ^(The following 
2e720 74 61 62 6c 65 20 64 65 74 61 69 6c 73 20 74 68  table details th
2e730 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a  e conversions.**
2e740 20 74 68 61 74 20 61 72 65 20 61 70 70 6c 69 65   that are applie
2e750 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  d:.**.** <blockq
2e760 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20  uote>.** <table 
2e770 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c  border="1">.** <
2e780 74 72 3e 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c  tr><th> Internal
2e790 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 52 65  <br>Type <th> Re
2e7a0 71 75 65 73 74 65 64 3c 62 72 3e 54 79 70 65 20  quested<br>Type 
2e7b0 3c 74 68 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e  <th>  Conversion
2e7c0 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  .**.** <tr><td> 
2e7d0 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e   NULL    <td> IN
2e7e0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 52 65 73  TEGER   <td> Res
2e7f0 75 6c 74 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e  ult is 0.** <tr>
2e800 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
2e810 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2e820 3e 20 52 65 73 75 6c 74 20 69 73 20 30 2e 30 0a  > Result is 0.0.
2e830 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2e840 4c 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54  L    <td>   TEXT
2e850 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20      <td> Result 
2e860 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
2e870 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e  r.** <tr><td>  N
2e880 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 20 42 4c  ULL    <td>   BL
2e890 4f 42 20 20 20 20 3c 74 64 3e 20 52 65 73 75 6c  OB    <td> Resul
2e8a0 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
2e8b0 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ter.** <tr><td> 
2e8c0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 46  INTEGER  <td>  F
2e8d0 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e  LOAT    <td> Con
2e8e0 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67 65  vert from intege
2e8f0 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74  r to float.** <t
2e900 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2e910 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2e920 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
2e930 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65 67  ing of the integ
2e940 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  er.** <tr><td> I
2e950 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 42  NTEGER  <td>   B
2e960 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65  LOB    <td> Same
2e970 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45 58   as INTEGER->TEX
2e980 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46  T.** <tr><td>  F
2e990 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54 45  LOAT   <td> INTE
2e9a0 47 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54  GER   <td> [CAST
2e9b0 5d 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20  ] to INTEGER.** 
2e9c0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2e9d0 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e9e0 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
2e9f0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f  ering of the flo
2ea00 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  at.** <tr><td>  
2ea10 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42  FLOAT   <td>   B
2ea20 4c 4f 42 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  LOB    <td> [CAS
2ea30 54 5d 20 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74  T] to BLOB.** <t
2ea40 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2ea50 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c  <td> INTEGER   <
2ea60 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e  td> [CAST] to IN
2ea70 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64  TEGER.** <tr><td
2ea80 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2ea90 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b   FLOAT    <td> [
2eaa0 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a  CAST] to REAL.**
2eab0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
2eac0 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2ead0 20 20 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65    <td> No change
2eae0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2eaf0 4f 42 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  OB    <td> INTEG
2eb00 45 52 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  ER   <td> [CAST]
2eb10 20 74 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c   to INTEGER.** <
2eb20 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2eb30 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2eb40 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52  <td> [CAST] to R
2eb50 45 41 4c 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EAL.** <tr><td> 
2eb60 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 20   BLOB    <td>   
2eb70 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41 64 64  TEXT    <td> Add
2eb80 20 61 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74   a zero terminat
2eb90 6f 72 20 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20  or if needed.** 
2eba0 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c  </table>.** </bl
2ebb0 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a  ockquote>)^.**.*
2ebc0 2a 20 54 68 65 20 74 61 62 6c 65 20 61 62 6f 76  * The table abov
2ebd0 65 20 6d 61 6b 65 73 20 72 65 66 65 72 65 6e 63  e makes referenc
2ebe0 65 20 74 6f 20 73 74 61 6e 64 61 72 64 20 43 20  e to standard C 
2ebf0 6c 69 62 72 61 72 79 20 66 75 6e 63 74 69 6f 6e  library function
2ec00 73 20 61 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20  s atoi().** and 
2ec10 61 74 6f 66 28 29 2e 20 20 53 51 4c 69 74 65 20  atof().  SQLite 
2ec20 64 6f 65 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20  does not really 
2ec30 75 73 65 20 74 68 65 73 65 20 66 75 6e 63 74 69  use these functi
2ec40 6f 6e 73 2e 20 20 49 74 20 68 61 73 20 69 74 73  ons.  It has its
2ec50 0a 2a 2a 20 6f 77 6e 20 65 71 75 69 76 61 6c 65  .** own equivale
2ec60 6e 74 20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74  nt internal rout
2ec70 69 6e 65 73 2e 20 20 54 68 65 20 61 74 6f 69 28  ines.  The atoi(
2ec80 29 20 61 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d  ) and atof() nam
2ec90 65 73 20 61 72 65 0a 2a 2a 20 75 73 65 64 20 69  es are.** used i
2eca0 6e 20 74 68 65 20 74 61 62 6c 65 20 66 6f 72 20  n the table for 
2ecb0 62 72 65 76 69 74 79 20 61 6e 64 20 62 65 63 61  brevity and beca
2ecc0 75 73 65 20 74 68 65 79 20 61 72 65 20 66 61 6d  use they are fam
2ecd0 69 6c 69 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a  iliar to most.**
2ece0 20 43 20 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a   C programmers..
2ecf0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
2ed00 77 68 65 6e 20 74 79 70 65 20 63 6f 6e 76 65 72  when type conver
2ed10 73 69 6f 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69  sions occur, poi
2ed20 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 62  nters returned b
2ed30 79 20 70 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73  y prior.** calls
2ed40 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2ed50 6d 6e 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  mn_blob(), sqlit
2ed60 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2ed70 2c 20 61 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69  , and/or.** sqli
2ed80 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2ed90 36 28 29 20 6d 61 79 20 62 65 20 69 6e 76 61 6c  6() may be inval
2eda0 69 64 61 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20  idated..** Type 
2edb0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 61 6e 64 20  conversions and 
2edc0 70 6f 69 6e 74 65 72 20 69 6e 76 61 6c 69 64 61  pointer invalida
2edd0 74 69 6f 6e 73 20 6d 69 67 68 74 20 6f 63 63 75  tions might occu
2ede0 72 0a 2a 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c  r.** in the foll
2edf0 6f 77 69 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a  owing cases:.**.
2ee00 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
2ee10 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2ee20 65 6e 74 20 69 73 20 61 20 42 4c 4f 42 20 61 6e  ent is a BLOB an
2ee30 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ee40 5f 74 65 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20  _text() or.**   
2ee50 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d     sqlite3_colum
2ee60 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63 61  n_text16() is ca
2ee70 6c 6c 65 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65  lled.  A zero-te
2ee80 72 6d 69 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a  rminator might.*
2ee90 2a 20 20 20 20 20 20 6e 65 65 64 20 74 6f 20 62  *      need to b
2eea0 65 20 61 64 64 65 64 20 74 6f 20 74 68 65 20 73  e added to the s
2eeb0 74 72 69 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c  tring.</li>.** <
2eec0 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61 6c 20  li> The initial 
2eed0 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46 2d 38  content is UTF-8
2eee0 20 74 65 78 74 20 61 6e 64 20 73 71 6c 69 74 65   text and sqlite
2eef0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2ef00 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2ef10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ef20 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2ef30 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
2ef40 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
2ef50 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 31  **      to UTF-1
2ef60 36 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20  6.</li>.** <li> 
2ef70 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74  The initial cont
2ef80 65 6e 74 20 69 73 20 55 54 46 2d 31 36 20 74 65  ent is UTF-16 te
2ef90 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2efa0 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
2efb0 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2efc0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69  _column_text() i
2efd0 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63  s called.  The c
2efe0 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63  ontent must be c
2eff0 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20  onverted.**     
2f000 20 74 6f 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a   to UTF-8.</li>.
2f010 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
2f020 43 6f 6e 76 65 72 73 69 6f 6e 73 20 62 65 74 77  Conversions betw
2f030 65 65 6e 20 55 54 46 2d 31 36 62 65 20 61 6e 64  een UTF-16be and
2f040 20 55 54 46 2d 31 36 6c 65 20 61 72 65 20 61 6c   UTF-16le are al
2f050 77 61 79 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61  ways done in pla
2f060 63 65 20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74  ce and do.** not
2f070 20 69 6e 76 61 6c 69 64 61 74 65 20 61 20 70 72   invalidate a pr
2f080 69 6f 72 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f  ior pointer, tho
2f090 75 67 68 20 6f 66 20 63 6f 75 72 73 65 20 74 68  ugh of course th
2f0a0 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
2f0b0 20 62 75 66 66 65 72 0a 2a 2a 20 74 68 61 74 20   buffer.** that 
2f0c0 74 68 65 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  the prior pointe
2f0d0 72 20 72 65 66 65 72 65 6e 63 65 73 20 77 69 6c  r references wil
2f0e0 6c 20 68 61 76 65 20 62 65 65 6e 20 6d 6f 64 69  l have been modi
2f0f0 66 69 65 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e  fied.  Other kin
2f100 64 73 0a 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73  ds.** of convers
2f110 69 6f 6e 20 61 72 65 20 64 6f 6e 65 20 69 6e 20  ion are done in 
2f120 70 6c 61 63 65 20 77 68 65 6e 20 69 74 20 69 73  place when it is
2f130 20 70 6f 73 73 69 62 6c 65 2c 20 62 75 74 20 73   possible, but s
2f140 6f 6d 65 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a  ometimes they.**
2f150 20 61 72 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c   are not possibl
2f160 65 20 61 6e 64 20 69 6e 20 74 68 6f 73 65 20 63  e and in those c
2f170 61 73 65 73 20 70 72 69 6f 72 20 70 6f 69 6e 74  ases prior point
2f180 65 72 73 20 61 72 65 20 69 6e 76 61 6c 69 64 61  ers are invalida
2f190 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  ted..**.** The s
2f1a0 61 66 65 73 74 20 61 6e 64 20 65 61 73 69 65 73  afest and easies
2f1b0 74 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f  t to remember po
2f1c0 6c 69 63 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b  licy is to invok
2f1d0 65 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  e these routines
2f1e0 0a 2a 2a 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68  .** in one of th
2f1f0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73  e following ways
2f200 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20  :.**.** <ul>.** 
2f210 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c   <li>sqlite3_col
2f220 75 6d 6e 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f  umn_text() follo
2f230 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  wed by sqlite3_c
2f240 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c  olumn_bytes()</l
2f250 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  i>.**  <li>sqlit
2f260 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2f270 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2f280 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f290 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2f2a0 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2f2b0 74 65 78 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65  text16() followe
2f2c0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
2f2d0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c  umn_bytes16()</l
2f2e0 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  i>.** </ul>.**.*
2f2f0 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
2f300 2c 20 79 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c  , you should cal
2f310 6c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  l sqlite3_column
2f320 5f 74 65 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69  _text(),.** sqli
2f330 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f340 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  ), or sqlite3_co
2f350 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66 69  lumn_text16() fi
2f360 72 73 74 20 74 6f 20 66 6f 72 63 65 20 74 68 65  rst to force the
2f370 20 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20   result.** into 
2f380 74 68 65 20 64 65 73 69 72 65 64 20 66 6f 72 6d  the desired form
2f390 61 74 2c 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20  at, then invoke 
2f3a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f3b0 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  ytes() or.** sql
2f3c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f3d0 73 31 36 28 29 20 74 6f 20 66 69 6e 64 20 74 68  s16() to find th
2f3e0 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 72 65  e size of the re
2f3f0 73 75 6c 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69  sult.  Do not mi
2f400 78 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71  x calls.** to sq
2f410 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f420 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  t() or sqlite3_c
2f430 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74  olumn_blob() wit
2f440 68 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71  h calls to.** sq
2f450 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f460 65 73 31 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e  es16(), and do n
2f470 6f 74 20 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20  ot mix calls to 
2f480 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2f490 65 78 74 31 36 28 29 0a 2a 2a 20 77 69 74 68 20  ext16().** with 
2f4a0 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
2f4b0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e  _column_bytes().
2f4c0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e  .**.** ^The poin
2f4d0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 61 72  ters returned ar
2f4e0 65 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 61 20  e valid until a 
2f4f0 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20  type conversion 
2f500 6f 63 63 75 72 73 20 61 73 0a 2a 2a 20 64 65 73  occurs as.** des
2f510 63 72 69 62 65 64 20 61 62 6f 76 65 2c 20 6f 72  cribed above, or
2f520 20 75 6e 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f   until [sqlite3_
2f530 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2f540 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2f550 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2f560 6c 69 7a 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  lize()] is calle
2f570 64 2e 20 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  d.  ^The memory 
2f580 73 70 61 63 65 20 75 73 65 64 20 74 6f 20 68 6f  space used to ho
2f590 6c 64 20 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e  ld strings.** an
2f5a0 64 20 42 4c 4f 42 73 20 69 73 20 66 72 65 65 64  d BLOBs is freed
2f5b0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20   automatically. 
2f5c0 20 44 6f 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70   Do <b>not</b> p
2f5d0 61 73 73 20 74 68 65 20 70 6f 69 6e 74 65 72 73  ass the pointers
2f5e0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2f5f0 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  m [sqlite3_colum
2f600 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  n_blob()], [sqli
2f610 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f620 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a  )], etc. into.**
2f630 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
2f640 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20  ]..**.** ^(If a 
2f650 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
2f660 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64  n error occurs d
2f670 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75 61  uring the evalua
2f680 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f  tion of any.** o
2f690 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
2f6a0 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c 75  , a default valu
2f6b0 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  e is returned.  
2f6c0 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75  The default valu
2f6d0 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20 74  e.** is either t
2f6e0 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74 68  he integer 0, th
2f6f0 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74  e floating point
2f700 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20   number 0.0, or 
2f710 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65  a NULL.** pointe
2f720 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20 63  r.  Subsequent c
2f730 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  alls to [sqlite3
2f740 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c  _errcode()] will
2f750 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
2f760 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a  TE_NOMEM].)^.*/.
2f770 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2f780 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2f790 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f7a0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2f7b0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f7c0 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  es(sqlite3_stmt*
2f7d0 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74  , int iCol);.int
2f7e0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f7f0 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f  bytes16(sqlite3_
2f800 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f810 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
2f820 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73  _column_double(s
2f830 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2f840 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c  t iCol);.int sql
2f850 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28  ite3_column_int(
2f860 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f870 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
2f880 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
2f890 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c  column_int64(sql
2f8a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f8b0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73  iCol);.const uns
2f8c0 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69  igned char *sqli
2f8d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2f8e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f8f0 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20  nt iCol);.const 
2f900 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2f910 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c 69  lumn_text16(sqli
2f920 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f930 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2f940 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71  3_column_type(sq
2f950 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f960 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f   iCol);.sqlite3_
2f970 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f 63  value *sqlite3_c
2f980 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69  olumn_value(sqli
2f990 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f9a0 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  Col);../*.** CAP
2f9b0 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20 41  I3REF: Destroy A
2f9c0 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2f9d0 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2f9e0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69   ^The sqlite3_fi
2f9f0 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69 6f  nalize() functio
2fa00 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 64  n is called to d
2fa10 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72 65  elete a [prepare
2fa20 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2fa30 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2fa40 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2fa50 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  of the statement
2fa60 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20   encountered no 
2fa70 65 72 72 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20  errors.** or if 
2fa80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2fa90 20 6e 65 76 65 72 20 62 65 65 6e 20 65 76 61 6c   never been eval
2faa0 75 61 74 65 64 2c 20 74 68 65 6e 20 73 71 6c 69  uated, then sqli
2fab0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72  te3_finalize() r
2fac0 65 74 75 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45  eturns.** SQLITE
2fad0 5f 4f 4b 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f  _OK.  ^If the mo
2fae0 73 74 20 72 65 63 65 6e 74 20 65 76 61 6c 75 61  st recent evalua
2faf0 74 69 6f 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e  tion of statemen
2fb00 74 20 53 20 66 61 69 6c 65 64 2c 20 74 68 65 6e  t S failed, then
2fb10 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  .** sqlite3_fina
2fb20 6c 69 7a 65 28 53 29 20 72 65 74 75 72 6e 73 20  lize(S) returns 
2fb30 74 68 65 20 61 70 70 72 6f 70 72 69 61 74 65 20  the appropriate 
2fb40 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a  [error code] or.
2fb50 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  ** [extended err
2fb60 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20  or code]..**.** 
2fb70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e  ^The sqlite3_fin
2fb80 61 6c 69 7a 65 28 53 29 20 72 6f 75 74 69 6e 65  alize(S) routine
2fb90 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
2fba0 74 20 61 6e 79 20 70 6f 69 6e 74 20 64 75 72 69  t any point duri
2fbb0 6e 67 0a 2a 2a 20 74 68 65 20 6c 69 66 65 20 63  ng.** the life c
2fbc0 79 63 6c 65 20 6f 66 20 5b 70 72 65 70 61 72 65  ycle of [prepare
2fbd0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a  d statement] S:.
2fbe0 2a 2a 20 62 65 66 6f 72 65 20 73 74 61 74 65 6d  ** before statem
2fbf0 65 6e 74 20 53 20 69 73 20 65 76 65 72 20 65 76  ent S is ever ev
2fc00 61 6c 75 61 74 65 64 2c 20 61 66 74 65 72 0a 2a  aluated, after.*
2fc10 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61  * one or more ca
2fc20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
2fc30 72 65 73 65 74 28 29 5d 2c 20 6f 72 20 61 66 74  reset()], or aft
2fc40 65 72 20 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74  er any call.** t
2fc50 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2fc60 29 5d 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  )] regardless of
2fc70 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
2fc80 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61  the statement ha
2fc90 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65  s.** completed e
2fca0 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  xecution..**.** 
2fcb0 5e 49 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65  ^Invoking sqlite
2fcc0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20  3_finalize() on 
2fcd0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
2fce0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
2fcf0 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70  op..**.** The ap
2fd00 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 66  plication must f
2fd10 69 6e 61 6c 69 7a 65 20 65 76 65 72 79 20 5b 70  inalize every [p
2fd20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2fd30 74 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 61  t] in order to a
2fd40 76 6f 69 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65  void.** resource
2fd50 20 6c 65 61 6b 73 2e 20 20 49 74 20 69 73 20 61   leaks.  It is a
2fd60 20 67 72 69 65 76 6f 75 73 20 65 72 72 6f 72 20   grievous error 
2fd70 66 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74  for the applicat
2fd80 69 6f 6e 20 74 6f 20 74 72 79 20 74 6f 20 75 73  ion to try to us
2fd90 65 0a 2a 2a 20 61 20 70 72 65 70 61 72 65 64 20  e.** a prepared 
2fda0 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20  statement after 
2fdb0 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61  it has been fina
2fdc0 6c 69 7a 65 64 2e 20 20 41 6e 79 20 75 73 65 20  lized.  Any use 
2fdd0 6f 66 20 61 20 70 72 65 70 61 72 65 64 0a 2a 2a  of a prepared.**
2fde0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
2fdf0 20 69 74 20 68 61 73 20 62 65 65 6e 20 66 69 6e   it has been fin
2fe00 61 6c 69 7a 65 64 20 63 61 6e 20 72 65 73 75 6c  alized can resul
2fe10 74 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 61  t in undefined a
2fe20 6e 64 0a 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c  nd.** undesirabl
2fe30 65 20 62 65 68 61 76 69 6f 72 20 73 75 63 68 20  e behavior such 
2fe40 61 73 20 73 65 67 66 61 75 6c 74 73 20 61 6e 64  as segfaults and
2fe50 20 68 65 61 70 20 63 6f 72 72 75 70 74 69 6f 6e   heap corruption
2fe60 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2fe70 5f 66 69 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65  _finalize(sqlite
2fe80 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
2fe90 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2fea0 20 52 65 73 65 74 20 41 20 50 72 65 70 61 72 65   Reset A Prepare
2feb0 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2fec0 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ct.**.** The sql
2fed0 69 74 65 33 5f 72 65 73 65 74 28 29 20 66 75 6e  ite3_reset() fun
2fee0 63 74 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20  ction is called 
2fef0 74 6f 20 72 65 73 65 74 20 61 20 5b 70 72 65 70  to reset a [prep
2ff00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a  ared statement].
2ff10 2a 2a 20 6f 62 6a 65 63 74 20 62 61 63 6b 20 74  ** object back t
2ff20 6f 20 69 74 73 20 69 6e 69 74 69 61 6c 20 73 74  o its initial st
2ff30 61 74 65 2c 20 72 65 61 64 79 20 74 6f 20 62 65  ate, ready to be
2ff40 20 72 65 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a   re-executed..**
2ff50 20 5e 41 6e 79 20 53 51 4c 20 73 74 61 74 65 6d   ^Any SQL statem
2ff60 65 6e 74 20 76 61 72 69 61 62 6c 65 73 20 74 68  ent variables th
2ff70 61 74 20 68 61 64 20 76 61 6c 75 65 73 20 62 6f  at had values bo
2ff80 75 6e 64 20 74 6f 20 74 68 65 6d 20 75 73 69 6e  und to them usin
2ff90 67 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  g.** the [sqlite
2ffa0 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71  3_bind_blob | sq
2ffb0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41  lite3_bind_*() A
2ffc0 50 49 5d 20 72 65 74 61 69 6e 20 74 68 65 69 72  PI] retain their
2ffd0 20 76 61 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20   values..** Use 
2ffe0 5b 73 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62  [sqlite3_clear_b
2fff0 69 6e 64 69 6e 67 73 28 29 5d 20 74 6f 20 72 65  indings()] to re
30000 73 65 74 20 74 68 65 20 62 69 6e 64 69 6e 67 73  set the bindings
30010 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71  ..**.** ^The [sq
30020 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
30030 69 6e 74 65 72 66 61 63 65 20 72 65 73 65 74 73  interface resets
30040 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
30050 74 61 74 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62  tatement] S.** b
30060 61 63 6b 20 74 6f 20 74 68 65 20 62 65 67 69 6e  ack to the begin
30070 6e 69 6e 67 20 6f 66 20 69 74 73 20 70 72 6f 67  ning of its prog
30080 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ram..**.** ^If t
30090 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
300a0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
300b0 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
300c0 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
300d0 61 74 65 6d 65 6e 74 5d 20 53 20 72 65 74 75 72  atement] S retur
300e0 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  ned [SQLITE_ROW]
300f0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45   or [SQLITE_DONE
30100 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c  ],.** or if [sql
30110 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 68 61  ite3_step(S)] ha
30120 73 20 6e 65 76 65 72 20 62 65 66 6f 72 65 20 62  s never before b
30130 65 65 6e 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c  een called on S,
30140 0a 2a 2a 20 74 68 65 6e 20 5b 73 71 6c 69 74 65  .** then [sqlite
30150 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75  3_reset(S)] retu
30160 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  rns [SQLITE_OK].
30170 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d  .**.** ^If the m
30180 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20  ost recent call 
30190 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  to [sqlite3_step
301a0 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20  (S)] for the.** 
301b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
301c0 65 6e 74 5d 20 53 20 69 6e 64 69 63 61 74 65 64  ent] S indicated
301d0 20 61 6e 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a   an error, then.
301e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
301f0 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 61 6e  t(S)] returns an
30200 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
30210 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a  ror code]..**.**
30220 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72   ^The [sqlite3_r
30230 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61  eset(S)] interfa
30240 63 65 20 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e  ce does not chan
30250 67 65 20 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a  ge the values.**
30260 20 6f 66 20 61 6e 79 20 5b 73 71 6c 69 74 65 33   of any [sqlite3
30270 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69  _bind_blob|bindi
30280 6e 67 73 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65  ngs] on the [pre
30290 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
302a0 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74   S..*/.int sqlit
302b0 65 33 5f 72 65 73 65 74 28 73 71 6c 69 74 65 33  e3_reset(sqlite3
302c0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
302d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
302e0 43 72 65 61 74 65 20 4f 72 20 52 65 64 65 66 69  Create Or Redefi
302f0 6e 65 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73  ne SQL Functions
30300 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
30310 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
30320 20 72 6f 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45   routines}.** KE
30330 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
30340 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30350 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45   function}.** KE
30360 59 57 4f 52 44 53 3a 20 7b 61 70 70 6c 69 63 61  YWORDS: {applica
30370 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
30380 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
30390 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
303a0 6e 73 20 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79  ns (collectively
303b0 20 6b 6e 6f 77 6e 20 61 73 20 22 66 75 6e 63 74   known as "funct
303c0 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75  ion creation rou
303d0 74 69 6e 65 73 22 29 0a 2a 2a 20 61 72 65 20 75  tines").** are u
303e0 73 65 64 20 74 6f 20 61 64 64 20 53 51 4c 20 66  sed to add SQL f
303f0 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72  unctions or aggr
30400 65 67 61 74 65 73 20 6f 72 20 74 6f 20 72 65 64  egates or to red
30410 65 66 69 6e 65 20 74 68 65 20 62 65 68 61 76 69  efine the behavi
30420 6f 72 0a 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e  or.** of existin
30430 67 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  g SQL functions 
30440 6f 72 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  or aggregates.  
30450 54 68 65 20 6f 6e 6c 79 20 64 69 66 66 65 72 65  The only differe
30460 6e 63 65 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20  nces between.** 
30470 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  these routines a
30480 72 65 20 74 68 65 20 74 65 78 74 20 65 6e 63 6f  re the text enco
30490 64 69 6e 67 20 65 78 70 65 63 74 65 64 20 66 6f  ding expected fo
304a0 72 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20  r.** the second 
304b0 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 6e  parameter (the n
304c0 61 6d 65 20 6f 66 20 74 68 65 20 66 75 6e 63 74  ame of the funct
304d0 69 6f 6e 20 62 65 69 6e 67 20 63 72 65 61 74 65  ion being create
304e0 64 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 70 72  d).** and the pr
304f0 65 73 65 6e 63 65 20 6f 72 20 61 62 73 65 6e 63  esence or absenc
30500 65 20 6f 66 20 61 20 64 65 73 74 72 75 63 74 6f  e of a destructo
30510 72 20 63 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a  r callback for.*
30520 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * the applicatio
30530 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a  n data pointer..
30540 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
30550 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30560 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
30570 65 63 74 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68  ection] to which
30580 20 74 68 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63   the SQL.** func
30590 74 69 6f 6e 20 69 73 20 74 6f 20 62 65 20 61 64  tion is to be ad
305a0 64 65 64 2e 20 20 5e 49 66 20 61 6e 20 61 70 70  ded.  ^If an app
305b0 6c 69 63 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f  lication uses mo
305c0 72 65 20 74 68 61 6e 20 6f 6e 65 20 64 61 74 61  re than one data
305d0 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69  base.** connecti
305e0 6f 6e 20 74 68 65 6e 20 61 70 70 6c 69 63 61 74  on then applicat
305f0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
30600 66 75 6e 63 74 69 6f 6e 73 20 6d 75 73 74 20 62  functions must b
30610 65 20 61 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61  e added.** to ea
30620 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
30630 65 63 74 69 6f 6e 20 73 65 70 61 72 61 74 65 6c  ection separatel
30640 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65  y..**.** ^The se
30650 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
30660 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
30670 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  e SQL function t
30680 6f 20 62 65 20 63 72 65 61 74 65 64 20 6f 72 0a  o be created or.
30690 2a 2a 20 72 65 64 65 66 69 6e 65 64 2e 20 20 5e  ** redefined.  ^
306a0 54 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  The length of th
306b0 65 20 6e 61 6d 65 20 69 73 20 6c 69 6d 69 74 65  e name is limite
306c0 64 20 74 6f 20 32 35 35 20 62 79 74 65 73 20 69  d to 255 bytes i
306d0 6e 20 61 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70  n a UTF-8.** rep
306e0 72 65 73 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63  resentation, exc
306f0 6c 75 73 69 76 65 20 6f 66 20 74 68 65 20 7a 65  lusive of the ze
30700 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro-terminator.  
30710 5e 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 6e  ^Note that the n
30720 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69  ame.** length li
30730 6d 69 74 20 69 73 20 69 6e 20 55 54 46 2d 38 20  mit is in UTF-8 
30740 62 79 74 65 73 2c 20 6e 6f 74 20 63 68 61 72 61  bytes, not chara
30750 63 74 65 72 73 20 6e 6f 72 20 55 54 46 2d 31 36  cters nor UTF-16
30760 20 62 79 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e   bytes.  .** ^An
30770 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 72 65  y attempt to cre
30780 61 74 65 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  ate a function w
30790 69 74 68 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d  ith a longer nam
307a0 65 0a 2a 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74  e.** will result
307b0 20 69 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   in [SQLITE_MISU
307c0 53 45 5d 20 62 65 69 6e 67 20 72 65 74 75 72 6e  SE] being return
307d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  ed..**.** ^The t
307e0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 28  hird parameter (
307f0 6e 41 72 67 29 0a 2a 2a 20 69 73 20 74 68 65 20  nArg).** is the 
30800 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
30810 6e 74 73 20 74 68 61 74 20 74 68 65 20 53 51 4c  nts that the SQL
30820 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20   function or.** 
30830 61 67 67 72 65 67 61 74 65 20 74 61 6b 65 73 2e  aggregate takes.
30840 20 5e 49 66 20 74 68 69 73 20 70 61 72 61 6d 65   ^If this parame
30850 74 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e 20  ter is -1, then 
30860 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
30870 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65   or.** aggregate
30880 20 6d 61 79 20 74 61 6b 65 20 61 6e 79 20 6e 75   may take any nu
30890 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74  mber of argument
308a0 73 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20  s between 0 and 
308b0 74 68 65 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74  the limit.** set
308c0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d   by [sqlite3_lim
308d0 69 74 5d 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  it]([SQLITE_LIMI
308e0 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29  T_FUNCTION_ARG])
308f0 2e 20 20 49 66 20 74 68 65 20 74 68 69 72 64 0a  .  If the third.
30900 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
30910 6c 65 73 73 20 74 68 61 6e 20 2d 31 20 6f 72 20  less than -1 or 
30920 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 32 37  greater than 127
30930 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
30940 6f 72 20 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e  or is.** undefin
30950 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
30960 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 2c  ourth parameter,
30970 20 65 54 65 78 74 52 65 70 2c 20 73 70 65 63 69   eTextRep, speci
30980 66 69 65 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51  fies what.** [SQ
30990 4c 49 54 45 5f 55 54 46 38 20 7c 20 74 65 78 74  LITE_UTF8 | text
309a0 20 65 6e 63 6f 64 69 6e 67 5d 20 74 68 69 73 20   encoding] this 
309b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 70 72 65  SQL function pre
309c0 66 65 72 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20  fers for.** its 
309d0 70 61 72 61 6d 65 74 65 72 73 2e 20 20 54 68 65  parameters.  The
309e0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f   application sho
309f0 75 6c 64 20 73 65 74 20 74 68 69 73 20 70 61 72  uld set this par
30a00 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51  ameter to.** [SQ
30a10 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 20 69 66  LITE_UTF16LE] if
30a20 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d   the function im
30a30 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76  plementation inv
30a40 6f 6b 65 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  okes .** [sqlite
30a50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
30a60 28 29 5d 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c  ()] on an input,
30a70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
30a80 36 42 45 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69  6BE] if the.** i
30a90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e  mplementation in
30aa0 76 6f 6b 65 73 20 5b 73 71 6c 69 74 65 33 5f 76  vokes [sqlite3_v
30ab0 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 5d  alue_text16be()]
30ac0 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
30ad0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  .** [SQLITE_UTF1
30ae0 36 5d 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 76  6] if [sqlite3_v
30af0 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 69  alue_text16()] i
30b00 73 20 75 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49  s used, or [SQLI
30b10 54 45 5f 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65  TE_UTF8].** othe
30b20 72 77 69 73 65 2e 20 20 5e 54 68 65 20 73 61 6d  rwise.  ^The sam
30b30 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d  e SQL function m
30b40 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
30b50 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73 20   multiple times 
30b60 75 73 69 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65  using.** differe
30b70 6e 74 20 70 72 65 66 65 72 72 65 64 20 74 65 78  nt preferred tex
30b80 74 20 65 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74  t encodings, wit
30b90 68 20 64 69 66 66 65 72 65 6e 74 20 69 6d 70 6c  h different impl
30ba0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a  ementations for.
30bb0 2a 2a 20 65 61 63 68 20 65 6e 63 6f 64 69 6e 67  ** each encoding
30bc0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69  ..** ^When multi
30bd0 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ple implementati
30be0 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ons of the same 
30bf0 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 61 76 61  function are ava
30c00 69 6c 61 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a  ilable, SQLite.*
30c10 2a 20 77 69 6c 6c 20 70 69 63 6b 20 74 68 65 20  * will pick the 
30c20 6f 6e 65 20 74 68 61 74 20 69 6e 76 6f 6c 76 65  one that involve
30c30 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d 6f 75  s the least amou
30c40 6e 74 20 6f 66 20 64 61 74 61 20 63 6f 6e 76 65  nt of data conve
30c50 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rsion..**.** ^Th
30c60 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
30c70 65 72 20 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c  er may optionall
30c80 79 20 62 65 20 4f 52 65 64 20 77 69 74 68 20 5b  y be ORed with [
30c90 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49  SQLITE_DETERMINI
30ca0 53 54 49 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e  STIC].** to sign
30cb0 61 6c 20 74 68 61 74 20 74 68 65 20 66 75 6e 63  al that the func
30cc0 74 69 6f 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73  tion will always
30cd0 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65   return the same
30ce0 20 72 65 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a   result given.**
30cf0 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73   the same inputs
30d00 20 77 69 74 68 69 6e 20 61 20 73 69 6e 67 6c 65   within a single
30d10 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20   SQL statement. 
30d20 20 4d 6f 73 74 20 53 51 4c 20 66 75 6e 63 74 69   Most SQL functi
30d30 6f 6e 73 20 61 72 65 0a 2a 2a 20 64 65 74 65 72  ons are.** deter
30d40 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 62  ministic.  The b
30d50 75 69 6c 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28  uilt-in [random(
30d60 29 5d 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  )] SQL function 
30d70 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66  is an example of
30d80 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74   a.** function t
30d90 68 61 74 20 69 73 20 6e 6f 74 20 64 65 74 65 72  hat is not deter
30da0 6d 69 6e 69 73 74 69 63 2e 20 20 54 68 65 20 53  ministic.  The S
30db0 51 4c 69 74 65 20 71 75 65 72 79 20 70 6c 61 6e  QLite query plan
30dc0 6e 65 72 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a  ner is able to.*
30dd0 2a 20 70 65 72 66 6f 72 6d 20 61 64 64 69 74 69  * perform additi
30de0 6f 6e 61 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f  onal optimizatio
30df0 6e 73 20 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73  ns on determinis
30e00 74 69 63 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73  tic functions, s
30e10 6f 20 75 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20  o use.** of the 
30e20 5b 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e  [SQLITE_DETERMIN
30e30 49 53 54 49 43 5d 20 66 6c 61 67 20 69 73 20 72  ISTIC] flag is r
30e40 65 63 6f 6d 6d 65 6e 64 65 64 20 77 68 65 72 65  ecommended where
30e50 20 70 6f 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a   possible..**.**
30e60 20 5e 28 54 68 65 20 66 69 66 74 68 20 70 61 72   ^(The fifth par
30e70 61 6d 65 74 65 72 20 69 73 20 61 6e 20 61 72 62  ameter is an arb
30e80 69 74 72 61 72 79 20 70 6f 69 6e 74 65 72 2e 20  itrary pointer. 
30e90 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   The implementat
30ea0 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75  ion of the.** fu
30eb0 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20  nction can gain 
30ec0 61 63 63 65 73 73 20 74 6f 20 74 68 69 73 20 70  access to this p
30ed0 6f 69 6e 74 65 72 20 75 73 69 6e 67 20 5b 73 71  ointer using [sq
30ee0 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
30ef0 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  )].)^.**.** ^The
30f00 20 73 69 78 74 68 2c 20 73 65 76 65 6e 74 68 20   sixth, seventh 
30f10 61 6e 64 20 65 69 67 68 74 68 20 70 61 72 61 6d  and eighth param
30f20 65 74 65 72 73 2c 20 78 46 75 6e 63 2c 20 78 53  eters, xFunc, xS
30f30 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20  tep and xFinal, 
30f40 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20  are.** pointers 
30f50 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65 20 66 75  to C-language fu
30f60 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 69 6d 70  nctions that imp
30f70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66  lement the SQL f
30f80 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67  unction or.** ag
30f90 67 72 65 67 61 74 65 2e 20 5e 41 20 73 63 61 6c  gregate. ^A scal
30fa0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ar SQL function 
30fb0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
30fc0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
30fd0 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62  e xFunc.** callb
30fe0 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70  ack only; NULL p
30ff0 6f 69 6e 74 65 72 73 20 6d 75 73 74 20 62 65 20  ointers must be 
31000 70 61 73 73 65 64 20 61 73 20 74 68 65 20 78 53  passed as the xS
31010 74 65 70 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a  tep and xFinal.*
31020 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 5e 41  * parameters. ^A
31030 6e 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  n aggregate SQL 
31040 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65  function require
31050 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  s an implementat
31060 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20  ion of xStep.** 
31070 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e  and xFinal and N
31080 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d 75 73 74  ULL pointer must
31090 20 62 65 20 70 61 73 73 65 64 20 66 6f 72 20 78   be passed for x
310a0 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65  Func. ^To delete
310b0 20 61 6e 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20   an existing.** 
310c0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  SQL function or 
310d0 61 67 67 72 65 67 61 74 65 2c 20 70 61 73 73 20  aggregate, pass 
310e0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f  NULL pointers fo
310f0 72 20 61 6c 6c 20 74 68 72 65 65 20 66 75 6e 63  r all three func
31100 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
31110 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68  s..**.** ^(If th
31120 65 20 6e 69 6e 74 68 20 70 61 72 61 6d 65 74 65  e ninth paramete
31130 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
31140 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
31150 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a  ) is not NULL,.*
31160 2a 20 74 68 65 6e 20 69 74 20 69 73 20 64 65 73  * then it is des
31170 74 72 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20  tructor for the 
31180 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
31190 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68   pointer. .** Th
311a0 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20  e destructor is 
311b0 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20 74 68 65  invoked when the
311c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c   function is del
311d0 65 74 65 64 2c 20 65 69 74 68 65 72 20 62 79 20  eted, either by 
311e0 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61  being.** overloa
311f0 64 65 64 20 6f 72 20 77 68 65 6e 20 74 68 65 20  ded or when the 
31200 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
31210 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a  ion closes.)^.**
31220 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
31230 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64   is also invoked
31240 20 69 66 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a   if the call to.
31250 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
31260 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20  e_function_v2() 
31270 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20  fails..** ^When 
31280 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 63  the destructor c
31290 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20 74  allback of the t
312a0 65 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  enth parameter i
312b0 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a  s invoked, it.**
312c0 20 69 73 20 70 61 73 73 65 64 20 61 20 73 69 6e   is passed a sin
312d0 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
312e0 63 68 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  ch is a copy of 
312f0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
31300 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72  data .** pointer
31310 20 77 68 69 63 68 20 77 61 73 20 74 68 65 20 66   which was the f
31320 69 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  ifth parameter t
31330 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31340 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a  _function_v2()..
31350 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 70 65 72  **.** ^It is per
31360 6d 69 74 74 65 64 20 74 6f 20 72 65 67 69 73 74  mitted to regist
31370 65 72 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  er multiple impl
31380 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
31390 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74  he same.** funct
313a0 69 6f 6e 73 20 77 69 74 68 20 74 68 65 20 73 61  ions with the sa
313b0 6d 65 20 6e 61 6d 65 20 62 75 74 20 77 69 74 68  me name but with
313c0 20 65 69 74 68 65 72 20 64 69 66 66 65 72 69 6e   either differin
313d0 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20  g numbers of.** 
313e0 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 64 69 66  arguments or dif
313f0 66 65 72 69 6e 67 20 70 72 65 66 65 72 72 65 64  fering preferred
31400 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e   text encodings.
31410 20 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75    ^SQLite will u
31420 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d  se.** the implem
31430 65 6e 74 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f  entation that mo
31440 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68  st closely match
31450 65 73 20 74 68 65 20 77 61 79 20 69 6e 20 77 68  es the way in wh
31460 69 63 68 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66  ich the.** SQL f
31470 75 6e 63 74 69 6f 6e 20 69 73 20 75 73 65 64 2e  unction is used.
31480 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d    ^A function im
31490 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74  plementation wit
314a0 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65  h a non-negative
314b0 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61 6d 65 74  .** nArg paramet
314c0 65 72 20 69 73 20 61 20 62 65 74 74 65 72 20 6d  er is a better m
314d0 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
314e0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
314f0 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65  ion with.** a ne
31500 67 61 74 69 76 65 20 6e 41 72 67 2e 20 20 5e 41  gative nArg.  ^A
31510 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
31520 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 65  the preferred te
31530 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d  xt encoding.** m
31540 61 74 63 68 65 73 20 74 68 65 20 64 61 74 61 62  atches the datab
31550 61 73 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20  ase encoding is 
31560 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63  a better.** matc
31570 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
31580 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f  n where the enco
31590 64 69 6e 67 20 69 73 20 64 69 66 66 65 72 65 6e  ding is differen
315a0 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74  t.  .** ^A funct
315b0 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e  ion where the en
315c0 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63  coding differenc
315d0 65 20 69 73 20 62 65 74 77 65 65 6e 20 55 54 46  e is between UTF
315e0 31 36 6c 65 20 61 6e 64 20 55 54 46 31 36 62 65  16le and UTF16be
315f0 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73 65 72 20  .** is a closer 
31600 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
31610 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
31620 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72 65  encoding differe
31630 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74 77 65 65  nce is.** betwee
31640 6e 20 55 54 46 38 20 61 6e 64 20 55 54 46 31 36  n UTF8 and UTF16
31650 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69  ..**.** ^Built-i
31660 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20  n functions may 
31670 62 65 20 6f 76 65 72 6c 6f 61 64 65 64 20 62 79  be overloaded by
31680 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
31690 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
316a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70  ns..**.** ^An ap
316b0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
316c0 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 70 65  d function is pe
316d0 72 6d 69 74 74 65 64 20 74 6f 20 63 61 6c 6c 20  rmitted to call 
316e0 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20  other.** SQLite 
316f0 69 6e 74 65 72 66 61 63 65 73 2e 20 20 48 6f 77  interfaces.  How
31700 65 76 65 72 2c 20 73 75 63 68 20 63 61 6c 6c 73  ever, such calls
31710 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f   must not.** clo
31720 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
31730 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66  connection nor f
31740 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65 73 65 74  inalize or reset
31750 20 74 68 65 20 70 72 65 70 61 72 65 64 0a 2a 2a   the prepared.**
31760 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 77 68   statement in wh
31770 69 63 68 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ich the function
31780 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a   is running..*/.
31790 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
317a0 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73  te_function(.  s
317b0 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
317c0 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
317d0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
317e0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
317f0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
31800 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
31810 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
31820 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31830 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31840 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31850 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31860 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31870 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31880 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31890 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
318a0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
318b0 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65 33 20  on16(.  sqlite3 
318c0 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69  *db,.  const voi
318d0 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65  d *zFunctionName
318e0 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20  ,.  int nArg,.  
318f0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20  int eTextRep,.  
31900 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f  void *pApp,.  vo
31910 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69  id (*xFunc)(sqli
31920 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74  te3_context*,int
31930 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a  ,sqlite3_value**
31940 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65  ),.  void (*xSte
31950 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  p)(sqlite3_conte
31960 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31970 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31980 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74   (*xFinal)(sqlit
31990 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a  e3_context*).);.
319a0 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
319b0 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a  te_function_v2(.
319c0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
319d0 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
319e0 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
319f0 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
31a00 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
31a10 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
31a20 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
31a30 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
31a40 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
31a50 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
31a60 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
31a70 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
31a80 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
31a90 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
31aa0 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a  text*),.  void(*
31ab0 78 44 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29  xDestroy)(void*)
31ac0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
31ad0 52 45 46 3a 20 54 65 78 74 20 45 6e 63 6f 64 69  REF: Text Encodi
31ae0 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ngs.**.** These 
31af0 63 6f 6e 73 74 61 6e 74 20 64 65 66 69 6e 65 20  constant define 
31b00 69 6e 74 65 67 65 72 20 63 6f 64 65 73 20 74 68  integer codes th
31b10 61 74 20 72 65 70 72 65 73 65 6e 74 20 74 68 65  at represent the
31b20 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74   various.** text
31b30 20 65 6e 63 6f 64 69 6e 67 73 20 73 75 70 70 6f   encodings suppo
31b40 72 74 65 64 20 62 79 20 53 51 4c 69 74 65 2e 0a  rted by SQLite..
31b50 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31b60 45 5f 55 54 46 38 20 20 20 20 20 20 20 20 20 20  E_UTF8          
31b70 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
31b80 45 5f 55 54 46 31 36 4c 45 20 20 20 20 20 20 20  E_UTF16LE       
31b90 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
31ba0 45 5f 55 54 46 31 36 42 45 20 20 20 20 20 20 20  E_UTF16BE       
31bb0 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
31bc0 45 5f 55 54 46 31 36 20 20 20 20 20 20 20 20 20  E_UTF16         
31bd0 20 34 20 20 20 20 2f 2a 20 55 73 65 20 6e 61 74   4    /* Use nat
31be0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 2a  ive byte order *
31bf0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
31c00 5f 41 4e 59 20 20 20 20 20 20 20 20 20 20 20 20  _ANY            
31c10 35 20 20 20 20 2f 2a 20 44 65 70 72 65 63 61 74  5    /* Deprecat
31c20 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
31c30 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e  LITE_UTF16_ALIGN
31c40 45 44 20 20 38 20 20 20 20 2f 2a 20 73 71 6c 69  ED  8    /* sqli
31c50 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31c60 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a  tion only */../*
31c70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75  .** CAPI3REF: Fu
31c80 6e 63 74 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a  nction Flags.**.
31c90 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
31ca0 74 73 20 6d 61 79 20 62 65 20 4f 52 65 64 20 74  ts may be ORed t
31cb0 6f 67 65 74 68 65 72 20 77 69 74 68 20 74 68 65  ogether with the
31cc0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46   .** [SQLITE_UTF
31cd0 38 20 7c 20 70 72 65 66 65 72 72 65 64 20 74 65  8 | preferred te
31ce0 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20  xt encoding] as 
31cf0 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
31d00 65 6e 74 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  ent.** to [sqlit
31d10 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
31d20 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  on()], [sqlite3_
31d30 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31d40 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c  6()], or.** [sql
31d50 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31d60 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23  tion_v2()]..*/.#
31d70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45  define SQLITE_DE
31d80 54 45 52 4d 49 4e 49 53 54 49 43 20 20 20 20 30  TERMINISTIC    0
31d90 78 38 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  x800../*.** CAPI
31da0 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64  3REF: Deprecated
31db0 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45   Functions.** DE
31dc0 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54  PRECATED.**.** T
31dd0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61  hese functions a
31de0 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e  re [deprecated].
31df0 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61    In order to ma
31e00 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61  intain.** backwa
31e10 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
31e20 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64  y with older cod
31e30 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f  e, these functio
31e40 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20  ns continue .** 
31e50 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e  to be supported.
31e60 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61    However, new a
31e70 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
31e80 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20  ld avoid.** the 
31e90 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e  use of these fun
31ea0 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70  ctions.  To help
31eb0 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c   encourage peopl
31ec0 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73  e to avoid.** us
31ed0 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74 69  ing these functi
31ee0 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20  ons, we are not 
31ef0 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f  going to tell yo
31f00 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a  u what they do..
31f10 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54  */.#ifndef SQLIT
31f20 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45  E_OMIT_DEPRECATE
31f30 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  D.SQLITE_DEPRECA
31f40 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
31f50 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28  aggregate_count(
31f60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31f70 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
31f80 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
31f90 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65 33  _expired(sqlite3
31fa0 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
31fb0 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
31fc0 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f  qlite3_transfer_
31fd0 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33  bindings(sqlite3
31fe0 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f  _stmt*, sqlite3_
31ff0 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44  stmt*);.SQLITE_D
32000 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71  EPRECATED int sq
32010 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63  lite3_global_rec
32020 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49  over(void);.SQLI
32030 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f  TE_DEPRECATED vo
32040 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61  id sqlite3_threa
32050 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b  d_cleanup(void);
32060 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
32070 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d  ED int sqlite3_m
32080 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64  emory_alarm(void
32090 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65  (*)(void*,sqlite
320a0 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20  3_int64,int),.  
320b0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
320c0 20 20 20 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65      void*,sqlite
320d0 33 5f 69 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66  3_int64);.#endif
320e0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
320f0 3a 20 4f 62 74 61 69 6e 69 6e 67 20 53 51 4c 20  : Obtaining SQL 
32100 46 75 6e 63 74 69 6f 6e 20 50 61 72 61 6d 65 74  Function Paramet
32110 65 72 20 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20  er Values.**.** 
32120 54 68 65 20 43 2d 6c 61 6e 67 75 61 67 65 20 69  The C-language i
32130 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
32140 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
32150 6e 64 20 61 67 67 72 65 67 61 74 65 73 20 75 73  nd aggregates us
32160 65 73 0a 2a 2a 20 74 68 69 73 20 73 65 74 20 6f  es.** this set o
32170 66 20 69 6e 74 65 72 66 61 63 65 20 72 6f 75 74  f interface rout
32180 69 6e 65 73 20 74 6f 20 61 63 63 65 73 73 20 74  ines to access t
32190 68 65 20 70 61 72 61 6d 65 74 65 72 20 76 61 6c  he parameter val
321a0 75 65 73 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75  ues on.** the fu
321b0 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65 67  nction or aggreg
321c0 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ate..**.** The x
321d0 46 75 6e 63 20 28 66 6f 72 20 73 63 61 6c 61 72  Func (for scalar
321e0 20 66 75 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78   functions) or x
321f0 53 74 65 70 20 28 66 6f 72 20 61 67 67 72 65 67  Step (for aggreg
32200 61 74 65 73 29 20 70 61 72 61 6d 65 74 65 72 73  ates) parameters
32210 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
32220 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
32230 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
32240 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
32250 36 28 29 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63  6()].** define c
32260 61 6c 6c 62 61 63 6b 73 20 74 68 61 74 20 69 6d  allbacks that im
32270 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51 4c 20  plement the SQL 
32280 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
32290 67 72 65 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65  gregates..** The
322a0 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
322b0 6f 20 74 68 65 73 65 20 63 61 6c 6c 62 61 63 6b  o these callback
322c0 73 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  s is an array of
322d0 20 70 6f 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20   pointers to.** 
322e0 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  [protected sqlit
322f0 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
32300 73 2e 20 20 54 68 65 72 65 20 69 73 20 6f 6e 65  s.  There is one
32310 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
32320 20 6f 62 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65   object for.** e
32330 61 63 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ach parameter to
32340 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
32350 6e 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69 6e  n.  These routin
32360 65 73 20 61 72 65 20 75 73 65 64 20 74 6f 0a 2a  es are used to.*
32370 2a 20 65 78 74 72 61 63 74 20 76 61 6c 75 65 73  * extract values
32380 20 66 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74   from the [sqlit
32390 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
323a0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s..**.** These r
323b0 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c  outines work onl
323c0 79 20 77 69 74 68 20 5b 70 72 6f 74 65 63 74 65  y with [protecte
323d0 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
323e0 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79   objects..** Any
323f0 20 61 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20   attempt to use 
32400 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  these routines o
32410 6e 20 61 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65  n an [unprotecte
32420 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
32430 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 73 75 6c  .** object resul
32440 74 73 20 69 6e 20 75 6e 64 65 66 69 6e 65 64 20  ts in undefined 
32450 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
32460 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
32470 77 6f 72 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74  work just like t
32480 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
32490 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   [column access 
324a0 66 75 6e 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78  functions].** ex
324b0 63 65 70 74 20 74 68 61 74 20 20 74 68 65 73 65  cept that  these
324c0 20 72 6f 75 74 69 6e 65 73 20 74 61 6b 65 20 61   routines take a
324d0 20 73 69 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74   single [protect
324e0 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
324f0 5d 20 6f 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e  ] object.** poin
32500 74 65 72 20 69 6e 73 74 65 61 64 20 6f 66 20 61  ter instead of a
32510 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d   [sqlite3_stmt*]
32520 20 70 6f 69 6e 74 65 72 20 61 6e 64 20 61 6e 20   pointer and an 
32530 69 6e 74 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e  integer column n
32540 75 6d 62 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  umber..**.** ^Th
32550 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
32560 74 65 78 74 31 36 28 29 20 69 6e 74 65 72 66 61  text16() interfa
32570 63 65 20 65 78 74 72 61 63 74 73 20 61 20 55 54  ce extracts a UT
32580 46 2d 31 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69  F-16 string.** i
32590 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74  n the native byt
325a0 65 2d 6f 72 64 65 72 20 6f 66 20 74 68 65 20 68  e-order of the h
325b0 6f 73 74 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54  ost machine.  ^T
325c0 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  he.** sqlite3_va
325d0 6c 75 65 5f 74 65 78 74 31 36 62 65 28 29 20 61  lue_text16be() a
325e0 6e 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nd sqlite3_value
325f0 5f 74 65 78 74 31 36 6c 65 28 29 20 69 6e 74 65  _text16le() inte
32600 72 66 61 63 65 73 0a 2a 2a 20 65 78 74 72 61 63  rfaces.** extrac
32610 74 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 73  t UTF-16 strings
32620 20 61 73 20 62 69 67 2d 65 6e 64 69 61 6e 20 61   as big-endian a
32630 6e 64 20 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e  nd little-endian
32640 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
32650 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
32660 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63  e3_value_numeric
32670 5f 74 79 70 65 28 29 20 69 6e 74 65 72 66 61 63  _type() interfac
32680 65 20 61 74 74 65 6d 70 74 73 20 74 6f 20 61 70  e attempts to ap
32690 70 6c 79 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61  ply.** numeric a
326a0 66 66 69 6e 69 74 79 20 74 6f 20 74 68 65 20 76  ffinity to the v
326b0 61 6c 75 65 2e 20 20 54 68 69 73 20 6d 65 61 6e  alue.  This mean
326c0 73 20 74 68 61 74 20 61 6e 20 61 74 74 65 6d 70  s that an attemp
326d0 74 20 69 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20  t is.** made to 
326e0 63 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75  convert the valu
326f0 65 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  e to an integer 
32700 6f 72 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  or floating poin
32710 74 2e 20 20 49 66 0a 2a 2a 20 73 75 63 68 20 61  t.  If.** such a
32720 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
32730 6f 73 73 69 62 6c 65 20 77 69 74 68 6f 75 74 20  ossible without 
32740 6c 6f 73 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74  loss of informat
32750 69 6f 6e 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a  ion (in other.**
32760 20 77 6f 72 64 73 2c 20 69 66 20 74 68 65 20 76   words, if the v
32770 61 6c 75 65 20 69 73 20 61 20 73 74 72 69 6e 67  alue is a string
32780 20 74 68 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65   that looks like
32790 20 61 20 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68   a number).** th
327a0 65 6e 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  en the conversio
327b0 6e 20 69 73 20 70 65 72 66 6f 72 6d 65 64 2e 20  n is performed. 
327c0 20 4f 74 68 65 72 77 69 73 65 20 6e 6f 20 63 6f   Otherwise no co
327d0 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e  nversion occurs.
327e0 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
327f0 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
32800 70 65 5d 20 61 66 74 65 72 20 63 6f 6e 76 65 72  pe] after conver
32810 73 69 6f 6e 20 69 73 20 72 65 74 75 72 6e 65 64  sion is returned
32820 2e 29 5e 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65  .)^.**.** Please
32830 20 70 61 79 20 70 61 72 74 69 63 75 6c 61 72 20   pay particular 
32840 61 74 74 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65  attention to the
32850 20 66 61 63 74 20 74 68 61 74 20 74 68 65 20 70   fact that the p
32860 6f 69 6e 74 65 72 20 72 65 74 75 72 6e 65 64 0a  ointer returned.
32870 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ** from [sqlite3
32880 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20  _value_blob()], 
32890 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
328a0 65 78 74 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  ext()], or.** [s
328b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
328c0 74 31 36 28 29 5d 20 63 61 6e 20 62 65 20 69 6e  t16()] can be in
328d0 76 61 6c 69 64 61 74 65 64 20 62 79 20 61 20 73  validated by a s
328e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
328f0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  o.** [sqlite3_va
32900 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73  lue_bytes()], [s
32910 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74  qlite3_value_byt
32920 65 73 31 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65  es16()], [sqlite
32930 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c  3_value_text()],
32940 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
32950 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 2e  value_text16()].
32960 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
32970 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20 63 61  tines must be ca
32980 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61  lled from the sa
32990 6d 65 20 74 68 72 65 61 64 20 61 73 0a 2a 2a 20  me thread as.** 
329a0 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  the SQL function
329b0 20 74 68 61 74 20 73 75 70 70 6c 69 65 64 20 74   that supplied t
329c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
329d0 65 2a 5d 20 70 61 72 61 6d 65 74 65 72 73 2e 0a  e*] parameters..
329e0 2a 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  */.const void *s
329f0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
32a00 62 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  b(sqlite3_value*
32a10 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
32a20 61 6c 75 65 5f 62 79 74 65 73 28 73 71 6c 69 74  alue_bytes(sqlit
32a30 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32a40 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
32a50 74 65 73 31 36 28 73 71 6c 69 74 65 33 5f 76 61  tes16(sqlite3_va
32a60 6c 75 65 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71  lue*);.double sq
32a70 6c 69 74 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62  lite3_value_doub
32a80 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
32a90 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
32aa0 76 61 6c 75 65 5f 69 6e 74 28 73 71 6c 69 74 65  value_int(sqlite
32ab0 33 5f 76 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74  3_value*);.sqlit
32ac0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
32ad0 5f 76 61 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c  _value_int64(sql
32ae0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
32af0 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68 61  nst unsigned cha
32b00 72 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r *sqlite3_value
32b10 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 76 61  _text(sqlite3_va
32b20 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
32b30 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
32b40 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
32b50 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76  value*);.const v
32b60 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
32b70 75 65 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  ue_text16le(sqli
32b80 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
32b90 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
32ba0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 62 65 28  _value_text16be(
32bb0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32bc0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32bd0 75 65 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ue_type(sqlite3_
32be0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32bf0 69 74 65 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72  ite3_value_numer
32c00 69 63 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ic_type(sqlite3_
32c10 76 61 6c 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  value*);../*.** 
32c20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e  CAPI3REF: Obtain
32c30 20 41 67 67 72 65 67 61 74 65 20 46 75 6e 63 74   Aggregate Funct
32c40 69 6f 6e 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a  ion Context.**.*
32c50 2a 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * Implementation
32c60 73 20 6f 66 20 61 67 67 72 65 67 61 74 65 20 53  s of aggregate S
32c70 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  QL functions use
32c80 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
32c90 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d   to allocate mem
32ca0 6f 72 79 20 66 6f 72 20 73 74 6f 72 69 6e 67 20  ory for storing 
32cb0 74 68 65 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a  their state..**.
32cc0 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69  ** ^The first ti
32cd0 6d 65 20 74 68 65 20 73 71 6c 69 74 65 33 5f 61  me the sqlite3_a
32ce0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32cf0 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 69 73  (C,N) routine is
32d00 20 63 61 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20   called .** for 
32d10 61 20 70 61 72 74 69 63 75 6c 61 72 20 61 67 67  a particular agg
32d20 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c  regate function,
32d30 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63   SQLite.** alloc
32d40 61 74 65 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79  ates N of memory
32d50 2c 20 7a 65 72 6f 65 73 20 6f 75 74 20 74 68 61  , zeroes out tha
32d60 74 20 6d 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65  t memory, and re
32d70 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a  turns a pointer.
32d80 2a 2a 20 74 6f 20 74 68 65 20 6e 65 77 20 6d 65  ** to the new me
32d90 6d 6f 72 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64  mory. ^On second
32da0 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
32db0 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69  calls to.** sqli
32dc0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
32dd0 6e 74 65 78 74 28 29 20 66 6f 72 20 74 68 65 20  ntext() for the 
32de0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
32df0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
32e00 2c 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20 62 75  ,.** the same bu
32e10 66 66 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  ffer is returned
32e20 2e 20 20 53 71 6c 69 74 65 33 5f 61 67 67 72 65  .  Sqlite3_aggre
32e30 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 69  gate_context() i
32e40 73 20 6e 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61  s normally.** ca
32e50 6c 6c 65 64 20 6f 6e 63 65 20 66 6f 72 20 65 61  lled once for ea
32e60 63 68 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ch invocation of
32e70 20 74 68 65 20 78 53 74 65 70 20 63 61 6c 6c 62   the xStep callb
32e80 61 63 6b 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65  ack and then one
32e90 0a 2a 2a 20 6c 61 73 74 20 74 69 6d 65 20 77 68  .** last time wh
32ea0 65 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61  en the xFinal ca
32eb0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
32ec0 64 2e 20 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f  d.  ^(When no ro
32ed0 77 73 20 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61  ws match.** an a
32ee0 67 67 72 65 67 61 74 65 20 71 75 65 72 79 2c 20  ggregate query, 
32ef0 74 68 65 20 78 53 74 65 70 28 29 20 63 61 6c 6c  the xStep() call
32f00 62 61 63 6b 20 6f 66 20 74 68 65 20 61 67 67 72  back of the aggr
32f10 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a  egate function.*
32f20 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
32f30 20 69 73 20 6e 65 76 65 72 20 63 61 6c 6c 65 64   is never called
32f40 20 61 6e 64 20 78 46 69 6e 61 6c 28 29 20 69 73   and xFinal() is
32f50 20 63 61 6c 6c 65 64 20 65 78 61 63 74 6c 79 20   called exactly 
32f60 6f 6e 63 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73  once..** In thos
32f70 65 20 63 61 73 65 73 2c 20 73 71 6c 69 74 65 33  e cases, sqlite3
32f80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32f90 78 74 28 29 20 6d 69 67 68 74 20 62 65 20 63 61  xt() might be ca
32fa0 6c 6c 65 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lled for the.** 
32fb0 66 69 72 73 74 20 74 69 6d 65 20 66 72 6f 6d 20  first time from 
32fc0 77 69 74 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e  within xFinal().
32fd0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  )^.**.** ^The sq
32fe0 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32ff0 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
33000 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 4e  tine returns a N
33010 55 4c 4c 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20  ULL pointer .** 
33020 77 68 65 6e 20 66 69 72 73 74 20 63 61 6c 6c 65  when first calle
33030 64 20 69 66 20 4e 20 69 73 20 6c 65 73 73 20 74  d if N is less t
33040 68 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20  han or equal to 
33050 7a 65 72 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d  zero or if a mem
33060 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20  ory.** allocate 
33070 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
33080 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
33090 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
330a0 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
330b0 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
330c0 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
330d0 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
330e0 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
330f0 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
33100 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
33110 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
33120 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
33130 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
33140 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
33150 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
33160 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
33170 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
33180 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
33190 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
331a0 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69  llocation.)^  Wi
331b0 74 68 69 6e 20 74 68 65 20 78 46 69 6e 61 6c 20  thin the xFinal 
331c0 63 61 6c 6c 62 61 63 6b 2c 20 69 74 20 69 73 20  callback, it is 
331d0 63 75 73 74 6f 6d 61 72 79 20 74 6f 20 73 65 74  customary to set
331e0 0a 2a 2a 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73  .** N=0 in calls
331f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72   to sqlite3_aggr
33200 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
33210 4e 29 20 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a  N) so that no .*
33220 2a 20 70 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f  * pointless memo
33230 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f  ry allocations o
33240 63 63 75 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  ccur..**.** ^SQL
33250 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ite automaticall
33260 79 20 66 72 65 65 73 20 74 68 65 20 6d 65 6d 6f  y frees the memo
33270 72 79 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  ry allocated by 
33280 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72  .** sqlite3_aggr
33290 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
332a0 77 68 65 6e 20 74 68 65 20 61 67 67 72 65 67 61  when the aggrega
332b0 74 65 20 71 75 65 72 79 20 63 6f 6e 63 6c 75 64  te query conclud
332c0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
332d0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  rst parameter mu
332e0 73 74 20 62 65 20 61 20 63 6f 70 79 20 6f 66 20  st be a copy of 
332f0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
33300 63 6f 6e 74 65 78 74 20 7c 20 53 51 4c 20 66 75  context | SQL fu
33310 6e 63 74 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20  nction context] 
33320 74 68 61 74 20 69 73 20 74 68 65 20 66 69 72 73  that is the firs
33330 74 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74  t parameter.** t
33340 6f 20 74 68 65 20 78 53 74 65 70 20 6f 72 20 78  o the xStep or x
33350 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72  Final callback r
33360 6f 75 74 69 6e 65 20 74 68 61 74 20 69 6d 70 6c  outine that impl
33370 65 6d 65 6e 74 73 20 74 68 65 20 61 67 67 72 65  ements the aggre
33380 67 61 74 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  gate.** function
33390 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
333a0 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
333b0 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
333c0 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
333d0 68 0a 2a 2a 20 74 68 65 20 61 67 67 72 65 67 61  h.** the aggrega
333e0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
333f0 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76  is running..*/.v
33400 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 61 67 67  oid *sqlite3_agg
33410 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 73  regate_context(s
33420 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
33430 20 69 6e 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f   int nBytes);../
33440 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 55  *.** CAPI3REF: U
33450 73 65 72 20 44 61 74 61 20 46 6f 72 20 46 75 6e  ser Data For Fun
33460 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  ctions.**.** ^Th
33470 65 20 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64  e sqlite3_user_d
33480 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
33490 72 65 74 75 72 6e 73 20 61 20 63 6f 70 79 20 6f  returns a copy o
334a0 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e 74 65 72  f.** the pointer
334b0 20 74 68 61 74 20 77 61 73 20 74 68 65 20 70 55   that was the pU
334c0 73 65 72 44 61 74 61 20 70 61 72 61 6d 65 74 65  serData paramete
334d0 72 20 28 74 68 65 20 35 74 68 20 70 61 72 61 6d  r (the 5th param
334e0 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
334f0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
33500 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
33510 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
33520 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
33530 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
33540 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
33550 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
33560 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
33570 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
33580 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
33590 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
335a0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
335b0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
335c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
335d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
335e0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
335f0 64 20 2a 73 71 6c 69 74 65 33 5f 75 73 65 72 5f  d *sqlite3_user_
33600 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33610 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33620 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61 73  API3REF: Databas
33630 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72  e Connection For
33640 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a   Functions.**.**
33650 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33660 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
33670 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
33680 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a  rns a copy of.**
33690 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 6f 20   the pointer to 
336a0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
336b0 6e 6e 65 63 74 69 6f 6e 5d 20 28 74 68 65 20 31  nnection] (the 1
336c0 73 74 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  st parameter).**
336d0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
336e0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
336f0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
33700 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33710 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
33720 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
33730 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
33740 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
33750 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
33760 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71  ..*/.sqlite3 *sq
33770 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
33780 5f 68 61 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f  _handle(sqlite3_
33790 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a  context*);../*.*
337a0 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63  * CAPI3REF: Func
337b0 74 69 6f 6e 20 41 75 78 69 6c 69 61 72 79 20 44  tion Auxiliary D
337c0 61 74 61 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ata.**.** These 
337d0 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65  functions may be
337e0 20 75 73 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67   used by (non-ag
337f0 67 72 65 67 61 74 65 29 20 53 51 4c 20 66 75 6e  gregate) SQL fun
33800 63 74 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73  ctions to.** ass
33810 6f 63 69 61 74 65 20 6d 65 74 61 64 61 74 61 20  ociate metadata 
33820 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61  with argument va
33830 6c 75 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d  lues. If the sam
33840 65 20 76 61 6c 75 65 20 69 73 20 70 61 73 73 65  e value is passe
33850 64 20 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65  d to.** multiple
33860 20 69 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20   invocations of 
33870 74 68 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e  the same SQL fun
33880 63 74 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65  ction during que
33890 72 79 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e  ry execution, un
338a0 64 65 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63  der.** some circ
338b0 75 6d 73 74 61 6e 63 65 73 20 74 68 65 20 61 73  umstances the as
338c0 73 6f 63 69 61 74 65 64 20 6d 65 74 61 64 61 74  sociated metadat
338d0 61 20 6d 61 79 20 62 65 20 70 72 65 73 65 72 76  a may be preserv
338e0 65 64 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a  ed.  An example.
338f0 2a 2a 20 6f 66 20 77 68 65 72 65 20 74 68 69 73  ** of where this
33900 20 6d 69 67 68 74 20 62 65 20 75 73 65 66 75 6c   might be useful
33910 20 69 73 20 69 6e 20 61 20 72 65 67 75 6c 61 72   is in a regular
33920 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
33930 68 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  hing.** function
33940 2e 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 76  . The compiled v
33950 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 72 65  ersion of the re
33960 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
33970 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20 61   can be stored a
33980 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61 20 61 73  s.** metadata as
33990 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74 68  sociated with th
339a0 65 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67  e pattern string
339b0 2e 20 20 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c  .  .** Then as l
339c0 6f 6e 67 20 61 73 20 74 68 65 20 70 61 74 74 65  ong as the patte
339d0 72 6e 20 73 74 72 69 6e 67 20 72 65 6d 61 69 6e  rn string remain
339e0 73 20 74 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74  s the same,.** t
339f0 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75  he compiled regu
33a00 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63  lar expression c
33a10 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20  an be reused on 
33a20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f  multiple.** invo
33a30 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
33a40 61 6d 65 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a  ame function..**
33a50 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
33a60 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69  _get_auxdata() i
33a70 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33a80 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
33a90 65 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73  e metadata.** as
33aa0 73 6f 63 69 61 74 65 64 20 62 79 20 74 68 65 20  sociated by the 
33ab0 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33ac0 61 74 61 28 29 20 66 75 6e 63 74 69 6f 6e 20 77  ata() function w
33ad0 69 74 68 20 74 68 65 20 4e 74 68 20 61 72 67 75  ith the Nth argu
33ae0 6d 65 6e 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f  ment.** value to
33af0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
33b00 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
33b10 6e 2e 20 5e 49 66 20 74 68 65 72 65 20 69 73 20  n. ^If there is 
33b20 6e 6f 20 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61  no metadata.** a
33b30 73 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 74  ssociated with t
33b40 68 65 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75  he function argu
33b50 6d 65 6e 74 2c 20 74 68 69 73 20 73 71 6c 69 74  ment, this sqlit
33b60 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29  e3_get_auxdata()
33b70 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72 65   interface.** re
33b80 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69  turns a NULL poi
33b90 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
33ba0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33bb0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e  data(C,N,P,X) in
33bc0 74 65 72 66 61 63 65 20 73 61 76 65 73 20 50 20  terface saves P 
33bd0 61 73 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  as metadata for 
33be0 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
33bf0 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
33c00 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33c10 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73  function.  ^Subs
33c20 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
33c30 74 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  to sqlite3_get_a
33c40 75 78 64 61 74 61 28 43 2c 4e 29 20 72 65 74 75  uxdata(C,N) retu
33c50 72 6e 20 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f  rn P from the mo
33c60 73 74 20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c  st recent.** sql
33c70 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33c80 28 43 2c 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69  (C,N,P,X) call i
33c90 66 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  f the metadata i
33ca0 73 20 73 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72  s still valid or
33cb0 0a 2a 2a 20 4e 55 4c 4c 20 69 66 20 74 68 65 20  .** NULL if the 
33cc0 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65 65  metadata has bee
33cd0 6e 20 64 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20  n discarded..** 
33ce0 5e 41 66 74 65 72 20 65 61 63 68 20 63 61 6c 6c  ^After each call
33cf0 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
33d00 61 75 78 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29  auxdata(C,N,P,X)
33d10 20 77 68 65 72 65 20 58 20 69 73 20 6e 6f 74 20   where X is not 
33d20 4e 55 4c 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20  NULL,.** SQLite 
33d30 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20  will invoke the 
33d40 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
33d50 69 6f 6e 20 58 20 77 69 74 68 20 70 61 72 61 6d  ion X with param
33d60 65 74 65 72 20 50 20 65 78 61 63 74 6c 79 0a 2a  eter P exactly.*
33d70 2a 20 6f 6e 63 65 2c 20 77 68 65 6e 20 74 68 65  * once, when the
33d80 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 69 73   metadata is dis
33d90 63 61 72 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74  carded..** SQLit
33da0 65 20 69 73 20 66 72 65 65 20 74 6f 20 64 69 73  e is free to dis
33db0 63 61 72 64 20 74 68 65 20 6d 65 74 61 64 61 74  card the metadat
33dc0 61 20 61 74 20 61 6e 79 20 74 69 6d 65 2c 20 69  a at any time, i
33dd0 6e 63 6c 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a  ncluding: <ul>.*
33de0 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 74 68 65 20  * <li> when the 
33df0 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 66 75  corresponding fu
33e00 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72  nction parameter
33e10 20 63 68 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20   changes, or.** 
33e20 3c 6c 69 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74  <li> when [sqlit
33e30 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
33e40 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
33e50 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 66 6f  ()] is called fo
33e60 72 20 74 68 65 0a 2a 2a 20 20 20 20 20 20 53 51  r the.**      SQ
33e70 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a  L statement, or.
33e80 2a 2a 20 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c  ** <li> when sql
33e90 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33ea0 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 67  () is invoked ag
33eb0 61 69 6e 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  ain on the same 
33ec0 70 61 72 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a  parameter, or.**
33ed0 20 3c 6c 69 3e 20 64 75 72 69 6e 67 20 74 68 65   <li> during the
33ee0 20 6f 72 69 67 69 6e 61 6c 20 73 71 6c 69 74 65   original sqlite
33ef0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33f00 63 61 6c 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f  call when a memo
33f10 72 79 20 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f  ry .**      allo
33f20 63 61 74 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63  cation error occ
33f30 75 72 73 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a  urs. </ul>)^.**.
33f40 2a 2a 20 4e 6f 74 65 20 74 68 65 20 6c 61 73 74  ** Note the last
33f50 20 62 75 6c 6c 65 74 20 69 6e 20 70 61 72 74 69   bullet in parti
33f60 63 75 6c 61 72 2e 20 20 54 68 65 20 64 65 73 74  cular.  The dest
33f70 72 75 63 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20  ructor X in .** 
33f80 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
33f90 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67  ata(C,N,P,X) mig
33fa0 68 74 20 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d  ht be called imm
33fb0 65 64 69 61 74 65 6c 79 2c 20 62 65 66 6f 72 65  ediately, before
33fc0 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
33fd0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  set_auxdata() in
33fe0 74 65 72 66 61 63 65 20 65 76 65 6e 20 72 65 74  terface even ret
33ff0 75 72 6e 73 2e 20 20 48 65 6e 63 65 20 73 71 6c  urns.  Hence sql
34000 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
34010 28 29 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  ().** should be 
34020 63 61 6c 6c 65 64 20 6e 65 61 72 20 74 68 65 20  called near the 
34030 65 6e 64 20 6f 66 20 74 68 65 20 66 75 6e 63 74  end of the funct
34040 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
34050 6f 6e 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75  on and the.** fu
34060 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74  nction implement
34070 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
34080 20 6d 61 6b 65 20 61 6e 79 20 75 73 65 20 6f 66   make any use of
34090 20 50 20 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69   P after.** sqli
340a0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
340b0 29 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ) has been calle
340c0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72  d..**.** ^(In pr
340d0 61 63 74 69 63 65 2c 20 6d 65 74 61 64 61 74 61  actice, metadata
340e0 20 69 73 20 70 72 65 73 65 72 76 65 64 20 62 65   is preserved be
340f0 74 77 65 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63  tween function c
34100 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63  alls for.** func
34110 74 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tion parameters 
34120 74 68 61 74 20 61 72 65 20 63 6f 6d 70 69 6c 65  that are compile
34130 2d 74 69 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c  -time constants,
34140 20 69 6e 63 6c 75 64 69 6e 67 20 6c 69 74 65 72   including liter
34150 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64  al.** values and
34160 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 20 61 6e   [parameters] an
34170 64 20 65 78 70 72 65 73 73 69 6f 6e 73 20 63 6f  d expressions co
34180 6d 70 6f 73 65 64 20 66 72 6f 6d 20 74 68 65 20  mposed from the 
34190 73 61 6d 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  same.)^.**.** Th
341a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
341b0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
341c0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
341d0 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
341e0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73   SQL function is
341f0 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69   running..*/.voi
34200 64 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  d *sqlite3_get_a
34210 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34220 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b  ontext*, int N);
34230 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65  .void sqlite3_se
34240 74 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65  t_auxdata(sqlite
34250 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
34260 4e 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28  N, void*, void (
34270 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a  *)(void*));.../*
34280 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
34290 6e 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67  nstants Defining
342a0 20 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63   Special Destruc
342b0 74 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a  tor Behavior.**.
342c0 2a 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65  ** These are spe
342d0 63 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20  cial values for 
342e0 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74  the destructor t
342f0 68 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e  hat is passed in
34300 20 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c   as the.** final
34310 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75   argument to rou
34320 74 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69  tines like [sqli
34330 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
34340 29 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73  )].  ^If the des
34350 74 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d  tructor.** argum
34360 65 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54  ent is SQLITE_ST
34370 41 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74  ATIC, it means t
34380 68 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  hat the content 
34390 70 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74  pointer is const
343a0 61 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20  ant.** and will 
343b0 6e 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49  never change.  I
343c0 74 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  t does not need 
343d0 74 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e  to be destroyed.
343e0 20 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45    ^The.** SQLITE
343f0 5f 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65  _TRANSIENT value
34400 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
34410 63 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b  content will lik
34420 65 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a  ely change in.**
34430 20 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65   the near future
34440 20 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65   and that SQLite
34450 20 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73   should make its
34460 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70   own private cop
34470 79 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74  y of.** the cont
34480 65 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72  ent before retur
34490 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ning..**.** The 
344a0 74 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73  typedef is neces
344b0 73 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f  sary to work aro
344c0 75 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20  und problems in 
344d0 63 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63  certain.** C++ c
344e0 6f 6d 70 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70  ompilers..*/.typ
344f0 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69  edef void (*sqli
34500 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
34510 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65  ype)(void*);.#de
34520 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54  fine SQLITE_STAT
34530 49 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65  IC      ((sqlite
34540 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
34550 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  e)0).#define SQL
34560 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20  ITE_TRANSIENT   
34570 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75  ((sqlite3_destru
34580 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f  ctor_type)-1)../
34590 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
345a0 65 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c  etting The Resul
345b0 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63  t Of An SQL Func
345c0 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  tion.**.** These
345d0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
345e0 65 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20  ed by the xFunc 
345f0 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61  or xFinal callba
34600 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c  cks that.** impl
34610 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69  ement SQL functi
34620 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
34630 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c  es.  See.** [sql
34640 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34650 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c  tion()] and [sql
34660 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
34670 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72  tion16()].** for
34680 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
34690 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  rmation..**.** T
346a0 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77  hese functions w
346b0 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69  ork very much li
346c0 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65  ke the [paramete
346d0 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c  r binding] famil
346e0 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  y of.** function
346f0 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76  s used to bind v
34700 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61  alues to host pa
34710 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70  rameters in prep
34720 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e  ared statements.
34730 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65  .** Refer to the
34740 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d   [SQL parameter]
34750 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66   documentation f
34760 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
34770 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
34780 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34790 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65  sult_blob() inte
347a0 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
347b0 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e  esult from.** an
347c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
347d0 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
347e0 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f   be the BLOB who
347f0 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f  se content is po
34800 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74  inted.** to by t
34810 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
34820 74 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73  ter and which is
34830 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68   N bytes long wh
34840 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20  ere N is the.** 
34850 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e  third parameter.
34860 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34870 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62  te3_result_zerob
34880 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73  lob() interfaces
34890 20 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20   set the result 
348a0 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  of.** the applic
348b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
348c0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42  nction to be a B
348d0 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61  LOB containing a
348e0 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73  ll zero.** bytes
348f0 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20   and N bytes in 
34900 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73  size, where N is
34910 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
34920 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
34930 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
34940 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c  te3_result_doubl
34950 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  e() interface se
34960 74 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72  ts the result fr
34970 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61  om.** an applica
34980 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
34990 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c  ction to be a fl
349a0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
349b0 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ue specified.** 
349c0 62 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d  by its 2nd argum
349d0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
349e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
349f0 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
34a00 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34a10 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a  6() functions.**
34a20 20 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65   cause the imple
34a30 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74  mented SQL funct
34a40 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ion to throw an 
34a50 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53  exception..** ^S
34a60 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73  QLite uses the s
34a70 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f  tring pointed to
34a80 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70   by the.** 2nd p
34a90 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69  arameter of sqli
34aa0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34ab0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
34ac0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
34ad0 2a 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66  * as the text of
34ae0 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67   an error messag
34af0 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65  e.  ^SQLite inte
34b00 72 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72  rprets the error
34b10 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69  .** message stri
34b20 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ng from sqlite3_
34b30 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61  result_error() a
34b40 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65  s UTF-8. ^SQLite
34b50 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74  .** interprets t
34b60 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73  he string from s
34b70 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34b80 72 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31  ror16() as UTF-1
34b90 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62  6 in native.** b
34ba0 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20  yte order.  ^If 
34bb0 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
34bc0 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72  ter to sqlite3_r
34bd0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a  esult_error().**
34be0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
34bf0 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20  lt_error16() is 
34c00 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51  negative then SQ
34c10 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68  Lite takes as th
34c20 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61  e error.** messa
34c30 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74  ge all text up t
34c40 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74  hrough the first
34c50 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e   zero character.
34c60 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72  .** ^If the thir
34c70 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
34c80 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34c90 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69  ror() or.** sqli
34ca0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34cb0 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  16() is non-nega
34cc0 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65  tive then SQLite
34cd0 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79   takes that many
34ce0 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63  .** bytes (not c
34cf0 68 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20  haracters) from 
34d00 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
34d10 72 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d  r as the error m
34d20 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20  essage..** ^The 
34d30 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34d40 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74  rror() and sqlit
34d50 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
34d60 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  6().** routines 
34d70 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63  make a private c
34d80 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72  opy of the error
34d90 20 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65   message text be
34da0 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74  fore.** they ret
34db0 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65  urn.  Hence, the
34dc0 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f   calling functio
34dd0 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65  n can deallocate
34de0 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68   or.** modify th
34df0 65 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65  e text after the
34e00 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74  y return without
34e10 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73   harm..** ^The s
34e20 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34e30 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74  ror_code() funct
34e40 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20  ion changes the 
34e50 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65  error code.** re
34e60 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65  turned by SQLite
34e70 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20   as a result of 
34e80 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75  an error in a fu
34e90 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66  nction.  ^By def
34ea0 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72  ault,.** the err
34eb0 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54  or code is SQLIT
34ec0 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62  E_ERROR.  ^A sub
34ed0 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20  sequent call to 
34ee0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
34ef0 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c  rror().** or sql
34f00 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34f10 72 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65  r16() resets the
34f20 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53   error code to S
34f30 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a  QLITE_ERROR..**.
34f40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
34f50 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f  result_error_too
34f60 62 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  big() interface 
34f70 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
34f80 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
34f90 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
34fa0 61 74 20 61 20 73 74 72 69 6e 67 20 6f 72 20 42  at a string or B
34fb0 4c 4f 42 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20  LOB is too long 
34fc0 74 6f 20 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a  to represent..**
34fd0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34fe0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
34ff0 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63 65 20  mem() interface 
35000 63 61 75 73 65 73 20 53 51 4c 69 74 65 20 74 6f  causes SQLite to
35010 20 74 68 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72   throw an.** err
35020 6f 72 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  or indicating th
35030 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  at a memory allo
35040 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a  cation failed..*
35050 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
35060 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29 20 69  3_result_int() i
35070 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
35080 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
35090 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
350a0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
350b0 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
350c0 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  32-bit signed in
350d0 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
350e0 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
350f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
35100 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35110 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72 66 61  _int64() interfa
35120 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75  ce sets the retu
35130 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74  rn value.** of t
35140 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35150 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35160 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62 69 74  to be the 64-bit
35170 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 0a   signed integer.
35180 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20 69  ** value given i
35190 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d 65  n the 2nd argume
351a0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
351b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
351c0 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  ll() interface s
351d0 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
351e0 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
351f0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
35200 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
35210 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  e NULL..**.** ^T
35220 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35230 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69 74 65  t_text(), sqlite
35240 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
35250 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65  ),.** sqlite3_re
35260 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28 29 2c  sult_text16le(),
35270 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 73   and sqlite3_res
35280 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29 20 69  ult_text16be() i
35290 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73 65 74  nterfaces.** set
352a0 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
352b0 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  e of the applica
352c0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
352d0 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61  ction to be.** a
352e0 20 74 65 78 74 20 73 74 72 69 6e 67 20 77 68 69   text string whi
352f0 63 68 20 69 73 20 72 65 70 72 65 73 65 6e 74 65  ch is represente
35300 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54 46 2d  d as UTF-8, UTF-
35310 31 36 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  16 native byte o
35320 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20  rder,.** UTF-16 
35330 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f  little endian, o
35340 72 20 55 54 46 2d 31 36 20 62 69 67 20 65 6e 64  r UTF-16 big end
35350 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  ian, respectivel
35360 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61  y..** ^SQLite ta
35370 6b 65 73 20 74 68 65 20 74 65 78 74 20 72 65 73  kes the text res
35380 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61 70 70  ult from the app
35390 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a  lication from.**
353a0 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
353b0 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  er of the sqlite
353c0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69  3_result_text* i
353d0 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49  nterfaces..** ^I
353e0 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
353f0 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
35400 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
35410 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
35420 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20   negative, then 
35430 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72 65 73  SQLite takes res
35440 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20 74 68  ult text from th
35450 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  e 2nd parameter.
35460 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65 20 66  ** through the f
35470 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63  irst zero charac
35480 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ter..** ^If the 
35490 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  3rd parameter to
354a0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
354b0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
354c0 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e  aces.** is non-n
354d0 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 61 73  egative, then as
354e0 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e 6f 74   many bytes (not
354f0 20 63 68 61 72 61 63 74 65 72 73 29 20 6f 66 20   characters) of 
35500 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e  the text.** poin
35510 74 65 64 20 74 6f 20 62 79 20 74 68 65 20 32 6e  ted to by the 2n
35520 64 20 70 61 72 61 6d 65 74 65 72 20 61 72 65 20  d parameter are 
35530 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61 70 70  taken as the app
35540 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
35550 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 73  .** function res
35560 75 6c 74 2e 20 20 49 66 20 74 68 65 20 33 72 64  ult.  If the 3rd
35570 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6e 6f   parameter is no
35580 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
35590 20 69 74 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74   it.** must be t
355a0 68 65 20 62 79 74 65 20 6f 66 66 73 65 74 20 69  he byte offset i
355b0 6e 74 6f 20 74 68 65 20 73 74 72 69 6e 67 20 77  nto the string w
355c0 68 65 72 65 20 74 68 65 20 4e 55 4c 20 74 65 72  here the NUL ter
355d0 6d 69 6e 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a  minator would.**
355e0 20 61 70 70 65 61 72 20 69 66 20 74 68 65 20 73   appear if the s
355f0 74 72 69 6e 67 20 77 68 65 72 65 20 4e 55 4c 20  tring where NUL 
35600 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
35610 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
35620 72 73 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  rs occur.** in t
35630 68 65 20 73 74 72 69 6e 67 20 61 74 20 61 20 62  he string at a b
35640 79 74 65 20 6f 66 66 73 65 74 20 74 68 61 74 20  yte offset that 
35650 69 73 20 6c 65 73 73 20 74 68 61 6e 20 74 68 65  is less than the
35660 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 33 72   value of the 3r
35670 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20  d.** parameter, 
35680 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 69  then the resulti
35690 6e 67 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 63  ng string will c
356a0 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
356b0 4e 55 4c 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20  NULs and the.** 
356c0 72 65 73 75 6c 74 20 6f 66 20 65 78 70 72 65 73  result of expres
356d0 73 69 6f 6e 73 20 6f 70 65 72 61 74 69 6e 67 20  sions operating 
356e0 6f 6e 20 73 74 72 69 6e 67 73 20 77 69 74 68 20  on strings with 
356f0 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20 69 73  embedded NULs is
35700 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e   undefined..** ^
35710 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61 6d  If the 4th param
35720 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
35730 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
35740 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f   interfaces.** o
35750 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
35760 5f 62 6c 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e  _blob is a non-N
35770 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65  ULL pointer, the
35780 6e 20 53 51 4c 69 74 65 20 63 61 6c 6c 73 20 74  n SQLite calls t
35790 68 61 74 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  hat.** function 
357a0 61 73 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  as the destructo
357b0 72 20 6f 6e 20 74 68 65 20 74 65 78 74 20 6f 72  r on the text or
357c0 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 77 68 65   BLOB result whe
357d0 6e 20 69 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69  n it has.** fini
357e0 73 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20  shed using that 
357f0 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
35800 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
35810 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
35820 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
35830 65 72 66 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a  erfaces or to.**
35840 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35850 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70 65 63  blob is the spec
35860 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c  ial constant SQL
35870 49 54 45 5f 53 54 41 54 49 43 2c 20 74 68 65 6e  ITE_STATIC, then
35880 20 53 51 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d   SQLite.** assum
35890 65 73 20 74 68 61 74 20 74 68 65 20 74 65 78 74  es that the text
358a0 20 6f 72 20 42 4c 4f 42 20 72 65 73 75 6c 74 20   or BLOB result 
358b0 69 73 20 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73  is in constant s
358c0 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f  pace and does no
358d0 74 0a 2a 2a 20 63 6f 70 79 20 74 68 65 20 63 6f  t.** copy the co
358e0 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 70 61 72  ntent of the par
358f0 61 6d 65 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20  ameter nor call 
35900 61 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  a destructor on 
35910 74 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77  the content.** w
35920 68 65 6e 20 69 74 20 68 61 73 20 66 69 6e 69 73  hen it has finis
35930 68 65 64 20 75 73 69 6e 67 20 74 68 61 74 20 72  hed using that r
35940 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
35950 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
35960 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
35970 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35980 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
35990 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
359a0 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
359b0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
359c0 54 52 41 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65  TRANSIENT.** the
359d0 6e 20 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61  n SQLite makes a
359e0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 72 65 73   copy of the res
359f0 75 6c 74 20 69 6e 74 6f 20 73 70 61 63 65 20 6f  ult into space o
35a00 62 74 61 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20  btained from.** 
35a10 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
35a20 6c 6c 6f 63 28 29 5d 20 62 65 66 6f 72 65 20 69  lloc()] before i
35a30 74 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  t returns..**.**
35a40 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
35a50 73 75 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74  sult_value() int
35a60 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20  erface sets the 
35a70 72 65 73 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65  result of.** the
35a80 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35a90 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
35aa0 20 62 65 20 61 20 63 6f 70 79 20 74 68 65 0a 2a   be a copy the.*
35ab0 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
35ac0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
35ad0 6a 65 63 74 20 73 70 65 63 69 66 69 65 64 20 62  ject specified b
35ae0 79 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  y the 2nd parame
35af0 74 65 72 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71  ter.  ^The.** sq
35b00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35b10 75 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  ue() interface m
35b20 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
35b30 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  he [sqlite3_valu
35b40 65 5d 0a 2a 2a 20 73 6f 20 74 68 61 74 20 74 68  e].** so that th
35b50 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  e [sqlite3_value
35b60 5d 20 73 70 65 63 69 66 69 65 64 20 69 6e 20 74  ] specified in t
35b70 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
35b80 20 63 68 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65   change or.** be
35b90 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 61 66 74   deallocated aft
35ba0 65 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  er sqlite3_resul
35bb0 74 5f 76 61 6c 75 65 28 29 20 72 65 74 75 72 6e  t_value() return
35bc0 73 20 77 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a  s without harm..
35bd0 2a 2a 20 5e 41 20 5b 70 72 6f 74 65 63 74 65 64  ** ^A [protected
35be0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
35bf0 6f 62 6a 65 63 74 20 6d 61 79 20 61 6c 77 61 79  object may alway
35c00 73 20 62 65 20 75 73 65 64 20 77 68 65 72 65 20  s be used where 
35c10 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
35c20 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
35c30 5d 20 6f 62 6a 65 63 74 20 69 73 20 72 65 71 75  ] object is requ
35c40 69 72 65 64 2c 20 73 6f 20 65 69 74 68 65 72 0a  ired, so either.
35c50 2a 2a 20 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69  ** kind of [sqli
35c60 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35c70 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 77 69  t can be used wi
35c80 74 68 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  th this interfac
35c90 65 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73  e..**.** If thes
35ca0 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
35cb0 61 6c 6c 65 64 20 66 72 6f 6d 20 77 69 74 68 69  alled from withi
35cc0 6e 20 74 68 65 20 64 69 66 66 65 72 65 6e 74 20  n the different 
35cd0 74 68 72 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74  thread.** than t
35ce0 68 65 20 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e  he one containin
35cf0 67 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  g the applicatio
35d00 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35d10 6f 6e 20 74 68 61 74 20 72 65 63 65 69 76 65 64  on that received
35d20 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33  .** the [sqlite3
35d30 5f 63 6f 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65  _context] pointe
35d40 72 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  r, the results a
35d50 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f  re undefined..*/
35d60 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35d70 73 75 6c 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65  sult_blob(sqlite
35d80 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35d90 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
35da0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
35db0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35dc0 6c 74 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  lt_double(sqlite
35dd0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62  3_context*, doub
35de0 6c 65 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  le);.void sqlite
35df0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 73  3_result_error(s
35e00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35e10 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
35e20 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
35e30 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
35e40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35e50 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
35e60 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
35e70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74  3_result_error_t
35e80 6f 6f 62 69 67 28 73 71 6c 69 74 65 33 5f 63 6f  oobig(sqlite3_co
35e90 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
35ea0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35eb0 6f 72 5f 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33  or_nomem(sqlite3
35ec0 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64  _context*);.void
35ed0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35ee0 65 72 72 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74  error_code(sqlit
35ef0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35f00 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35f10 72 65 73 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74  result_int(sqlit
35f20 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
35f30 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35f40 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c  result_int64(sql
35f50 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73  ite3_context*, s
35f60 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76  qlite3_int64);.v
35f70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35f80 6c 74 5f 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f  lt_null(sqlite3_
35f90 63 6f 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20  context*);.void 
35fa0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35fb0 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ext(sqlite3_cont
35fc0 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  ext*, const char
35fd0 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
35fe0 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
35ff0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36000 74 31 36 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  t16(sqlite3_cont
36010 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
36020 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28  *, int, void(*)(
36030 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71  void*));.void sq
36040 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
36050 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  t16le(sqlite3_co
36060 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
36070 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29  id*, int,void(*)
36080 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
36090 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65  qlite3_result_te
360a0 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 63  xt16be(sqlite3_c
360b0 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
360c0 6f 69 64 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a  oid*, int,void(*
360d0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
360e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
360f0 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  alue(sqlite3_con
36100 74 65 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76  text*, sqlite3_v
36110 61 6c 75 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  alue*);.void sql
36120 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f  ite3_result_zero
36130 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
36140 74 65 78 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a  text*, int n);..
36150 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
36160 44 65 66 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61  Define New Colla
36170 74 69 6e 67 20 53 65 71 75 65 6e 63 65 73 0a 2a  ting Sequences.*
36180 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63  *.** ^These func
36190 74 69 6f 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76  tions add, remov
361a0 65 2c 20 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b  e, or modify a [
361b0 63 6f 6c 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63  collation] assoc
361c0 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
361d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
361e0 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66 69 65  ection] specifie
361f0 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61  d as the first a
36200 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  rgument..**.** ^
36210 54 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  The name of the 
36220 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 61 20 55  collation is a U
36230 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66  TF-8 string.** f
36240 6f 72 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  or sqlite3_creat
36250 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e  e_collation() an
36260 64 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  d sqlite3_create
36270 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a  _collation_v2().
36280 2a 2a 20 61 6e 64 20 61 20 55 54 46 2d 31 36 20  ** and a UTF-16 
36290 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
362a0 20 62 79 74 65 20 6f 72 64 65 72 20 66 6f 72 20   byte order for 
362b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
362c0 6f 6c 6c 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a  ollation16()..**
362d0 20 5e 43 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65   ^Collation name
362e0 73 20 74 68 61 74 20 63 6f 6d 70 61 72 65 20 65  s that compare e
362f0 71 75 61 6c 20 61 63 63 6f 72 64 69 6e 67 20 74  qual according t
36300 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 72 6e 69  o [sqlite3_strni
36310 63 6d 70 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f  cmp()] are.** co
36320 6e 73 69 64 65 72 65 64 20 74 6f 20 62 65 20 74  nsidered to be t
36330 68 65 20 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a  he same name..**
36340 0a 2a 2a 20 5e 28 54 68 65 20 74 68 69 72 64 20  .** ^(The third 
36350 61 72 67 75 6d 65 6e 74 20 28 65 54 65 78 74 52  argument (eTextR
36360 65 70 29 20 6d 75 73 74 20 62 65 20 6f 6e 65 20  ep) must be one 
36370 6f 66 20 74 68 65 20 63 6f 6e 73 74 61 6e 74 73  of the constants
36380 3a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  :.** <ul>.** <li
36390 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c  > [SQLITE_UTF8],
363a0 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
363b0 5f 55 54 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16LE],.** <l
363c0 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
363d0 42 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  BE],.** <li> [SQ
363e0 4c 49 54 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a  LITE_UTF16], or.
363f0 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36400 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a  UTF16_ALIGNED]..
36410 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54  ** </ul>)^.** ^T
36420 68 65 20 65 54 65 78 74 52 65 70 20 61 72 67 75  he eTextRep argu
36430 6d 65 6e 74 20 64 65 74 65 72 6d 69 6e 65 73 20  ment determines 
36440 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20  the encoding of 
36450 73 74 72 69 6e 67 73 20 70 61 73 73 65 64 0a 2a  strings passed.*
36460 2a 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  * to the collati
36470 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  ng function call
36480 62 61 63 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e  back, xCallback.
36490 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
364a0 5f 55 54 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c  _UTF16] and [SQL
364b0 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45  ITE_UTF16_ALIGNE
364c0 44 5d 20 76 61 6c 75 65 73 20 66 6f 72 20 65 54  D] values for eT
364d0 65 78 74 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20  extRep.** force 
364e0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 20 55 54  strings to be UT
364f0 46 31 36 20 77 69 74 68 20 6e 61 74 69 76 65 20  F16 with native 
36500 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
36510 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
36520 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65  6_ALIGNED] value
36530 20 66 6f 72 20 65 54 65 78 74 52 65 70 20 66 6f   for eTextRep fo
36540 72 63 65 73 20 73 74 72 69 6e 67 73 20 74 6f 20  rces strings to 
36550 62 65 67 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65  begin.** on an e
36560 76 65 6e 20 62 79 74 65 20 61 64 64 72 65 73 73  ven byte address
36570 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
36580 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 70 41  rth argument, pA
36590 72 67 2c 20 69 73 20 61 6e 20 61 70 70 6c 69 63  rg, is an applic
365a0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
365b0 65 72 20 74 68 61 74 20 69 73 20 70 61 73 73 65  er that is passe
365c0 64 0a 2a 2a 20 74 68 72 6f 75 67 68 20 61 73 20  d.** through as 
365d0 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
365e0 6e 74 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74  nt to the collat
365f0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c  ing function cal
36600 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
36610 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
36620 2c 20 78 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20  , xCallback, is 
36630 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  a pointer to the
36640 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36650 69 6f 6e 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c  ion..** ^Multipl
36660 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
36670 74 69 6f 6e 73 20 63 61 6e 20 62 65 20 72 65 67  tions can be reg
36680 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
36690 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a  e same name but.
366a0 2a 2a 20 77 69 74 68 20 64 69 66 66 65 72 65 6e  ** with differen
366b0 74 20 65 54 65 78 74 52 65 70 20 70 61 72 61 6d  t eTextRep param
366c0 65 74 65 72 73 20 61 6e 64 20 53 51 4c 69 74 65  eters and SQLite
366d0 20 77 69 6c 6c 20 75 73 65 20 77 68 69 63 68 65   will use whiche
366e0 76 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ver.** function 
366f0 72 65 71 75 69 72 65 73 20 74 68 65 20 6c 65 61  requires the lea
36700 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
36710 61 20 74 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e  a transformation
36720 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 78 43 61  ..** ^If the xCa
36730 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
36740 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
36750 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36760 69 6f 6e 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65  ion is.** delete
36770 64 2e 20 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f  d.  ^When all co
36780 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36790 73 20 68 61 76 69 6e 67 20 74 68 65 20 73 61 6d  s having the sam
367a0 65 20 6e 61 6d 65 20 61 72 65 20 64 65 6c 65 74  e name are delet
367b0 65 64 2c 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c  ed,.** that coll
367c0 61 74 69 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67  ation is no long
367d0 65 72 20 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  er usable..**.**
367e0 20 5e 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20   ^The collating 
367f0 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
36800 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74  k is invoked wit
36810 68 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  h a copy of the 
36820 70 41 72 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61  pArg .** applica
36830 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65  tion data pointe
36840 72 20 61 6e 64 20 77 69 74 68 20 74 77 6f 20 73  r and with two s
36850 74 72 69 6e 67 73 20 69 6e 20 74 68 65 20 65 6e  trings in the en
36860 63 6f 64 69 6e 67 20 73 70 65 63 69 66 69 65 64  coding specified
36870 0a 2a 2a 20 62 79 20 74 68 65 20 65 54 65 78 74  .** by the eText
36880 52 65 70 20 61 72 67 75 6d 65 6e 74 2e 20 20 54  Rep argument.  T
36890 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
368a0 63 74 69 6f 6e 20 6d 75 73 74 20 72 65 74 75 72  ction must retur
368b0 6e 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20  n an.** integer 
368c0 74 68 61 74 20 69 73 20 6e 65 67 61 74 69 76 65  that is negative
368d0 2c 20 7a 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74  , zero, or posit
368e0 69 76 65 0a 2a 2a 20 69 66 20 74 68 65 20 66 69  ive.** if the fi
368f0 72 73 74 20 73 74 72 69 6e 67 20 69 73 20 6c 65  rst string is le
36900 73 73 20 74 68 61 6e 2c 20 65 71 75 61 6c 20 74  ss than, equal t
36910 6f 2c 20 6f 72 20 67 72 65 61 74 65 72 20 74 68  o, or greater th
36920 61 6e 20 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a  an the second,.*
36930 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  * respectively. 
36940 20 41 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e   A collating fun
36950 63 74 69 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79  ction must alway
36960 73 20 72 65 74 75 72 6e 20 74 68 65 20 73 61 6d  s return the sam
36970 65 20 61 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65  e answer.** give
36980 6e 20 74 68 65 20 73 61 6d 65 20 69 6e 70 75 74  n the same input
36990 73 2e 20 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  s.  If two or mo
369a0 72 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  re collating fun
369b0 63 74 69 6f 6e 73 20 61 72 65 20 72 65 67 69 73  ctions are regis
369c0 74 65 72 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20  tered.** to the 
369d0 73 61 6d 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e  same collation n
369e0 61 6d 65 20 28 75 73 69 6e 67 20 64 69 66 66 65  ame (using diffe
369f0 72 65 6e 74 20 65 54 65 78 74 52 65 70 20 76 61  rent eTextRep va
36a00 6c 75 65 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a  lues) then all.*
36a10 2a 20 6d 75 73 74 20 67 69 76 65 20 61 6e 20 65  * must give an e
36a20 71 75 69 76 61 6c 65 6e 74 20 61 6e 73 77 65 72  quivalent answer
36a30 20 77 68 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69   when invoked wi
36a40 74 68 20 65 71 75 69 76 61 6c 65 6e 74 20 73 74  th equivalent st
36a50 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f  rings..** The co
36a60 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36a70 20 6d 75 73 74 20 6f 62 65 79 20 74 68 65 20 66   must obey the f
36a80 6f 6c 6c 6f 77 69 6e 67 20 70 72 6f 70 65 72 74  ollowing propert
36a90 69 65 73 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73  ies for all.** s
36aa0 74 72 69 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64  trings A, B, and
36ab0 20 43 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a   C:.**.** <ol>.*
36ac0 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74  * <li> If A==B t
36ad0 68 65 6e 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69  hen B==A..** <li
36ae0 3e 20 49 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d  > If A==B and B=
36af0 3d 43 20 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a  =C then A==C..**
36b00 20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20   <li> If A&lt;B 
36b10 54 48 45 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20  THEN B&gt;A..** 
36b20 3c 6c 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 61  <li> If A&lt;B a
36b30 6e 64 20 42 26 6c 74 3b 43 20 74 68 65 6e 20 41  nd B&lt;C then A
36b40 26 6c 74 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  &lt;C..** </ol>.
36b50 2a 2a 0a 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61  **.** If a colla
36b60 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 66 61  ting function fa
36b70 69 6c 73 20 61 6e 79 20 6f 66 20 74 68 65 20 61  ils any of the a
36b80 62 6f 76 65 20 63 6f 6e 73 74 72 61 69 6e 74 73  bove constraints
36b90 20 61 6e 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c   and that.** col
36ba0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
36bb0 69 73 20 20 72 65 67 69 73 74 65 72 65 64 20 61  is  registered a
36bc0 6e 64 20 75 73 65 64 2c 20 74 68 65 6e 20 74 68  nd used, then th
36bd0 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  e behavior of SQ
36be0 4c 69 74 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66  Lite.** is undef
36bf0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
36c00 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36c10 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
36c20 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74 65  orks like sqlite
36c30 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
36c40 6f 6e 28 29 0a 2a 2a 20 77 69 74 68 20 74 68 65  on().** with the
36c50 20 61 64 64 69 74 69 6f 6e 20 74 68 61 74 20 74   addition that t
36c60 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c  he xDestroy call
36c70 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
36c80 6f 6e 20 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20  on pArg when.** 
36c90 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
36ca0 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
36cb0 64 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67  d..** ^Collating
36cc0 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 64   functions are d
36cd0 65 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 79  eleted when they
36ce0 20 61 72 65 20 6f 76 65 72 72 69 64 64 65 6e 20   are overridden 
36cf0 62 79 20 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c  by later.** call
36d00 73 20 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69  s to the collati
36d10 6f 6e 20 63 72 65 61 74 69 6f 6e 20 66 75 6e 63  on creation func
36d20 74 69 6f 6e 73 20 6f 72 20 77 68 65 6e 20 74 68  tions or when th
36d30 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
36d40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c  onnection] is cl
36d50 6f 73 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  osed using [sqli
36d60 74 65 33 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a  te3_close()]..**
36d70 0a 2a 2a 20 5e 54 68 65 20 78 44 65 73 74 72 6f  .** ^The xDestro
36d80 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75  y callback is <u
36d90 3e 6e 6f 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20  >not</u> called 
36da0 69 66 20 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74  if the .** sqlit
36db0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36dc0 69 6f 6e 5f 76 32 28 29 20 66 75 6e 63 74 69 6f  ion_v2() functio
36dd0 6e 20 66 61 69 6c 73 2e 20 20 41 70 70 6c 69 63  n fails.  Applic
36de0 61 74 69 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f  ations that invo
36df0 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  ke.** sqlite3_cr
36e00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36e10 32 28 29 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e  2() with a non-N
36e20 55 4c 4c 20 78 44 65 73 74 72 6f 79 20 61 72 67  ULL xDestroy arg
36e30 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a  ument should .**
36e40 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
36e50 6e 20 63 6f 64 65 20 61 6e 64 20 64 69 73 70 6f  n code and dispo
36e60 73 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  se of the applic
36e70 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
36e80 65 72 0a 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73  er.** themselves
36e90 20 72 61 74 68 65 72 20 74 68 61 6e 20 65 78 70   rather than exp
36ea0 65 63 74 69 6e 67 20 53 51 4c 69 74 65 20 74 6f  ecting SQLite to
36eb0 20 64 65 61 6c 20 77 69 74 68 20 69 74 20 66 6f   deal with it fo
36ec0 72 20 74 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20  r them..** This 
36ed0 69 73 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  is different fro
36ee0 6d 20 65 76 65 72 79 20 6f 74 68 65 72 20 53 51  m every other SQ
36ef0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
36f00 20 54 68 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e   The inconsisten
36f10 63 79 20 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74  cy .** is unfort
36f20 75 6e 61 74 65 20 62 75 74 20 63 61 6e 6e 6f 74  unate but cannot
36f30 20 62 65 20 63 68 61 6e 67 65 64 20 77 69 74 68   be changed with
36f40 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 62 61 63  out breaking bac
36f50 6b 77 61 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61  kwards .** compa
36f60 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20  tibility..**.** 
36f70 53 65 65 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69  See also:  [sqli
36f80 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
36f90 65 64 65 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c  eded()] and [sql
36fa0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
36fb0 65 65 64 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69  eeded16()]..*/.i
36fc0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36fd0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73  e_collation(.  s
36fe0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
36ff0 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a  t char *zName, .
37000 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
37010 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
37020 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
37030 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37040 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
37050 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  void*).);.int sq
37060 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37070 6c 61 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  lation_v2(.  sql
37080 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20  ite3*, .  const 
37090 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20  char *zName, .  
370a0 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20  int eTextRep, . 
370b0 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69   void *pArg,.  i
370c0 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f  nt(*xCompare)(vo
370d0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
370e0 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f  id*,int,const vo
370f0 69 64 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44  id*),.  void(*xD
37100 65 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29  estroy)(void*).)
37110 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
37120 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
37130 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37140 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61   const void *zNa
37150 6d 65 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52  me,.  int eTextR
37160 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
37170 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
37180 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
37190 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
371a0 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f  nst void*).);../
371b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
371c0 6f 6c 6c 61 74 69 6f 6e 20 4e 65 65 64 65 64 20  ollation Needed 
371d0 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20  Callbacks.**.** 
371e0 5e 54 6f 20 61 76 6f 69 64 20 68 61 76 69 6e 67  ^To avoid having
371f0 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 6c 6c   to register all
37200 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65   collation seque
37210 6e 63 65 73 20 62 65 66 6f 72 65 20 61 20 64 61  nces before a da
37220 74 61 62 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65  tabase.** can be
37230 20 75 73 65 64 2c 20 61 20 73 69 6e 67 6c 65 20   used, a single 
37240 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
37250 6e 20 6d 61 79 20 62 65 20 72 65 67 69 73 74 65  n may be registe
37260 72 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  red with the.** 
37270 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
37280 74 69 6f 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f  tion] to be invo
37290 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 6e 20  ked whenever an 
372a0 75 6e 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74  undefined collat
372b0 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20  ion.** sequence 
372c0 69 73 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  is required..**.
372d0 2a 2a 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74  ** ^If the funct
372e0 69 6f 6e 20 69 73 20 72 65 67 69 73 74 65 72 65  ion is registere
372f0 64 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  d using the sqli
37300 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
37310 65 64 65 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74  eded() API,.** t
37320 68 65 6e 20 69 74 20 69 73 20 70 61 73 73 65 64  hen it is passed
37330 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e   the names of un
37340 64 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f  defined collatio
37350 6e 20 73 65 71 75 65 6e 63 65 73 20 61 73 20 73  n sequences as s
37360 74 72 69 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65  trings.** encode
37370 64 20 69 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20  d in UTF-8. ^If 
37380 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f  sqlite3_collatio
37390 6e 5f 6e 65 65 64 65 64 31 36 28 29 20 69 73 20  n_needed16() is 
373a0 75 73 65 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d  used,.** the nam
373b0 65 73 20 61 72 65 20 70 61 73 73 65 64 20 61 73  es are passed as
373c0 20 55 54 46 2d 31 36 20 69 6e 20 6d 61 63 68 69   UTF-16 in machi
373d0 6e 65 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f  ne native byte o
373e0 72 64 65 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c  rder..** ^A call
373f0 20 74 6f 20 65 69 74 68 65 72 20 66 75 6e 63 74   to either funct
37400 69 6f 6e 20 72 65 70 6c 61 63 65 73 20 74 68 65  ion replaces the
37410 20 65 78 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74   existing collat
37420 69 6f 6e 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62  ion-needed callb
37430 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65  ack..**.** ^(Whe
37440 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  n the callback i
37450 73 20 69 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66  s invoked, the f
37460 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 70 61  irst argument pa
37470 73 73 65 64 20 69 73 20 61 20 63 6f 70 79 0a 2a  ssed is a copy.*
37480 2a 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64 20  * of the second 
37490 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
374a0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
374b0 65 64 65 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c  eded() or.** sql
374c0 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
374d0 65 65 64 65 64 31 36 28 29 2e 20 20 54 68 65 20  eeded16().  The 
374e0 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
374f0 69 73 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  is the database.
37500 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  ** connection.  
37510 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
37520 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
37530 4c 49 54 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c  LITE_UTF8], [SQL
37540 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a  ITE_UTF16BE],.**
37550 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54 46 31   or [SQLITE_UTF1
37560 36 4c 45 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67  6LE], indicating
37570 20 74 68 65 20 6d 6f 73 74 20 64 65 73 69 72 61   the most desira
37580 62 6c 65 20 66 6f 72 6d 20 6f 66 20 74 68 65 20  ble form of the 
37590 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
375a0 75 65 6e 63 65 20 66 75 6e 63 74 69 6f 6e 20 72  uence function r
375b0 65 71 75 69 72 65 64 2e 20 20 54 68 65 20 66 6f  equired.  The fo
375c0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
375d0 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
375e0 65 0a 2a 2a 20 72 65 71 75 69 72 65 64 20 63 6f  e.** required co
375f0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
37600 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61  .)^.**.** The ca
37610 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
37620 73 68 6f 75 6c 64 20 72 65 67 69 73 74 65 72 20  should register 
37630 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 6c  the desired coll
37640 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  ation using.** [
37650 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
37660 6f 6c 6c 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71  ollation()], [sq
37670 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
37680 6c 61 74 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a  lation16()], or.
37690 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ** [sqlite3_crea
376a0 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
376b0 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
376c0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
376d0 64 65 64 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c  ded(.  sqlite3*,
376e0 20 0a 20 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f   .  void*, .  vo
376f0 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69  id(*)(void*,sqli
37700 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74 52 65  te3*,int eTextRe
37710 70 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29  p,const char*).)
37720 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
37730 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
37740 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
37750 20 76 6f 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a   void*,.  void(*
37760 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
37770 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
37780 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23  nst void*).);..#
37790 69 66 64 65 66 20 53 51 4c 49 54 45 5f 48 41 53  ifdef SQLITE_HAS
377a0 5f 43 4f 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65  _CODEC./*.** Spe
377b0 63 69 66 79 20 74 68 65 20 6b 65 79 20 66 6f 72  cify the key for
377c0 20 61 6e 20 65 6e 63 72 79 70 74 65 64 20 64 61   an encrypted da
377d0 74 61 62 61 73 65 2e 20 20 54 68 69 73 20 72 6f  tabase.  This ro
377e0 75 74 69 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a  utine should be.
377f0 2a 2a 20 63 61 6c 6c 65 64 20 72 69 67 68 74 20  ** called right 
37800 61 66 74 65 72 20 73 71 6c 69 74 65 33 5f 6f 70  after sqlite3_op
37810 65 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  en()..**.** The 
37820 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  code to implemen
37830 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e 6f  t this API is no
37840 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20 74  t available in t
37850 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61 73  he public releas
37860 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a  e.** of SQLite..
37870 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b  */.int sqlite3_k
37880 65 79 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  ey(.  sqlite3 *d
37890 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  b,              
378a0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
378b0 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a   to be rekeyed *
378c0 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
378d0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
378e0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
378f0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
37900 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
37910 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37920 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37930 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37940 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
37950 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
37960 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
37970 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
37980 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
37990 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
379a0 20 20 20 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f     /* The key */
379b0 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67  .);../*.** Chang
379c0 65 20 74 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20  e the key on an 
379d0 6f 70 65 6e 20 64 61 74 61 62 61 73 65 2e 20 20  open database.  
379e0 49 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  If the current d
379f0 61 74 61 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a  atabase is not.*
37a00 2a 20 65 6e 63 72 79 70 74 65 64 2c 20 74 68 69  * encrypted, thi
37a10 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65  s routine will e
37a20 6e 63 72 79 70 74 20 69 74 2e 20 20 49 66 20 70  ncrypt it.  If p
37a30 4e 65 77 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d  New==0 or nNew==
37a40 30 2c 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  0, the.** databa
37a50 73 65 20 69 73 20 64 65 63 72 79 70 74 65 64 2e  se is decrypted.
37a60 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
37a70 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
37a80 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
37a90 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
37aa0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
37ab0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
37ac0 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65 79 28  t sqlite3_rekey(
37ad0 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37ae0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37af0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37b00 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37b10 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37b20 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37b30 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20 2a  /* The new key *
37b40 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
37b50 5f 72 65 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c  _rekey_v2(.  sql
37b60 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
37b70 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
37b80 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65  atabase to be re
37b90 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74  keyed */.  const
37ba0 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20   char *zDbName, 
37bb0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d            /* Nam
37bc0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
37bd0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
37be0 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
37bf0 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
37c00 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
37c10 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
37c20 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
37c30 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
37c40 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
37c50 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
37c60 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
37c70 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
37c80 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
37c90 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
37ca0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37cb0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
37cc0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
37cd0 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
37ce0 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
37cf0 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
37d00 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
37d10 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
37d20 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
37d30 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
37d40 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
37d50 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
37d60 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
37d70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
37d80 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
37d90 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
37da0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
37db0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
37dc0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
37dd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37de0 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
37df0 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
37e00 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
37e10 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
37e20 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
37e30 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
37e40 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
37e50 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
37e60 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
37e70 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
37e80 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
37e90 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
37ea0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
37eb0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
37ec0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
37ed0 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
37ee0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
37ef0 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
37f00 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
37f10 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
37f20 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
37f30 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
37f40 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
37f50 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
37f60 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
37f70 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
37f80 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
37f90 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
37fa0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
37fb0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
37fc0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
37fd0 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
37fe0 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
37ff0 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
38000 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
38010 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
38020 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
38030 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
38040 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
38050 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
38060 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
38070 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
38080 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
38090 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
380a0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
380b0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
380c0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
380d0 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
380e0 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
380f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
38100 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
38110 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
38120 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
38130 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
38140 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
38150 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
38160 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
38170 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
38180 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
38190 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
381a0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
381b0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
381c0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
381d0 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
381e0 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
381f0 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
38200 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
38210 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
38220 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
38230 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
38240 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
38250 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
38260 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
38270 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
38280 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
38290 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
382a0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
382b0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
382c0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
382d0 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
382e0 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
382f0 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
38300 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
38310 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
38320 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
38330 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
38340 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
38350 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
38360 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
38370 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
38380 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
38390 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
383a0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
383b0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
383c0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
383d0 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
383e0 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
383f0 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
38400 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
38410 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
38420 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
38430 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
38440 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
38450 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
38460 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
38470 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
38480 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
38490 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
384a0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
384b0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
384c0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
384d0 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
384e0 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
384f0 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
38500 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
38510 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
38520 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
38530 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
38540 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
38550 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
38560 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
38570 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
38580 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
38590 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
385a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
385b0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
385c0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
385d0 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
385e0 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
385f0 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
38600 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
38610 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
38620 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
38630 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
38640 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
38650 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
38660 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
38670 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
38680 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2a  d be avoided..**
38690 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
386a0 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 75  indows Runtime u
386b0 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 74  sers:</b>  The t
386c0 65 6d 70 6f 72 61 72 79 20 64 69 72 65 63 74 6f  emporary directo
386d0 72 79 20 6d 75 73 74 20 62 65 20 73 65 74 0a 2a  ry must be set.*
386e0 2a 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  * prior to calli
386f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ng [sqlite3_open
38700 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ] or [sqlite3_op
38710 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65 72 77 69  en_v2].  Otherwi
38720 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a 2a 20 66  se, various.** f
38730 65 61 74 75 72 65 73 20 74 68 61 74 20 72 65 71  eatures that req
38740 75 69 72 65 20 74 68 65 20 75 73 65 20 6f 66 20  uire the use of 
38750 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 20  temporary files 
38760 6d 61 79 20 66 61 69 6c 2e 20 20 48 65 72 65 20  may fail.  Here 
38770 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d 70 6c 65  is an.** example
38780 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f 20 74 68   of how to do th
38790 69 73 20 75 73 69 6e 67 20 43 2b 2b 20 77 69 74  is using C++ wit
387a0 68 20 74 68 65 20 57 69 6e 64 6f 77 73 20 52 75  h the Windows Ru
387b0 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  ntime:.**.** <bl
387c0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
387d0 2a 20 4c 50 43 57 53 54 52 20 7a 50 61 74 68 20  * LPCWSTR zPath 
387e0 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74 6f 72 61  = Windows::Stora
387f0 67 65 3a 3a 41 70 70 6c 69 63 61 74 69 6f 6e 44  ge::ApplicationD
38800 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d 3e 0a 2a  ata::Current->.*
38810 2a 20 26 6e 62 73 70 3b 20 20 20 20 20 54 65 6d  * &nbsp;     Tem
38820 70 6f 72 61 72 79 46 6f 6c 64 65 72 2d 3e 50 61