/ Hex Artifact Content
Login

Artifact c9c7328b51a94633c229b435eda8092fcd4e1ea3:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 20  atements.** and 
2c60: 75 6e 66 69 6e 69 73 68 65 64 20 73 71 6c 69 74  unfinished sqlit
2c70: 65 33 5f 62 61 63 6b 75 70 73 2c 20 74 68 65 6e  e3_backups, then
2c80: 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
2c90: 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f 6d 65 73  nnection becomes
2ca0: 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62 6c 65 20  .** an unusable 
2cb0: 22 7a 6f 6d 62 69 65 22 20 77 68 69 63 68 20 77  "zombie" which w
2cc0: 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  ill automaticall
2cd0: 79 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64  y be deallocated
2ce0: 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 6c 61 73   when the.** las
2cf0: 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  t prepared state
2d00: 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c 69 7a 65  ment is finalize
2d10: 64 20 6f 72 20 74 68 65 20 6c 61 73 74 20 73 71  d or the last sq
2d20: 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 69 73 0a  lite3_backup is.
2d30: 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20 20 54 68  ** finished.  Th
2d40: 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f  e sqlite3_close_
2d50: 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  v2() interface i
2d60: 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  s intended for u
2d70: 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f 73 74 20  se with.** host 
2d80: 6c 61 6e 67 75 61 67 65 73 20 74 68 61 74 20 61  languages that a
2d90: 72 65 20 67 61 72 62 61 67 65 20 63 6f 6c 6c 65  re garbage colle
2da0: 63 74 65 64 2c 20 61 6e 64 20 77 68 65 72 65 20  cted, and where 
2db0: 74 68 65 20 6f 72 64 65 72 20 69 6e 20 77 68 69  the order in whi
2dc0: 63 68 0a 2a 2a 20 64 65 73 74 72 75 63 74 6f 72  ch.** destructor
2dd0: 73 20 61 72 65 20 63 61 6c 6c 65 64 20 69 73 20  s are called is 
2de0: 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a 0a 2a 2a  arbitrary..**.**
2df0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68   Applications sh
2e00: 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ould [sqlite3_fi
2e10: 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69 7a  nalize | finaliz
2e20: 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61 72 65 64  e] all [prepared
2e30: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 0a 2a 2a   statements],.**
2e40: 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 63   [sqlite3_blob_c
2e50: 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d 20 61 6c  lose | close] al
2e60: 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  l [BLOB handles]
2e70: 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69 74  , and .** [sqlit
2e80: 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e 69 73 68  e3_backup_finish
2e90: 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c 6c 20 5b   | finish] all [
2ea0: 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 5d 20  sqlite3_backup] 
2eb0: 6f 62 6a 65 63 74 73 20 61 73 73 6f 63 69 61 74  objects associat
2ec0: 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
2ed0: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2ee0: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ef0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2f00: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2f10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
2f20: 32 28 29 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e  2() is called on
2f30: 20 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e   a [database con
2f40: 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 73 74  nection] that st
2f50: 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74  ill has.** outst
2f60: 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72 65 64  anding [prepared
2f70: 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b 42   statements], [B
2f80: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 61 6e  LOB handles], an
2f90: 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d/or.** [sqlite3
2fa0: 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73  _backup] objects
2fb0: 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e 73   then it returns
2fc0: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 62 75 74   [SQLITE_OK] but
2fd0: 20 74 68 65 20 64 65 61 6c 6c 6f 63 61 74 69 6f   the deallocatio
2fe0: 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75 72 63 65  n.** of resource
2ff0: 73 20 69 73 20 64 65 66 65 72 72 65 64 20 75 6e  s is deferred un
3000: 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70 61 72 65  til all [prepare
3010: 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c 20 5b  d statements], [
3020: 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 0a 2a  BLOB handles],.*
3030: 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62  * and [sqlite3_b
3040: 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74 73 20 61  ackup] objects a
3050: 72 65 20 61 6c 73 6f 20 64 65 73 74 72 6f 79 65  re also destroye
3060: 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20  d..**.** ^If an 
3070: 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74  [sqlite3] object
3080: 20 69 73 20 64 65 73 74 72 6f 79 65 64 20 77 68   is destroyed wh
3090: 69 6c 65 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ile a transactio
30a0: 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a 20 74 68  n is open,.** th
30b0: 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  e transaction is
30c0: 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
30d0: 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
30e0: 2a 20 54 68 65 20 43 20 70 61 72 61 6d 65 74 65  * The C paramete
30f0: 72 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c  r to [sqlite3_cl
3100: 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b 73 71 6c  ose(C)] and [sql
3110: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 43 29  ite3_close_v2(C)
3120: 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
3130: 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f  her a NULL.** po
3140: 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c  inter or an [sql
3150: 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69  ite3] object poi
3160: 6e 74 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  nter obtained.**
3170: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f   from [sqlite3_o
3180: 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
3190: 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a  _open16()], or.*
31a0: 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  * [sqlite3_open_
31b0: 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70  v2()], and not p
31c0: 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64  reviously closed
31d0: 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  ..** ^Calling sq
31e0: 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 6f 72  lite3_close() or
31f0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76   sqlite3_close_v
3200: 32 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  2() with a NULL 
3210: 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72 67 75 6d  pointer.** argum
3220: 65 6e 74 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ent is a harmles
3230: 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69 6e 74 20  s no-op..*/.int 
3240: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 73 71  sqlite3_close(sq
3250: 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20 73 71 6c  lite3*);.int sql
3260: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 73 71  ite3_close_v2(sq
3270: 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
3280: 54 68 65 20 74 79 70 65 20 66 6f 72 20 61 20 63  The type for a c
3290: 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
32a0: 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 6c 65 67  ..** This is leg
32b0: 61 63 79 20 61 6e 64 20 64 65 70 72 65 63 61 74  acy and deprecat
32c0: 65 64 2e 20 20 49 74 20 69 73 20 69 6e 63 6c 75  ed.  It is inclu
32d0: 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69 63  ded for historic
32e0: 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  al.** compatibil
32f0: 69 74 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 64  ity and is not d
3300: 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f 0a 74 79  ocumented..*/.ty
3310: 70 65 64 65 66 20 69 6e 74 20 28 2a 73 71 6c 69  pedef int (*sqli
3320: 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29 28 76 6f  te3_callback)(vo
3330: 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 20  id*,int,char**, 
3340: 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  char**);../*.** 
3350: 43 41 50 49 33 52 45 46 3a 20 4f 6e 65 2d 53 74  CAPI3REF: One-St
3360: 65 70 20 51 75 65 72 79 20 45 78 65 63 75 74 69  ep Query Executi
3370: 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a 2a 2a 0a  on Interface.**.
3380: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 65  ** The sqlite3_e
3390: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
33a0: 69 73 20 61 20 63 6f 6e 76 65 6e 69 65 6e 63 65  is a convenience
33b0: 20 77 72 61 70 70 65 72 20 61 72 6f 75 6e 64 0a   wrapper around.
33c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ** [sqlite3_prep
33d0: 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73 71 6c 69  are_v2()], [sqli
33e0: 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 61 6e 64  te3_step()], and
33f0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
3400: 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61 74 20 61  ze()],.** that a
3410: 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c 69 63 61  llows an applica
3420: 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d 75 6c 74  tion to run mult
3430: 69 70 6c 65 20 73 74 61 74 65 6d 65 6e 74 73 20  iple statements 
3440: 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74 68 6f 75  of SQL.** withou
3450: 74 20 68 61 76 69 6e 67 20 74 6f 20 75 73 65 20  t having to use 
3460: 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f 64 65 2e  a lot of C code.
3470: 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c   .**.** ^The sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65  ite3_exec() inte
3490: 72 66 61 63 65 20 72 75 6e 73 20 7a 65 72 6f 20  rface runs zero 
34a0: 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38 20 65 6e  or more UTF-8 en
34b0: 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d 69 63 6f  coded,.** semico
34c0: 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20 53 51 4c  lon-separate SQL
34d0: 20 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73   statements pass
34e0: 65 64 20 69 6e 74 6f 20 69 74 73 20 32 6e 64 20  ed into its 2nd 
34f0: 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20 69 6e 20  argument,.** in 
3500: 74 68 65 20 63 6f 6e 74 65 78 74 20 6f 66 20 74  the context of t
3510: 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
3520: 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73 65 64 20  nection] passed 
3530: 69 6e 20 61 73 20 69 74 73 20 31 73 74 0a 2a 2a  in as its 1st.**
3540: 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20   argument.  ^If 
3550: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  the callback fun
3560: 63 74 69 6f 6e 20 6f 66 20 74 68 65 20 33 72 64  ction of the 3rd
3570: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
3580: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3590: 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e  s not NULL, then
35a0: 20 69 74 20 69 73 20 69 6e 76 6f 6b 65 64 20 66   it is invoked f
35b0: 6f 72 20 65 61 63 68 20 72 65 73 75 6c 74 20 72  or each result r
35c0: 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20 6f 75 74  ow.** coming out
35d0: 20 6f 66 20 74 68 65 20 65 76 61 6c 75 61 74 65   of the evaluate
35e0: 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
35f0: 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75  .  ^The 4th argu
3600: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  ment to.** sqlit
3610: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 65 6c  e3_exec() is rel
3620: 61 79 65 64 20 74 68 72 6f 75 67 68 20 74 6f 20  ayed through to 
3630: 74 68 65 20 31 73 74 20 61 72 67 75 6d 65 6e 74  the 1st argument
3640: 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63 61 6c 6c   of each.** call
3650: 62 61 63 6b 20 69 6e 76 6f 63 61 74 69 6f 6e 2e  back invocation.
3660: 20 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61    ^If the callba
3670: 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f 20 73 71  ck pointer to sq
3680: 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20  lite3_exec().** 
3690: 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 6e 6f  is NULL, then no
36a0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 65 76 65   callback is eve
36b0: 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64 20 72 65  r invoked and re
36c0: 73 75 6c 74 20 72 6f 77 73 20 61 72 65 0a 2a 2a  sult rows are.**
36d0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
36e0: 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  ^If an error occ
36f0: 75 72 73 20 77 68 69 6c 65 20 65 76 61 6c 75 61  urs while evalua
3700: 74 69 6e 67 20 74 68 65 20 53 51 4c 20 73 74 61  ting the SQL sta
3710: 74 65 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69  tements passed i
3720: 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65  nto.** sqlite3_e
3730: 78 65 63 28 29 2c 20 74 68 65 6e 20 65 78 65 63  xec(), then exec
3740: 75 74 69 6f 6e 20 6f 66 20 74 68 65 20 63 75 72  ution of the cur
3750: 72 65 6e 74 20 73 74 61 74 65 6d 65 6e 74 20 73  rent statement s
3760: 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73 75 62 73  tops and.** subs
3770: 65 71 75 65 6e 74 20 73 74 61 74 65 6d 65 6e 74  equent statement
3780: 73 20 61 72 65 20 73 6b 69 70 70 65 64 2e 20 20  s are skipped.  
3790: 5e 49 66 20 74 68 65 20 35 74 68 20 70 61 72 61  ^If the 5th para
37a0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
37b0: 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 6e 6f  _exec().** is no
37c0: 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61 6e 79 20  t NULL then any 
37d0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 73  error message is
37e0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
37f0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  mory obtained.**
3800: 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
3810: 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20 70 61 73  alloc()] and pas
3820: 73 65 64 20 62 61 63 6b 20 74 68 72 6f 75 67 68  sed back through
3830: 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74   the 5th paramet
3840: 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f 69 64 20  er..** To avoid 
3850: 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c 20 74 68  memory leaks, th
3860: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
3870: 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b 73 71 6c  ould invoke [sql
3880: 69 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20  ite3_free()].** 
3890: 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  on error message
38a0: 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
38b0: 64 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74  d through the 5t
38c0: 68 20 70 61 72 61 6d 65 74 65 72 20 6f 66 0a 2a  h parameter of.*
38d0: 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65  * of sqlite3_exe
38e0: 63 28 29 20 61 66 74 65 72 20 74 68 65 20 65 72  c() after the er
38f0: 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69  ror message stri
3900: 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  ng is no longer 
3910: 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 74  needed..** ^If t
3920: 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  he 5th parameter
3930: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
3940: 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61  () is not NULL a
3950: 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a 2a 20  nd no errors.** 
3960: 6f 63 63 75 72 2c 20 74 68 65 6e 20 73 71 6c 69  occur, then sqli
3970: 74 65 33 5f 65 78 65 63 28 29 20 73 65 74 73 20  te3_exec() sets 
3980: 74 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 69  the pointer in i
3990: 74 73 20 35 74 68 20 70 61 72 61 6d 65 74 65 72  ts 5th parameter
39a0: 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62 65 66 6f   to.** NULL befo
39b0: 72 65 20 72 65 74 75 72 6e 69 6e 67 2e 0a 2a 2a  re returning..**
39c0: 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71 6c 69 74  .** ^If an sqlit
39d0: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
39e0: 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
39f0: 65 72 6f 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ero, the sqlite3
3a00: 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f 75 74 69  _exec().** routi
3a10: 6e 65 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  ne returns SQLIT
3a20: 45 5f 41 42 4f 52 54 20 77 69 74 68 6f 75 74 20  E_ABORT without 
3a30: 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 63 61 6c  invoking the cal
3a40: 6c 62 61 63 6b 20 61 67 61 69 6e 20 61 6e 64 0a  lback again and.
3a50: 2a 2a 20 77 69 74 68 6f 75 74 20 72 75 6e 6e 69  ** without runni
3a60: 6e 67 20 61 6e 79 20 73 75 62 73 65 71 75 65 6e  ng any subsequen
3a70: 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  t SQL statements
3a80: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 32 6e 64  ..**.** ^The 2nd
3a90: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
3aa0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3ab0: 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
3ac0: 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62  n is the.** numb
3ad0: 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
3ae0: 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 5e 54   the result.  ^T
3af0: 68 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20  he 3rd argument 
3b00: 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 65  to the sqlite3_e
3b10: 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c 62 61 63  xec().** callbac
3b20: 6b 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  k is an array of
3b30: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
3b40: 69 6e 67 73 20 6f 62 74 61 69 6e 65 64 20 61 73  ings obtained as
3b50: 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c   if from.** [sql
3b60: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
3b70: 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20 65 61 63  ()], one for eac
3b80: 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49 66 20 61  h column.  ^If a
3b90: 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20 61 0a 2a  n element of a.*
3ba0: 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 69 73 20  * result row is 
3bb0: 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
3bc0: 72 72 65 73 70 6f 6e 64 69 6e 67 20 73 74 72 69  rresponding stri
3bd0: 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f 72 20 74  ng pointer for t
3be0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
3bf0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
3c00: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
3c10: 20 20 5e 54 68 65 20 34 74 68 20 61 72 67 75 6d    ^The 4th argum
3c20: 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 73 71  ent to the.** sq
3c30: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
3c40: 6c 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61  lback is an arra
3c50: 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
3c60: 20 73 74 72 69 6e 67 73 20 77 68 65 72 65 20 65   strings where e
3c70: 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20 72 65 70  ach.** entry rep
3c80: 72 65 73 65 6e 74 73 20 74 68 65 20 6e 61 6d 65  resents the name
3c90: 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e   of correspondin
3ca0: 67 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  g result column 
3cb0: 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  as obtained.** f
3cc0: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  rom [sqlite3_col
3cd0: 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a 2a 2a 0a  umn_name()]..**.
3ce0: 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e 64 20 70  ** ^If the 2nd p
3cf0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3d00: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 61 20  te3_exec() is a 
3d10: 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 61 20  NULL pointer, a 
3d20: 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 61 6e  pointer.** to an
3d30: 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 6f   empty string, o
3d40: 72 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  r a pointer that
3d50: 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c 79 20 77   contains only w
3d60: 68 69 74 65 73 70 61 63 65 20 61 6e 64 2f 6f 72  hitespace and/or
3d70: 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d 65 6e 74   .** SQL comment
3d80: 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51 4c 20 73  s, then no SQL s
3d90: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 65 76  tatements are ev
3da0: 61 6c 75 61 74 65 64 20 61 6e 64 20 74 68 65 20  aluated and the 
3db0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 6e  database.** is n
3dc0: 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a 2a 0a 2a  ot changed..**.*
3dd0: 2a 20 52 65 73 74 72 69 63 74 69 6f 6e 73 3a 0a  * Restrictions:.
3de0: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
3df0: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3e00: 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  on must insure t
3e10: 68 61 74 20 74 68 65 20 31 73 74 20 70 61 72 61  hat the 1st para
3e20: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3e30: 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20 20 20 20  _exec().**      
3e40: 69 73 20 61 20 76 61 6c 69 64 20 61 6e 64 20 6f  is a valid and o
3e50: 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f  pen [database co
3e60: 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 3c 6c  nnection]..** <l
3e70: 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  i> The applicati
3e80: 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63 6c 6f 73  on must not clos
3e90: 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  e the [database 
3ea0: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63  connection] spec
3eb0: 69 66 69 65 64 20 62 79 0a 2a 2a 20 20 20 20 20  ified by.**     
3ec0: 20 74 68 65 20 31 73 74 20 70 61 72 61 6d 65 74   the 1st paramet
3ed0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3ee0: 65 63 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74  ec() while sqlit
3ef0: 65 33 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e  e3_exec() is run
3f00: 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ning..** <li> Th
3f10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
3f20: 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79 20 74 68  st not modify th
3f30: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
3f40: 74 65 78 74 20 70 61 73 73 65 64 20 69 6e 74 6f  text passed into
3f50: 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 32 6e 64  .**      the 2nd
3f60: 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
3f70: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 77 68 69  lite3_exec() whi
3f80: 6c 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  le sqlite3_exec(
3f90: 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a  ) is running..**
3fa0: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ul>.*/.int sq
3fb0: 6c 69 74 65 33 5f 65 78 65 63 28 0a 20 20 73 71  lite3_exec(.  sq
3fc0: 6c 69 74 65 33 2a 2c 20 20 20 20 20 20 20 20 20  lite3*,         
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f           /* An o
3ff0: 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  pen database */.
4000: 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71    const char *sq
4010: 6c 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20  l,              
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
4030: 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
4040: 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 63  ted */.  int (*c
4050: 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69  allback)(void*,i
4060: 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61 72 2a 2a  nt,char**,char**
4070: 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  ),  /* Callback 
4080: 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
4090: 69 64 20 2a 2c 20 20 20 20 20 20 20 20 20 20 20  id *,           
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 2f 2a 20 31 73 74 20           /* 1st 
40c0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
40d0: 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61 72 20 2a  back */.  char *
40e0: 2a 65 72 72 6d 73 67 20 20 20 20 20 20 20 20 20  *errmsg         
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
4110: 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
4120: 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
4130: 33 52 45 46 3a 20 52 65 73 75 6c 74 20 43 6f 64  3REF: Result Cod
4140: 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
4150: 7b 72 65 73 75 6c 74 20 63 6f 64 65 20 64 65 66  {result code def
4160: 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20  initions}.**.** 
4170: 4d 61 6e 79 20 53 51 4c 69 74 65 20 66 75 6e 63  Many SQLite func
4180: 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 61 6e 20  tions return an 
4190: 69 6e 74 65 67 65 72 20 72 65 73 75 6c 74 20 63  integer result c
41a0: 6f 64 65 20 66 72 6f 6d 20 74 68 65 20 73 65 74  ode from the set
41b0: 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72 65 20 69   shown.** here i
41c0: 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e 64 69 63  n order to indic
41d0: 61 74 65 20 73 75 63 63 65 73 73 20 6f 72 20 66  ate success or f
41e0: 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65  ailure..**.** Ne
41f0: 77 20 65 72 72 6f 72 20 63 6f 64 65 73 20 6d 61  w error codes ma
4200: 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75  y be added in fu
4210: 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66  ture versions of
4220: 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53   SQLite..**.** S
4230: 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74 65 6e 64  ee also: [extend
4240: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 20 64  ed result code d
4250: 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a 2f 0a 23  efinitions].*/.#
4260: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f 4b  define SQLITE_OK
4270: 20 20 20 20 20 20 20 20 20 20 20 30 20 20 20 2f             0   /
4280: 2a 20 53 75 63 63 65 73 73 66 75 6c 20 72 65 73  * Successful res
4290: 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67 69 6e 6e  ult */./* beginn
42a0: 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d 63 6f 64  ing-of-error-cod
42b0: 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  es */.#define SQ
42c0: 4c 49 54 45 5f 45 52 52 4f 52 20 20 20 20 20 20  LITE_ERROR      
42d0: 20 20 31 20 20 20 2f 2a 20 53 51 4c 20 65 72 72    1   /* SQL err
42e0: 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67 20 64 61  or or missing da
42f0: 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e  tabase */.#defin
4300: 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 4e 41  e SQLITE_INTERNA
4310: 4c 20 20 20 20 20 32 20 20 20 2f 2a 20 49 6e 74  L     2   /* Int
4320: 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65 72 72 6f  ernal logic erro
4330: 72 20 69 6e 20 53 51 4c 69 74 65 20 2a 2f 0a 23  r in SQLite */.#
4340: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 50 45  define SQLITE_PE
4350: 52 4d 20 20 20 20 20 20 20 20 20 33 20 20 20 2f  RM         3   /
4360: 2a 20 41 63 63 65 73 73 20 70 65 72 6d 69 73 73  * Access permiss
4370: 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23 64  ion denied */.#d
4380: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f  efine SQLITE_ABO
4390: 52 54 20 20 20 20 20 20 20 20 34 20 20 20 2f 2a  RT        4   /*
43a0: 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   Callback routin
43b0: 65 20 72 65 71 75 65 73 74 65 64 20 61 6e 20 61  e requested an a
43c0: 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20  bort */.#define 
43d0: 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20 20 20  SQLITE_BUSY     
43e0: 20 20 20 20 35 20 20 20 2f 2a 20 54 68 65 20 64      5   /* The d
43f0: 61 74 61 62 61 73 65 20 66 69 6c 65 20 69 73 20  atabase file is 
4400: 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e  locked */.#defin
4410: 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20  e SQLITE_LOCKED 
4420: 20 20 20 20 20 20 36 20 20 20 2f 2a 20 41 20 74        6   /* A t
4430: 61 62 6c 65 20 69 6e 20 74 68 65 20 64 61 74 61  able in the data
4440: 62 61 73 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a  base is locked *
4450: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4460: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 37 20  _NOMEM        7 
4470: 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63 28 29 20    /* A malloc() 
4480: 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65 66 69 6e  failed */.#defin
4490: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
44a0: 59 20 20 20 20 20 38 20 20 20 2f 2a 20 41 74 74  Y     8   /* Att
44b0: 65 6d 70 74 20 74 6f 20 77 72 69 74 65 20 61 20  empt to write a 
44c0: 72 65 61 64 6f 6e 6c 79 20 64 61 74 61 62 61 73  readonly databas
44d0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
44e0: 49 54 45 5f 49 4e 54 45 52 52 55 50 54 20 20 20  ITE_INTERRUPT   
44f0: 20 39 20 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f   9   /* Operatio
4500: 6e 20 74 65 72 6d 69 6e 61 74 65 64 20 62 79 20  n terminated by 
4510: 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
4520: 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  t()*/.#define SQ
4530: 4c 49 54 45 5f 49 4f 45 52 52 20 20 20 20 20 20  LITE_IOERR      
4540: 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65 20 6b 69   10   /* Some ki
4550: 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f 4f 20 65  nd of disk I/O e
4560: 72 72 6f 72 20 6f 63 63 75 72 72 65 64 20 2a 2f  rror occurred */
4570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4580: 43 4f 52 52 55 50 54 20 20 20 20 20 31 31 20 20  CORRUPT     11  
4590: 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65   /* The database
45a0: 20 64 69 73 6b 20 69 6d 61 67 65 20 69 73 20 6d   disk image is m
45b0: 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23 64 65 66  alformed */.#def
45c0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  ine SQLITE_NOTFO
45d0: 55 4e 44 20 20 20 20 31 32 20 20 20 2f 2a 20 55  UND    12   /* U
45e0: 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65 20 69 6e  nknown opcode in
45f0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f   sqlite3_file_co
4600: 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64 65 66 69  ntrol() */.#defi
4610: 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c 4c 20 20  ne SQLITE_FULL  
4620: 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 49 6e        13   /* In
4630: 73 65 72 74 69 6f 6e 20 66 61 69 6c 65 64 20 62  sertion failed b
4640: 65 63 61 75 73 65 20 64 61 74 61 62 61 73 65 20  ecause database 
4650: 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64 65 66 69  is full */.#defi
4660: 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  ne SQLITE_CANTOP
4670: 45 4e 20 20 20 20 31 34 20 20 20 2f 2a 20 55 6e  EN    14   /* Un
4680: 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20 74 68 65  able to open the
4690: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 2a   database file *
46a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
46b0: 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20 31 35 20  _PROTOCOL    15 
46c0: 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 6c 6f    /* Database lo
46d0: 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65 72 72 6f  ck protocol erro
46e0: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
46f0: 49 54 45 5f 45 4d 50 54 59 20 20 20 20 20 20 20  ITE_EMPTY       
4700: 31 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  16   /* Database
4710: 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a 23 64 65   is empty */.#de
4720: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 43 48 45  fine SQLITE_SCHE
4730: 4d 41 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20  MA      17   /* 
4740: 54 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68  The database sch
4750: 65 6d 61 20 63 68 61 6e 67 65 64 20 2a 2f 0a 23  ema changed */.#
4760: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 4f  define SQLITE_TO
4770: 4f 42 49 47 20 20 20 20 20 20 31 38 20 20 20 2f  OBIG      18   /
4780: 2a 20 53 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  * String or BLOB
4790: 20 65 78 63 65 65 64 73 20 73 69 7a 65 20 6c 69   exceeds size li
47a0: 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  mit */.#define S
47b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
47c0: 20 20 31 39 20 20 20 2f 2a 20 41 62 6f 72 74 20    19   /* Abort 
47d0: 64 75 65 20 74 6f 20 63 6f 6e 73 74 72 61 69 6e  due to constrain
47e0: 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a 2f 0a 23  t violation */.#
47f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4800: 53 4d 41 54 43 48 20 20 20 20 32 30 20 20 20 2f  SMATCH    20   /
4810: 2a 20 44 61 74 61 20 74 79 70 65 20 6d 69 73 6d  * Data type mism
4820: 61 74 63 68 20 2a 2f 0a 23 64 65 66 69 6e 65 20  atch */.#define 
4830: 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 20 20 20  SQLITE_MISUSE   
4840: 20 20 20 32 31 20 20 20 2f 2a 20 4c 69 62 72 61     21   /* Libra
4850: 72 79 20 75 73 65 64 20 69 6e 63 6f 72 72 65 63  ry used incorrec
4860: 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  tly */.#define S
4870: 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20 20 20 20  QLITE_NOLFS     
4880: 20 20 32 32 20 20 20 2f 2a 20 55 73 65 73 20 4f    22   /* Uses O
4890: 53 20 66 65 61 74 75 72 65 73 20 6e 6f 74 20 73  S features not s
48a0: 75 70 70 6f 72 74 65 64 20 6f 6e 20 68 6f 73 74  upported on host
48b0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
48c0: 54 45 5f 41 55 54 48 20 20 20 20 20 20 20 20 32  TE_AUTH        2
48d0: 33 20 20 20 2f 2a 20 41 75 74 68 6f 72 69 7a 61  3   /* Authoriza
48e0: 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f 0a 23  tion denied */.#
48f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 4f  define SQLITE_FO
4900: 52 4d 41 54 20 20 20 20 20 20 32 34 20 20 20 2f  RMAT      24   /
4910: 2a 20 41 75 78 69 6c 69 61 72 79 20 64 61 74 61  * Auxiliary data
4920: 62 61 73 65 20 66 6f 72 6d 61 74 20 65 72 72 6f  base format erro
4930: 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
4940: 49 54 45 5f 52 41 4e 47 45 20 20 20 20 20 20 20  ITE_RANGE       
4950: 32 35 20 20 20 2f 2a 20 32 6e 64 20 70 61 72 61  25   /* 2nd para
4960: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
4970: 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20 72 61 6e  _bind out of ran
4980: 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ge */.#define SQ
4990: 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20 20 20 20  LITE_NOTADB     
49a0: 20 32 36 20 20 20 2f 2a 20 46 69 6c 65 20 6f 70   26   /* File op
49b0: 65 6e 65 64 20 74 68 61 74 20 69 73 20 6e 6f 74  ened that is not
49c0: 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
49d0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
49e0: 54 45 5f 4e 4f 54 49 43 45 20 20 20 20 20 20 32  TE_NOTICE      2
49f0: 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69 63 61 74  7   /* Notificat
4a00: 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c 69 74 65  ions from sqlite
4a10: 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65 66 69  3_log() */.#defi
4a20: 6e 65 20 53 51 4c 49 54 45 5f 57 41 52 4e 49 4e  ne SQLITE_WARNIN
4a30: 47 20 20 20 20 20 32 38 20 20 20 2f 2a 20 57 61  G     28   /* Wa
4a40: 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73 71 6c 69  rnings from sqli
4a50: 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64 65  te3_log() */.#de
4a60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20  fine SQLITE_ROW 
4a70: 20 20 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20          100  /* 
4a80: 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68  sqlite3_step() h
4a90: 61 73 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72  as another row r
4aa0: 65 61 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20  eady */.#define 
4ab0: 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20  SQLITE_DONE     
4ac0: 20 20 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74     101  /* sqlit
4ad0: 65 33 5f 73 74 65 70 28 29 20 68 61 73 20 66 69  e3_step() has fi
4ae0: 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
4af0: 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72   */./* end-of-er
4b00: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a  ror-codes */../*
4b10: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
4b20: 74 65 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f  tended Result Co
4b30: 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  des.** KEYWORDS:
4b40: 20 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   {extended resul
4b50: 74 20 63 6f 64 65 20 64 65 66 69 6e 69 74 69 6f  t code definitio
4b60: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20 69 74 73  ns}.**.** In its
4b70: 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75   default configu
4b80: 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74 65 20 41  ration, SQLite A
4b90: 50 49 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  PI routines retu
4ba0: 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20 69 6e 74  rn one of 30 int
4bb0: 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75 6c 74 20  eger.** [result 
4bc0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
4bd0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
4be0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
4bf0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
4c00: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4c10: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4c20: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4c30: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4c40: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4c50: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4c60: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4c70: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4c80: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4c90: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4ca0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
4cb0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
4cc0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
4cd0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
4ce0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
4cf0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
4d00: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4d10: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4d20: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4d30: 72 73 2e 20 54 68 65 73 65 20 5b 65 78 74 65 6e  rs. These [exten
4d40: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
4d50: 5d 20 61 72 65 20 65 6e 61 62 6c 65 64 20 6f 72  ] are enabled or
4d60: 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20   disabled.** on 
4d70: 61 20 70 65 72 20 64 61 74 61 62 61 73 65 20 63  a per database c
4d80: 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 20  onnection basis 
4d90: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
4da0: 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
4db0: 65 73 75 6c 74 5f 63 6f 64 65 73 28 29 5d 20 41  esult_codes()] A
4dc0: 50 49 2e 20 20 4f 72 2c 20 74 68 65 20 65 78 74  PI.  Or, the ext
4dd0: 65 6e 64 65 64 20 63 6f 64 65 20 66 6f 72 0a 2a  ended code for.*
4de0: 2a 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  * the most recen
4df0: 74 20 65 72 72 6f 72 20 63 61 6e 20 62 65 20 6f  t error can be o
4e00: 62 74 61 69 6e 65 64 20 75 73 69 6e 67 0a 2a 2a  btained using.**
4e10: 20 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64   [sqlite3_extend
4e20: 65 64 5f 65 72 72 63 6f 64 65 28 29 5d 2e 0a 2a  ed_errcode()]..*
4e30: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4e40: 5f 49 4f 45 52 52 5f 52 45 41 44 20 20 20 20 20  _IOERR_READ     
4e50: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4e60: 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c 38 29 29  _IOERR | (1<<8))
4e70: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4e80: 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45 41 44  IOERR_SHORT_READ
4e90: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4ea0: 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38 29 29 0a  IOERR | (2<<8)).
4eb0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ec0: 4f 45 52 52 5f 57 52 49 54 45 20 20 20 20 20 20  OERR_WRITE      
4ed0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4ee0: 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29 29 0a 23  OERR | (3<<8)).#
4ef0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4f00: 45 52 52 5f 46 53 59 4e 43 20 20 20 20 20 20 20  ERR_FSYNC       
4f10: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4f20: 45 52 52 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64  ERR | (4<<8)).#d
4f30: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4f40: 52 52 5f 44 49 52 5f 46 53 59 4e 43 20 20 20 20  RR_DIR_FSYNC    
4f50: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4f60: 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a 23 64 65  RR | (5<<8)).#de
4f70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f80: 52 5f 54 52 55 4e 43 41 54 45 20 20 20 20 20 20  R_TRUNCATE      
4f90: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fa0: 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23 64 65 66  R | (6<<8)).#def
4fb0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fc0: 5f 46 53 54 41 54 20 20 20 20 20 20 20 20 20 20  _FSTAT          
4fd0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4fe0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
4ff0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  ne SQLITE_IOERR_
5000: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  UNLOCK          
5010: 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20    (SQLITE_IOERR 
5020: 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (8<<8)).#defin
5030: 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 52  e SQLITE_IOERR_R
5040: 44 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  DLOCK           
5050: 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c   (SQLITE_IOERR |
5060: 20 28 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (9<<8)).#define
5070: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
5080: 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20 20  LETE            
5090: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50a0: 28 31 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (10<<8)).#define
50b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c   SQLITE_IOERR_BL
50c0: 4f 43 4b 45 44 20 20 20 20 20 20 20 20 20 20 20  OCKED           
50d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
50e0: 28 31 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (11<<8)).#define
50f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4e 4f   SQLITE_IOERR_NO
5100: 4d 45 4d 20 20 20 20 20 20 20 20 20 20 20 20 20  MEM             
5110: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5120: 28 31 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (12<<8)).#define
5130: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 41 43   SQLITE_IOERR_AC
5140: 43 45 53 53 20 20 20 20 20 20 20 20 20 20 20 20  CESS            
5150: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5160: 28 31 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (13<<8)).#define
5170: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 48   SQLITE_IOERR_CH
5180: 45 43 4b 52 45 53 45 52 56 45 44 4c 4f 43 4b 20  ECKRESERVEDLOCK 
5190: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51a0: 28 31 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (14<<8)).#define
51b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4c 4f   SQLITE_IOERR_LO
51c0: 43 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CK              
51d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
51e0: 28 31 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (15<<8)).#define
51f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4c   SQLITE_IOERR_CL
5200: 4f 53 45 20 20 20 20 20 20 20 20 20 20 20 20 20  OSE             
5210: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5220: 28 31 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (16<<8)).#define
5230: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 49   SQLITE_IOERR_DI
5240: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
5250: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5260: 28 31 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (17<<8)).#define
5270: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5280: 4d 4f 50 45 4e 20 20 20 20 20 20 20 20 20 20 20  MOPEN           
5290: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52a0: 28 31 38 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (18<<8)).#define
52b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
52c0: 4d 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  MSIZE           
52d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
52e0: 28 31 39 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (19<<8)).#define
52f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5300: 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  MLOCK           
5310: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5320: 28 32 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (20<<8)).#define
5330: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48   SQLITE_IOERR_SH
5340: 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20 20  MMAP            
5350: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5360: 28 32 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (21<<8)).#define
5370: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 45   SQLITE_IOERR_SE
5380: 45 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  EK              
5390: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53a0: 28 32 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (22<<8)).#define
53b0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 44 45   SQLITE_IOERR_DE
53c0: 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20 20 20 20  LETE_NOENT      
53d0: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
53e0: 28 32 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (23<<8)).#define
53f0: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 4d 4d   SQLITE_IOERR_MM
5400: 41 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  AP              
5410: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5420: 28 32 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (24<<8)).#define
5430: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 47 45   SQLITE_IOERR_GE
5440: 54 54 45 4d 50 50 41 54 48 20 20 20 20 20 20 20  TTEMPPATH       
5450: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
5460: 28 32 35 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (25<<8)).#define
5470: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 43 4f   SQLITE_IOERR_CO
5480: 4e 56 50 41 54 48 20 20 20 20 20 20 20 20 20 20  NVPATH          
5490: 28 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20  (SQLITE_IOERR | 
54a0: 28 32 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65  (26<<8)).#define
54b0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 5f 53   SQLITE_LOCKED_S
54c0: 48 41 52 45 44 43 41 43 48 45 20 20 20 20 20 20  HAREDCACHE      
54d0: 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45 44 20 7c  (SQLITE_LOCKED |
54e0: 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e    (1<<8)).#defin
54f0: 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 52 45  e SQLITE_BUSY_RE
5500: 43 4f 56 45 52 59 20 20 20 20 20 20 20 20 20 20  COVERY          
5510: 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20 20   (SQLITE_BUSY   
5520: 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69  |  (1<<8)).#defi
5530: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 5f 53  ne SQLITE_BUSY_S
5540: 4e 41 50 53 48 4f 54 20 20 20 20 20 20 20 20 20  NAPSHOT         
5550: 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59 20 20    (SQLITE_BUSY  
5560: 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23 64 65 66   |  (2<<8)).#def
5570: 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f  ine SQLITE_CANTO
5580: 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20 20 20  PEN_NOTEMPDIR   
5590: 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e 54 4f     (SQLITE_CANTO
55a0: 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a 23 64  PEN | (1<<8)).#d
55b0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
55c0: 54 4f 50 45 4e 5f 49 53 44 49 52 20 20 20 20 20  TOPEN_ISDIR     
55d0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
55e0: 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38 29 29 0a  TOPEN | (2<<8)).
55f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5600: 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50 41 54 48  ANTOPEN_FULLPATH
5610: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5620: 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c 3c 38 29  ANTOPEN | (3<<8)
5630: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
5640: 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e 56 50 41  _CANTOPEN_CONVPA
5650: 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  TH       (SQLITE
5660: 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 34 3c 3c  _CANTOPEN | (4<<
5670: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5680: 54 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20  TE_CORRUPT_VTAB 
5690: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
56a0: 54 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c  TE_CORRUPT | (1<
56b0: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
56c0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43  ITE_READONLY_REC
56d0: 4f 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c  OVERY       (SQL
56e0: 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28  ITE_READONLY | (
56f0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5700: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43  QLITE_READONLY_C
5710: 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53  ANTLOCK       (S
5720: 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c  QLITE_READONLY |
5730: 20 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65   (2<<8)).#define
5740: 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59   SQLITE_READONLY
5750: 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20 20  _ROLLBACK       
5760: 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59  (SQLITE_READONLY
5770: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
5780: 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e  ne SQLITE_READON
5790: 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20 20 20 20  LY_DBMOVED      
57a0: 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e    (SQLITE_READON
57b0: 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65  LY | (4<<8)).#de
57c0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 42 4f 52  fine SQLITE_ABOR
57d0: 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20 20 20  T_ROLLBACK      
57e0: 20 20 20 20 28 53 51 4c 49 54 45 5f 41 42 4f 52      (SQLITE_ABOR
57f0: 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  T | (2<<8)).#def
5800: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5810: 52 41 49 4e 54 5f 43 48 45 43 4b 20 20 20 20 20  RAINT_CHECK     
5820: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5830: 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38 29 29 0a  RAINT | (1<<8)).
5840: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5850: 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d 4d 49 54  ONSTRAINT_COMMIT
5860: 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54 45 5f 43  HOOK   (SQLITE_C
5870: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 32 3c 3c  ONSTRAINT | (2<<
5880: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5890: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 46 4f  TE_CONSTRAINT_FO
58a0: 52 45 49 47 4e 4b 45 59 20 20 20 28 53 51 4c 49  REIGNKEY   (SQLI
58b0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
58c0: 28 33 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (3<<8)).#define 
58d0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
58e0: 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20 20 20 28  T_FUNCTION     (
58f0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5900: 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23 64 65 66  T | (4<<8)).#def
5910: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5920: 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c 20 20 20  RAINT_NOTNULL   
5930: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5940: 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38 29 29 0a  RAINT | (5<<8)).
5950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5960: 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49 4d 41 52  ONSTRAINT_PRIMAR
5970: 59 4b 45 59 20 20 20 28 53 51 4c 49 54 45 5f 43  YKEY   (SQLITE_C
5980: 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28 36 3c 3c  ONSTRAINT | (6<<
5990: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
59a0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 54 52  TE_CONSTRAINT_TR
59b0: 49 47 47 45 52 20 20 20 20 20 20 28 53 51 4c 49  IGGER      (SQLI
59c0: 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20  TE_CONSTRAINT | 
59d0: 28 37 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (7<<8)).#define 
59e0: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
59f0: 54 5f 55 4e 49 51 55 45 20 20 20 20 20 20 20 28  T_UNIQUE       (
5a00: 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e  SQLITE_CONSTRAIN
5a10: 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65 66  T | (8<<8)).#def
5a20: 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54  ine SQLITE_CONST
5a30: 52 41 49 4e 54 5f 56 54 41 42 20 20 20 20 20 20  RAINT_VTAB      
5a40: 20 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54     (SQLITE_CONST
5a50: 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38 29 29 0a  RAINT | (9<<8)).
5a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5a70: 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57 49 44 20  ONSTRAINT_ROWID 
5a80: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5a90: 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31 30 3c 3c  ONSTRAINT |(10<<
5aa0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5ab0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5ac0: 52 5f 57 41 4c 20 20 20 20 20 20 28 53 51 4c 49  R_WAL      (SQLI
5ad0: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 31 3c 3c  TE_NOTICE | (1<<
5ae0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5af0: 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43 4f 56 45  TE_NOTICE_RECOVE
5b00: 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53 51 4c 49  R_ROLLBACK (SQLI
5b10: 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28 32 3c 3c  TE_NOTICE | (2<<
5b20: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
5b30: 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55 54 4f 49  TE_WARNING_AUTOI
5b40: 4e 44 45 58 20 20 20 20 20 20 20 28 53 51 4c 49  NDEX       (SQLI
5b50: 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20 28 31 3c  TE_WARNING | (1<
5b60: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
5b70: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
5b80: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5b90: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5ba0: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5bb0: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5bc0: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5bd0: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5be0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5bf0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5c00: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5c10: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5c20: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
5c30: 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  pen] method..*/.
5c40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5c50: 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20 20  PEN_READONLY    
5c60: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31 20       0x00000001 
5c70: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5c80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ca0: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20 20  PEN_READWRITE   
5cb0: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32 20       0x00000002 
5cc0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5cd0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5ce0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5cf0: 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20 20  PEN_CREATE      
5d00: 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34 20       0x00000004 
5d10: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5d20: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5d30: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5d40: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
5d50: 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38 20  E    0x00000008 
5d60: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5d70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5d80: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20 20  PEN_EXCLUSIVE   
5d90: 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30 20       0x00000010 
5da0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5db0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5dc0: 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20 20  PEN_AUTOPROXY   
5dd0: 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30 20       0x00000020 
5de0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5df0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e00: 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20 20  PEN_URI         
5e10: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 20       0x00000040 
5e20: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e30: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5e50: 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20 20 20 20  PEN_MEMORY      
5e60: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 20       0x00000080 
5e70: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
5e80: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
5e90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ea0: 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20 20  PEN_MAIN_DB     
5eb0: 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30 20       0x00000100 
5ec0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5ed0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5ee0: 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20 20  PEN_TEMP_DB     
5ef0: 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30 20       0x00000200 
5f00: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f10: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f20: 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42  PEN_TRANSIENT_DB
5f30: 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30 20       0x00000400 
5f40: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5f60: 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c  PEN_MAIN_JOURNAL
5f70: 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30 20       0x00000800 
5f80: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5f90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fa0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
5fb0: 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30 20       0x00001000 
5fc0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
5fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
5fe0: 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20 20  PEN_SUBJOURNAL  
5ff0: 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30 20       0x00002000 
6000: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6010: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6020: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
6030: 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30 20  AL   0x00004000 
6040: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
6050: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6060: 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20 20  PEN_NOMUTEX     
6070: 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30 20       0x00008000 
6080: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6090: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
60a0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
60b0: 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20 20  PEN_FULLMUTEX   
60c0: 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30 20       0x00010000 
60d0: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
60e0: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
60f0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6100: 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20  PEN_SHAREDCACHE 
6110: 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30 20       0x00020000 
6120: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6130: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6140: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
6150: 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
6160: 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30 20       0x00040000 
6170: 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69 74   /* Ok for sqlit
6180: 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f 0a  e3_open_v2() */.
6190: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4f  #define SQLITE_O
61a0: 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20 20  PEN_WAL         
61b0: 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30 20       0x00080000 
61c0: 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f 0a   /* VFS only */.
61d0: 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20 20  ./* Reserved:   
61e0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
61f0: 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30 30        0x00F00000
6200: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
6210: 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61 72  REF: Device Char
6220: 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a 2a  acteristics.**.*
6230: 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61  * The xDeviceCha
6240: 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65 74  racteristics met
6250: 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  hod of the [sqli
6260: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 0a  te3_io_methods].
6270: 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  ** object return
6280: 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69  s an integer whi
6290: 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20 6f  ch is a vector o
62a0: 66 20 74 68 65 73 65 0a 2a 2a 20 62 69 74 20 76  f these.** bit v
62b0: 61 6c 75 65 73 20 65 78 70 72 65 73 73 69 6e 67  alues expressing
62c0: 20 49 2f 4f 20 63 68 61 72 61 63 74 65 72 69 73   I/O characteris
62d0: 74 69 63 73 20 6f 66 20 74 68 65 20 6d 61 73 73  tics of the mass
62e0: 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64 65 76 69   storage.** devi
62f0: 63 65 20 74 68 61 74 20 68 6f 6c 64 73 20 74 68  ce that holds th
6300: 65 20 66 69 6c 65 20 74 68 61 74 20 74 68 65 20  e file that the 
6310: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
6320: 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72 73 20 74  ods].** refers t
6330: 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53 51 4c  o..**.** The SQL
6340: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
6350: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
6360: 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65 73 20  that all writes 
6370: 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65 20 61  of.** any size a
6380: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6390: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
63a0: 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a  MICnnn values.**
63b0: 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69 74 65   mean that write
63c0: 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68 61 74  s of blocks that
63d0: 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73 20 69   are nnn bytes i
63e0: 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20 61 72  n size and.** ar
63f0: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
6400: 61 64 64 72 65 73 73 20 77 68 69 63 68 20 69 73  address which is
6410: 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75 6c 74   an integer mult
6420: 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61  iple of.** nnn a
6430: 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68 65 20  re atomic.  The 
6440: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
6450: 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65 20 6d  E_APPEND value m
6460: 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77 68 65  eans.** that whe
6470: 6e 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  n data is append
6480: 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20 74 68  ed to a file, th
6490: 65 20 64 61 74 61 20 69 73 20 61 70 70 65 6e 64  e data is append
64a0: 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68 65 6e  ed.** first then
64b0: 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65   the size of the
64c0: 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e 64 65   file is extende
64d0: 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f 74 68  d, never the oth
64e0: 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75 6e 64  er.** way around
64f0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
6500: 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 70  CAP_SEQUENTIAL p
6510: 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68  roperty means th
6520: 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f  at.** informatio
6530: 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74 6f 20  n is written to 
6540: 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61 6d 65  disk in the same
6550: 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c 73 0a   order as calls.
6560: 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29 2e 20  ** to xWrite(). 
6570: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
6580: 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52  P_POWERSAFE_OVER
6590: 57 52 49 54 45 20 70 72 6f 70 65 72 74 79 20 6d  WRITE property m
65a0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 61 66 74  eans that.** aft
65b0: 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c 6c 6f 77  er reboot follow
65c0: 69 6e 67 20 61 20 63 72 61 73 68 20 6f 72 20 70  ing a crash or p
65d0: 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68 65 20 6f  ower loss, the o
65e0: 6e 6c 79 20 62 79 74 65 73 20 69 6e 20 61 0a 2a  nly bytes in a.*
65f0: 2a 20 66 69 6c 65 20 74 68 61 74 20 77 65 72 65  * file that were
6600: 20 77 72 69 74 74 65 6e 20 61 74 20 74 68 65 20   written at the 
6610: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c 65 76 65  application leve
6620: 6c 20 6d 69 67 68 74 20 68 61 76 65 20 63 68 61  l might have cha
6630: 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74 68 61 74  nged.** and that
6640: 20 61 64 6a 61 63 65 6e 74 20 62 79 74 65 73 2c   adjacent bytes,
6650: 20 65 76 65 6e 20 62 79 74 65 73 20 77 69 74 68   even bytes with
6660: 69 6e 20 74 68 65 20 73 61 6d 65 20 73 65 63 74  in the same sect
6670: 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61 72 61 6e  or are.** guaran
6680: 74 65 65 64 20 74 6f 20 62 65 20 75 6e 63 68 61  teed to be uncha
6690: 6e 67 65 64 2e 20 20 54 68 65 20 53 51 4c 49 54  nged.  The SQLIT
66a0: 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41  E_IOCAP_UNDELETA
66b0: 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 0a 2a 2a  BLE_WHEN_OPEN.**
66c0: 20 66 6c 61 67 20 69 6e 64 69 63 61 74 65 20 74   flag indicate t
66d0: 68 61 74 20 61 20 66 69 6c 65 20 63 61 6e 6e 6f  hat a file canno
66e0: 74 20 62 65 20 64 65 6c 65 74 65 64 20 77 68 65  t be deleted whe
66f0: 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a 2a 2a 20  n open.  The.** 
6700: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d  SQLITE_IOCAP_IMM
6710: 55 54 41 42 4c 45 20 66 6c 61 67 20 69 6e 64 69  UTABLE flag indi
6720: 63 61 74 65 73 20 74 68 61 74 20 74 68 65 20 66  cates that the f
6730: 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20 72 65 61  ile is on.** rea
6740: 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20 61 6e 64  d-only media and
6750: 20 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67   cannot be chang
6760: 65 64 20 65 76 65 6e 20 62 79 20 70 72 6f 63 65  ed even by proce
6770: 73 73 65 73 20 77 69 74 68 0a 2a 2a 20 65 6c 65  sses with.** ele
6780: 76 61 74 65 64 20 70 72 69 76 69 6c 65 67 65 73  vated privileges
6790: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
67a0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
67b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
67c0: 20 30 78 30 30 30 30 30 30 30 31 0a 23 64 65 66   0x00000001.#def
67d0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
67e0: 5f 41 54 4f 4d 49 43 35 31 32 20 20 20 20 20 20  _ATOMIC512      
67f0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
6800: 30 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  02.#define SQLIT
6810: 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 4b  E_IOCAP_ATOMIC1K
6820: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30                 0
6830: 78 30 30 30 30 30 30 30 34 0a 23 64 65 66 69 6e  x00000004.#defin
6840: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
6850: 54 4f 4d 49 43 32 4b 20 20 20 20 20 20 20 20 20  TOMIC2K         
6860: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 38        0x00000008
6870: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
6880: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34 4b 20 20  IOCAP_ATOMIC4K  
6890: 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30               0x0
68a0: 30 30 30 30 30 31 30 0a 23 64 65 66 69 6e 65 20  0000010.#define 
68b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
68c0: 4d 49 43 38 4b 20 20 20 20 20 20 20 20 20 20 20  MIC8K           
68d0: 20 20 20 20 30 78 30 30 30 30 30 30 32 30 0a 23      0x00000020.#
68e0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
68f0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 20 20 20  CAP_ATOMIC16K   
6900: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6910: 30 30 30 34 30 0a 23 64 65 66 69 6e 65 20 53 51  00040.#define SQ
6920: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6930: 43 33 32 4b 20 20 20 20 20 20 20 20 20 20 20 20  C32K            
6940: 20 20 30 78 30 30 30 30 30 30 38 30 0a 23 64 65    0x00000080.#de
6950: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6960: 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20 20 20 20  P_ATOMIC64K     
6970: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6980: 31 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  100.#define SQLI
6990: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
69a0: 50 45 4e 44 20 20 20 20 20 20 20 20 20 20 20 20  PEND            
69b0: 30 78 30 30 30 30 30 32 30 30 0a 23 64 65 66 69  0x00000200.#defi
69c0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
69d0: 53 45 51 55 45 4e 54 49 41 4c 20 20 20 20 20 20  SEQUENTIAL      
69e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 34 30         0x0000040
69f0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
6a00: 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45 54 41 42  _IOCAP_UNDELETAB
6a10: 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20 20 30 78  LE_WHEN_OPEN  0x
6a20: 30 30 30 30 30 38 30 30 0a 23 64 65 66 69 6e 65  00000800.#define
6a30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 50 4f   SQLITE_IOCAP_PO
6a40: 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49 54  WERSAFE_OVERWRIT
6a50: 45 20 20 20 20 30 78 30 30 30 30 31 30 30 30 0a  E    0x00001000.
6a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6a70: 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c 45 20 20  OCAP_IMMUTABLE  
6a80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6a90: 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a 20 43 41  002000../*.** CA
6aa0: 50 49 33 52 45 46 3a 20 46 69 6c 65 20 4c 6f 63  PI3REF: File Loc
6ab0: 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a 2a 0a 2a  king Levels.**.*
6ac0: 2a 20 53 51 4c 69 74 65 20 75 73 65 73 20 6f 6e  * SQLite uses on
6ad0: 65 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65 67  e of these integ
6ae0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6af0: 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72 67 75 6d   second.** argum
6b00: 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20 69 74 20  ent to calls it 
6b10: 6d 61 6b 65 73 20 74 6f 20 74 68 65 20 78 4c 6f  makes to the xLo
6b20: 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b  ck() and xUnlock
6b30: 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a 20 6f 66  () methods.** of
6b40: 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   an [sqlite3_io_
6b50: 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
6b60: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6b70: 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20 20 20 20  TE_LOCK_NONE    
6b80: 20 20 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20        0.#define 
6b90: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
6ba0: 45 44 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  ED        1.#def
6bb0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ine SQLITE_LOCK_
6bc0: 52 45 53 45 52 56 45 44 20 20 20 20 20 20 32 0a  RESERVED      2.
6bd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
6be0: 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20 20 20 20  OCK_PENDING     
6bf0: 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    3.#define SQLI
6c00: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
6c10: 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a 2a 20 43  E     4../*.** C
6c20: 41 50 49 33 52 45 46 3a 20 53 79 6e 63 68 72 6f  API3REF: Synchro
6c30: 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65 20 46 6c  nization Type Fl
6c40: 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 53  ags.**.** When S
6c50: 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20 74 68  QLite invokes th
6c60: 65 20 78 53 79 6e 63 28 29 20 6d 65 74 68 6f 64  e xSync() method
6c70: 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   of an.** [sqlit
6c80: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f  e3_io_methods] o
6c90: 62 6a 65 63 74 20 69 74 20 75 73 65 73 20 61 20  bject it uses a 
6ca0: 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 0a 2a  combination of.*
6cb0: 2a 20 74 68 65 73 65 20 69 6e 74 65 67 65 72 20  * these integer 
6cc0: 76 61 6c 75 65 73 20 61 73 20 74 68 65 20 73 65  values as the se
6cd0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  cond argument..*
6ce0: 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 53 51  *.** When the SQ
6cf0: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6d00: 4c 59 20 66 6c 61 67 20 69 73 20 75 73 65 64 2c  LY flag is used,
6d10: 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
6d20: 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70 65 72 61  he.** sync opera
6d30: 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65 64 73 20  tion only needs 
6d40: 74 6f 20 66 6c 75 73 68 20 64 61 74 61 20 74 6f  to flush data to
6d50: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 2e 20 20   mass storage.  
6d60: 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61  Inode.** informa
6d70: 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74 20 62 65  tion need not be
6d80: 20 66 6c 75 73 68 65 64 2e 20 49 66 20 74 68 65   flushed. If the
6d90: 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73   lower four bits
6da0: 20 6f 66 20 74 68 65 20 66 6c 61 67 0a 2a 2a 20   of the flag.** 
6db0: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6dc0: 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61 74 20 6d  C_NORMAL, that m
6dd0: 65 61 6e 73 20 74 6f 20 75 73 65 20 6e 6f 72 6d  eans to use norm
6de0: 61 6c 20 66 73 79 6e 63 28 29 20 73 65 6d 61 6e  al fsync() seman
6df0: 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74 68 65 20  tics..** If the 
6e00: 6c 6f 77 65 72 20 66 6f 75 72 20 62 69 74 73 20  lower four bits 
6e10: 65 71 75 61 6c 20 53 51 4c 49 54 45 5f 53 59 4e  equal SQLITE_SYN
6e20: 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20 6d 65 61  C_FULL, that mea
6e30: 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20 4d 61 63  ns.** to use Mac
6e40: 20 4f 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c   OS X style full
6e50: 73 79 6e 63 20 69 6e 73 74 65 61 64 20 6f 66 20  sync instead of 
6e60: 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 44  fsync()..**.** D
6e70: 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65 20 74 68  o not confuse th
6e80: 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f  e SQLITE_SYNC_NO
6e90: 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49 54 45 5f  RMAL and SQLITE_
6ea0: 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61 67 73 0a  SYNC_FULL flags.
6eb0: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 50 52 41  ** with the [PRA
6ec0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6ed0: 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b 50 52 41  =NORMAL and [PRA
6ee0: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
6ef0: 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74 69 6e 67  =FULL.** setting
6f00: 73 2e 20 20 54 68 65 20 5b 73 79 6e 63 68 72 6f  s.  The [synchro
6f10: 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20 64 65 74  nous pragma] det
6f20: 65 72 6d 69 6e 65 73 20 77 68 65 6e 20 63 61 6c  ermines when cal
6f30: 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 79  ls to the.** xSy
6f40: 6e 63 20 56 46 53 20 6d 65 74 68 6f 64 20 6f 63  nc VFS method oc
6f50: 63 75 72 20 61 6e 64 20 61 70 70 6c 69 65 73 20  cur and applies 
6f60: 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72 6f 73 73  uniformly across
6f70: 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d 73 2e 0a   all platforms..
6f80: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 53 59  ** The SQLITE_SY
6f90: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6fa0: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6fb0: 6c 61 67 73 20 64 65 74 65 72 6d 69 6e 65 20 68  lags determine h
6fc0: 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74 69 63 20  ow.** energetic 
6fd0: 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f 72 20 66  or rigorous or f
6fe0: 6f 72 63 65 66 75 6c 20 74 68 65 20 73 79 6e 63  orceful the sync
6ff0: 20 6f 70 65 72 61 74 69 6f 6e 73 20 61 72 65 20   operations are 
7000: 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d 61 6b 65  and.** only make
7010: 20 61 20 64 69 66 66 65 72 65 6e 63 65 20 6f 6e   a difference on
7020: 20 4d 61 63 20 4f 53 58 20 66 6f 72 20 74 68 65   Mac OSX for the
7030: 20 64 65 66 61 75 6c 74 20 53 51 4c 69 74 65 20   default SQLite 
7040: 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69 72 64 2d  code..** (Third-
7050: 70 61 72 74 79 20 56 46 53 20 69 6d 70 6c 65 6d  party VFS implem
7060: 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67 68 74 20  entations might 
7070: 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65 20 64 69  also make the di
7080: 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20 62 65 74  stinction.** bet
7090: 77 65 65 6e 20 53 51 4c 49 54 45 5f 53 59 4e 43  ween SQLITE_SYNC
70a0: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
70b0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 62 75  TE_SYNC_FULL, bu
70c0: 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a 2a 20 6f  t among the.** o
70d0: 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 73  perating systems
70e0: 20 6e 61 74 69 76 65 6c 79 20 73 75 70 70 6f 72   natively suppor
70f0: 74 65 64 20 62 79 20 53 51 4c 69 74 65 2c 20 6f  ted by SQLite, o
7100: 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a 2a 20 63  nly Mac OSX.** c
7110: 61 72 65 73 20 61 62 6f 75 74 20 74 68 65 20 64  ares about the d
7120: 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a 2f 0a 23  ifference.).*/.#
7130: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59  define SQLITE_SY
7140: 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20 20 20 20  NC_NORMAL       
7150: 20 30 78 30 30 30 30 32 0a 23 64 65 66 69 6e 65   0x00002.#define
7160: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
7170: 4c 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30  L          0x000
7180: 30 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  03.#define SQLIT
7190: 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 20  E_SYNC_DATAONLY 
71a0: 20 20 20 20 20 30 78 30 30 30 31 30 0a 0a 2f 2a       0x00010../*
71b0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53  .** CAPI3REF: OS
71c0: 20 49 6e 74 65 72 66 61 63 65 20 4f 70 65 6e 20   Interface Open 
71d0: 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a  File Handle.**.*
71e0: 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69  * An [sqlite3_fi
71f0: 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65 70 72 65  le] object repre
7200: 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e 20 66 69  sents an open fi
7210: 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a 20 5b 73  le in the .** [s
7220: 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 4f 53 20  qlite3_vfs | OS 
7230: 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72 5d  interface layer]
7240: 2e 20 20 49 6e 64 69 76 69 64 75 61 6c 20 4f 53  .  Individual OS
7250: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 69 6d   interface.** im
7260: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 77 69  plementations wi
7270: 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f 20 73 75  ll.** want to su
7280: 62 63 6c 61 73 73 20 74 68 69 73 20 6f 62 6a 65  bclass this obje
7290: 63 74 20 62 79 20 61 70 70 65 6e 64 69 6e 67 20  ct by appending 
72a0: 61 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64  additional field
72b0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69 72 20 6f  s.** for their o
72c0: 77 6e 20 75 73 65 2e 20 20 54 68 65 20 70 4d 65  wn use.  The pMe
72d0: 74 68 6f 64 73 20 65 6e 74 72 79 20 69 73 20 61  thods entry is a
72e0: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
72f0: 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  * [sqlite3_io_me
7300: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 74 68  thods] object th
7310: 61 74 20 64 65 66 69 6e 65 73 20 6d 65 74 68 6f  at defines metho
7320: 64 73 20 66 6f 72 20 70 65 72 66 6f 72 6d 69 6e  ds for performin
7330: 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72 61 74 69  g.** I/O operati
7340: 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70 65 6e 20  ons on the open 
7350: 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  file..*/.typedef
7360: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
7370: 66 69 6c 65 20 73 71 6c 69 74 65 33 5f 66 69 6c  file sqlite3_fil
7380: 65 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  e;.struct sqlite
7390: 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f 6e 73 74  3_file {.  const
73a0: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
73b0: 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70 4d 65 74  io_methods *pMet
73c0: 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74 68 6f 64  hods;  /* Method
73d0: 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e 20 66 69  s for an open fi
73e0: 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20  le */.};../*.** 
73f0: 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49 6e 74  CAPI3REF: OS Int
7400: 65 72 66 61 63 65 20 46 69 6c 65 20 56 69 72 74  erface File Virt
7410: 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f 62 6a 65  ual Methods Obje
7420: 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72 79 20 66  ct.**.** Every f
7430: 69 6c 65 20 6f 70 65 6e 65 64 20 62 79 20 74 68  ile opened by th
7440: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
7450: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20 70 6f 70  Open] method pop
7460: 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20 5b 73 71  ulates an.** [sq
7470: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
7480: 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20 63 6f 6d  ct (or, more com
7490: 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63 6c 61 73  monly, a subclas
74a0: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  s of the.** [sql
74b0: 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63  ite3_file] objec
74c0: 74 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  t) with a pointe
74d0: 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65  r to an instance
74e0: 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 2e   of this object.
74f0: 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20  .** This object 
7500: 64 65 66 69 6e 65 73 20 74 68 65 20 6d 65 74 68  defines the meth
7510: 6f 64 73 20 75 73 65 64 20 74 6f 20 70 65 72 66  ods used to perf
7520: 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f 70 65 72  orm various oper
7530: 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61 69 6e 73  ations.** agains
7540: 74 20 74 68 65 20 6f 70 65 6e 20 66 69 6c 65 20  t the open file 
7550: 72 65 70 72 65 73 65 6e 74 65 64 20 62 79 20 74  represented by t
7560: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7570: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
7580: 49 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  If the [sqlite3_
7590: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
75a0: 64 20 73 65 74 73 20 74 68 65 20 73 71 6c 69 74  d sets the sqlit
75b0: 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73  e3_file.pMethods
75c0: 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20 74 6f 20   element .** to 
75d0: 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74  a non-NULL point
75e0: 65 72 2c 20 74 68 65 6e 20 74 68 65 20 73 71 6c  er, then the sql
75f0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 2e  ite3_io_methods.
7600: 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64 0a 2a 2a  xClose method.**
7610: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
7620: 65 76 65 6e 20 69 66 20 74 68 65 20 5b 73 71 6c  even if the [sql
7630: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
7640: 72 65 70 6f 72 74 65 64 20 74 68 61 74 20 69 74  reported that it
7650: 20 66 61 69 6c 65 64 2e 20 20 54 68 65 0a 2a 2a   failed.  The.**
7660: 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20 70 72 65   only way to pre
7670: 76 65 6e 74 20 61 20 63 61 6c 6c 20 74 6f 20 78  vent a call to x
7680: 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  Close following 
7690: 61 20 66 61 69 6c 65 64 20 5b 73 71 6c 69 74 65  a failed [sqlite
76a0: 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a 2a 2a 20  3_vfs.xOpen].** 
76b0: 69 73 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69  is for the [sqli
76c0: 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 74  te3_vfs.xOpen] t
76d0: 6f 20 73 65 74 20 74 68 65 20 73 71 6c 69 74 65  o set the sqlite
76e0: 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20  3_file.pMethods 
76f0: 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f 20 4e 55  element.** to NU
7700: 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c  LL..**.** The fl
7710: 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ags argument to 
7720: 78 53 79 6e 63 20 6d 61 79 20 62 65 20 6f 6e 65  xSync may be one
7730: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43   of [SQLITE_SYNC
7740: 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a 2a 20 5b  _NORMAL] or.** [
7750: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c  SQLITE_SYNC_FULL
7760: 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 63 68  ].  The first ch
7770: 6f 69 63 65 20 69 73 20 74 68 65 20 6e 6f 72 6d  oice is the norm
7780: 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 20 54  al fsync()..** T
7790: 68 65 20 73 65 63 6f 6e 64 20 63 68 6f 69 63 65  he second choice
77a0: 20 69 73 20 61 20 4d 61 63 20 4f 53 20 58 20 73   is a Mac OS X s
77b0: 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63 2e 20 20  tyle fullsync.  
77c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  The [SQLITE_SYNC
77d0: 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a 20 66 6c  _DATAONLY].** fl
77e0: 61 67 20 6d 61 79 20 62 65 20 4f 52 65 64 20 69  ag may be ORed i
77f0: 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74 68  n to indicate th
7800: 61 74 20 6f 6e 6c 79 20 74 68 65 20 64 61 74 61  at only the data
7810: 20 6f 66 20 74 68 65 20 66 69 6c 65 0a 2a 2a 20   of the file.** 
7820: 61 6e 64 20 6e 6f 74 20 69 74 73 20 69 6e 6f 64  and not its inod
7830: 65 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 79  e needs to be sy
7840: 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nced..**.** The 
7850: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 74  integer values t
7860: 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  o xLock() and xU
7870: 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f 6e 65 20  nlock() are one 
7880: 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  of.** <ul>.** <l
7890: 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  i> [SQLITE_LOCK_
78a0: 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  NONE],.** <li> [
78b0: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41 52  SQLITE_LOCK_SHAR
78c0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
78d0: 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56  LITE_LOCK_RESERV
78e0: 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  ED],.** <li> [SQ
78f0: 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e  LITE_LOCK_PENDIN
7900: 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b  G], or.** <li> [
7910: 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c  SQLITE_LOCK_EXCL
7920: 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e  USIVE]..** </ul>
7930: 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69 6e 63 72  .** xLock() incr
7940: 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 20  eases the lock. 
7950: 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63 72 65 61  xUnlock() decrea
7960: 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e 0a 2a 2a  ses the lock..**
7970: 20 54 68 65 20 78 43 68 65 63 6b 52 65 73 65 72   The xCheckReser
7980: 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74 68 6f 64  vedLock() method
7990: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
79a0: 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f 6e  any database con
79b0: 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65 69 74 68  nection,.** eith
79c0: 65 72 20 69 6e 20 74 68 69 73 20 70 72 6f 63 65  er in this proce
79d0: 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65 20 6f 74  ss or in some ot
79e0: 68 65 72 20 70 72 6f 63 65 73 73 2c 20 69 73 20  her process, is 
79f0: 68 6f 6c 64 69 6e 67 20 61 20 52 45 53 45 52 56  holding a RESERV
7a00: 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e 47 2c 20  ED,.** PENDING, 
7a10: 6f 72 20 45 58 43 4c 55 53 49 56 45 20 6c 6f 63  or EXCLUSIVE loc
7a20: 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65 2e 20 20  k on the file.  
7a30: 49 74 20 72 65 74 75 72 6e 73 20 74 72 75 65 0a  It returns true.
7a40: 2a 2a 20 69 66 20 73 75 63 68 20 61 20 6c 6f 63  ** if such a loc
7a50: 6b 20 65 78 69 73 74 73 20 61 6e 64 20 66 61 6c  k exists and fal
7a60: 73 65 20 6f 74 68 65 72 77 69 73 65 2e 0a 2a 2a  se otherwise..**
7a70: 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65 43 6f 6e  .** The xFileCon
7a80: 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64 20 69 73  trol() method is
7a90: 20 61 20 67 65 6e 65 72 69 63 20 69 6e 74 65 72   a generic inter
7aa0: 66 61 63 65 20 74 68 61 74 20 61 6c 6c 6f 77 73  face that allows
7ab0: 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46 53 20 69   custom.** VFS i
7ac0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 74  mplementations t
7ad0: 6f 20 64 69 72 65 63 74 6c 79 20 63 6f 6e 74 72  o directly contr
7ae0: 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69 6c 65 20  ol an open file 
7af0: 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
7b00: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
7b10: 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e  ol()] interface.
7b20: 20 20 54 68 65 20 73 65 63 6f 6e 64 20 22 6f 70    The second "op
7b30: 22 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  " argument is an
7b40: 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f 70 63 6f  .** integer opco
7b50: 64 65 2e 20 20 54 68 65 20 74 68 69 72 64 20 61  de.  The third a
7b60: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 67 65 6e  rgument is a gen
7b70: 65 72 69 63 20 70 6f 69 6e 74 65 72 20 69 6e 74  eric pointer int
7b80: 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70 6f 69 6e  ended to.** poin
7b90: 74 20 74 6f 20 61 20 73 74 72 75 63 74 75 72 65  t to a structure
7ba0: 20 74 68 61 74 20 6d 61 79 20 63 6f 6e 74 61 69   that may contai
7bb0: 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20 73  n arguments or s
7bc0: 70 61 63 65 20 69 6e 20 77 68 69 63 68 20 74 6f  pace in which to
7bd0: 0a 2a 2a 20 77 72 69 74 65 20 72 65 74 75 72 6e  .** write return
7be0: 20 76 61 6c 75 65 73 2e 20 20 50 6f 74 65 6e 74   values.  Potent
7bf0: 69 61 6c 20 75 73 65 73 20 66 6f 72 20 78 46 69  ial uses for xFi
7c00: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 69 67 68  leControl() migh
7c10: 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  t be.** function
7c20: 73 20 74 6f 20 65 6e 61 62 6c 65 20 62 6c 6f 63  s to enable bloc
7c30: 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69 74 68 20  king locks with 
7c40: 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20 63 68 61  timeouts, to cha
7c50: 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f 63 6b 69  nge the.** locki
7c60: 6e 67 20 73 74 72 61 74 65 67 79 20 28 66 6f 72  ng strategy (for
7c70: 20 65 78 61 6d 70 6c 65 20 74 6f 20 75 73 65 20   example to use 
7c80: 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b 73 29 2c  dot-file locks),
7c90: 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a 2a 20 61   to inquire.** a
7ca0: 62 6f 75 74 20 74 68 65 20 73 74 61 74 75 73 20  bout the status 
7cb0: 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72 20 74 6f  of a lock, or to
7cc0: 20 62 72 65 61 6b 20 73 74 61 6c 65 20 6c 6f 63   break stale loc
7cd0: 6b 73 2e 20 20 54 68 65 20 53 51 4c 69 74 65 0a  ks.  The SQLite.
7ce0: 2a 2a 20 63 6f 72 65 20 72 65 73 65 72 76 65 73  ** core reserves
7cf0: 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20 6c 65 73   all opcodes les
7d00: 73 20 74 68 61 6e 20 31 30 30 20 66 6f 72 20 69  s than 100 for i
7d10: 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a 2a 20 41  ts own use..** A
7d20: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c   [SQLITE_FCNTL_L
7d30: 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69 73 74 20  OCKSTATE | list 
7d40: 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73 73  of opcodes] less
7d50: 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76 61   than 100 is ava
7d60: 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c 69  ilable..** Appli
7d70: 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65 66  cations that def
7d80: 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46 69  ine a custom xFi
7d90: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7da0: 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63 6f   should use opco
7db0: 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20 74  des.** greater t
7dc0: 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69 64  han 100 to avoid
7dd0: 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46 53   conflicts.  VFS
7de0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7df0: 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72   should.** retur
7e00: 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55  n [SQLITE_NOTFOU
7e10: 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f 6e  ND] for file con
7e20: 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68 61  trol opcodes tha
7e30: 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
7e40: 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a 2a   recognize..**.*
7e50: 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69 7a  * The xSectorSiz
7e60: 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75 72  e() method retur
7e70: 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73 69  ns the sector si
7e80: 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65 76  ze of the.** dev
7e90: 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c 69  ice that underli
7ea0: 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68  es the file.  Th
7eb0: 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69 73  e sector size is
7ec0: 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d 20   the.** minimum 
7ed0: 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20 62  write that can b
7ee0: 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74 68  e performed with
7ef0: 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a 2a  out disturbing.*
7f00: 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69 6e  * other bytes in
7f10: 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65 20   the file.  The 
7f20: 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65 72  xDeviceCharacter
7f30: 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74 68  istics().** meth
7f40: 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69 74  od returns a bit
7f50: 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62 69   vector describi
7f60: 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66 20  ng behaviors of 
7f70: 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69 6e  the.** underlyin
7f80: 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a 20  g device:.**.** 
7f90: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
7fa0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7fb0: 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  C].** <li> [SQLI
7fc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 35  TE_IOCAP_ATOMIC5
7fd0: 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  12].** <li> [SQL
7fe0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7ff0: 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  1K].** <li> [SQL
8000: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8010: 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  2K].** <li> [SQL
8020: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8030: 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  4K].** <li> [SQL
8040: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8050: 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  8K].** <li> [SQL
8060: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
8070: 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  16K].** <li> [SQ
8080: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8090: 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C32K].** <li> [S
80a0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
80b0: 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC64K].** <li> [
80c0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46  SQLITE_IOCAP_SAF
80d0: 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c 69  E_APPEND].** <li
80e0: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
80f0: 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20 3c  SEQUENTIAL].** <
8100: 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  /ul>.**.** The S
8110: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8120: 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e  IC property mean
8130: 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74 65  s that all write
8140: 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a 65  s of.** any size
8150: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8160: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
8170: 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73 0a  TOMICnnn values.
8180: 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72 69  ** mean that wri
8190: 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74 68  tes of blocks th
81a0: 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65 73  at are nnn bytes
81b0: 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a 20   in size and.** 
81c0: 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  are aligned to a
81d0: 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68 20  n address which 
81e0: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d 75  is an integer mu
81f0: 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e 6e  ltiple of.** nnn
8200: 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54 68   are atomic.  Th
8210: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53  e SQLITE_IOCAP_S
8220: 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75 65  AFE_APPEND value
8230: 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20 77   means.** that w
8240: 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70 65  hen data is appe
8250: 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c 20  nded to a file, 
8260: 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70 65  the data is appe
8270: 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74 68  nded.** first th
8280: 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  en the size of t
8290: 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65 6e  he file is exten
82a0: 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20 6f  ded, never the o
82b0: 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f 75  ther.** way arou
82c0: 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f  nd.  The SQLITE_
82d0: 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c  IOCAP_SEQUENTIAL
82e0: 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73 20   property means 
82f0: 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74  that.** informat
8300: 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20 74  ion is written t
8310: 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73 61  o disk in the sa
8320: 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c 6c  me order as call
8330: 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28 29  s.** to xWrite()
8340: 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61 64  ..**.** If xRead
8350: 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49 54  () returns SQLIT
8360: 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52 45  E_IOERR_SHORT_RE
8370: 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f 20  AD it must also 
8380: 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20 75  fill.** in the u
8390: 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20 6f  nread portions o
83a0: 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69 74  f the buffer wit
83b0: 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53 20  h zeros.  A VFS 
83c0: 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74 6f  that.** fails to
83d0: 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72 74   zero-fill short
83e0: 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65 65   reads might see
83f0: 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77 65  m to work.  Howe
8400: 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65 20  ver,.** failure 
8410: 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f  to zero-fill sho
8420: 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65 76  rt reads will ev
8430: 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74 6f  entually lead to
8440: 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 72  .** database cor
8450: 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  ruption..*/.type
8460: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
8470: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73 71  e3_io_methods sq
8480: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
8490: 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
84a0: 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20  _io_methods {.  
84b0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20 20  int iVersion;.  
84c0: 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71  int (*xClose)(sq
84d0: 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20  lite3_file*);.  
84e0: 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71 6c  int (*xRead)(sql
84f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69 64  ite3_file*, void
8500: 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c  *, int iAmt, sql
8510: 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74  ite3_int64 iOfst
8520: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69 74  );.  int (*xWrit
8530: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8540: 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
8550: 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33  nt iAmt, sqlite3
8560: 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20  _int64 iOfst);. 
8570: 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74 65   int (*xTruncate
8580: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
8590: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73   sqlite3_int64 s
85a0: 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53  ize);.  int (*xS
85b0: 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ync)(sqlite3_fil
85c0: 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a  e*, int flags);.
85d0: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69 7a    int (*xFileSiz
85e0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
85f0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
8600: 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  *pSize);.  int (
8610: 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  *xLock)(sqlite3_
8620: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
8630: 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73 71  nt (*xUnlock)(sq
8640: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8650: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65 63  );.  int (*xChec
8660: 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28 73  kReservedLock)(s
8670: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8680: 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69  t *pResOut);.  i
8690: 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72 6f  nt (*xFileContro
86a0: 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  l)(sqlite3_file*
86b0: 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20 2a  , int op, void *
86c0: 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78  pArg);.  int (*x
86d0: 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c 69  SectorSize)(sqli
86e0: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e  te3_file*);.  in
86f0: 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72 61  t (*xDeviceChara
8700: 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c 69  cteristics)(sqli
8710: 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f 2a  te3_file*);.  /*
8720: 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61   Methods above a
8730: 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65 72  re valid for ver
8740: 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74 20  sion 1 */.  int 
8750: 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69 74  (*xShmMap)(sqlit
8760: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69 50  e3_file*, int iP
8770: 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e 74  g, int pgsz, int
8780: 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65 2a  , void volatile*
8790: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
87a0: 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69  Lock)(sqlite3_fi
87b0: 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74 2c  le*, int offset,
87c0: 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61 67   int n, int flag
87d0: 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53 68  s);.  void (*xSh
87e0: 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74 65  mBarrier)(sqlite
87f0: 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  3_file*);.  int 
8800: 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71 6c  (*xShmUnmap)(sql
8810: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
8820: 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20 2f  deleteFlag);.  /
8830: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8840: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8850: 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e 74  rsion 2 */.  int
8860: 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69 74   (*xFetch)(sqlit
8870: 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65  e3_file*, sqlite
8880: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20 69  3_int64 iOfst, i
8890: 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a 2a  nt iAmt, void **
88a0: 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e  pp);.  int (*xUn
88b0: 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f 66  fetch)(sqlite3_f
88c0: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
88d0: 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64 20  t64 iOfst, void 
88e0: 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64  *p);.  /* Method
88f0: 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c 69  s above are vali
8900: 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  d for version 3 
8910: 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e  */.  /* Addition
8920: 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20 62  al methods may b
8930: 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75 72  e added in futur
8940: 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b  e releases */.};
8950: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
8960: 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65 20  : Standard File 
8970: 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a  Control Opcodes.
8980: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
8990: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ger constants ar
89a0: 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20 74 68  e opcodes for th
89b0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  e xFileControl m
89c0: 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
89d0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
89e0: 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20  ods] object and 
89f0: 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74 65 33  for the [sqlite3
8a00: 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d  _file_control()]
8a10: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  .** interface..*
8a20: 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45  *.** The [SQLITE
8a30: 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45  _FCNTL_LOCKSTATE
8a40: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
8a50: 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67 2e 20   for debugging. 
8a60: 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20   This.** opcode 
8a70: 63 61 75 73 65 73 20 74 68 65 20 78 46 69 6c 65  causes the xFile
8a80: 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74  Control method t
8a90: 6f 20 77 72 69 74 65 20 74 68 65 20 63 75 72 72  o write the curr
8aa0: 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20  ent state of.** 
8ab0: 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66  the lock (one of
8ac0: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f   [SQLITE_LOCK_NO
8ad0: 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43  NE], [SQLITE_LOC
8ae0: 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53  K_SHARED],.** [S
8af0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52  QLITE_LOCK_RESER
8b00: 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f  VED], [SQLITE_LO
8b10: 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20  CK_PENDING], or 
8b20: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43  [SQLITE_LOCK_EXC
8b30: 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f  LUSIVE]).** into
8b40: 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68 61 74   an integer that
8b50: 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d 65   the pArg argume
8b60: 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68  nt points to. Th
8b70: 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a  is capability.**
8b80: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
8b90: 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79  testing and only
8ba0: 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73 75 70   needs to be sup
8bb0: 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51 4c 49  ported when SQLI
8bc0: 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20 64 65  TE_TEST.** is de
8bd0: 66 69 6e 65 64 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a  fined..** <ul>.*
8be0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
8bf0: 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d 5d  CNTL_SIZE_HINT]]
8c00: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8c10: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 5d  FCNTL_SIZE_HINT]
8c20: 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20   opcode is used 
8c30: 62 79 20 53 51 4c 69 74 65 20 74 6f 20 67 69 76  by SQLite to giv
8c40: 65 20 74 68 65 20 56 46 53 0a 2a 2a 20 6c 61 79  e the VFS.** lay
8c50: 65 72 20 61 20 68 69 6e 74 20 6f 66 20 68 6f 77  er a hint of how
8c60: 20 6c 61 72 67 65 20 74 68 65 20 64 61 74 61 62   large the datab
8c70: 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20 67 72  ase file will gr
8c80: 6f 77 20 74 6f 20 62 65 20 64 75 72 69 6e 67 20  ow to be during 
8c90: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 74  the.** current t
8ca0: 72 61 6e 73 61 63 74 69 6f 6e 2e 20 20 54 68 69  ransaction.  Thi
8cb0: 73 20 68 69 6e 74 20 69 73 20 6e 6f 74 20 67 75  s hint is not gu
8cc0: 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 61  aranteed to be a
8cd0: 63 63 75 72 61 74 65 20 62 75 74 20 69 74 0a 2a  ccurate but it.*
8ce0: 2a 20 69 73 20 6f 66 74 65 6e 20 63 6c 6f 73 65  * is often close
8cf0: 2e 20 20 54 68 65 20 75 6e 64 65 72 6c 79 69 6e  .  The underlyin
8d00: 67 20 56 46 53 20 6d 69 67 68 74 20 63 68 6f 6f  g VFS might choo
8d10: 73 65 20 74 6f 20 70 72 65 61 6c 6c 6f 63 61 74  se to preallocat
8d20: 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69  e database.** fi
8d30: 6c 65 20 73 70 61 63 65 20 62 61 73 65 64 20 6f  le space based o
8d40: 6e 20 74 68 69 73 20 68 69 6e 74 20 69 6e 20 6f  n this hint in o
8d50: 72 64 65 72 20 74 6f 20 68 65 6c 70 20 77 72 69  rder to help wri
8d60: 74 65 73 20 74 6f 20 74 68 65 20 64 61 74 61 62  tes to the datab
8d70: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 72 75 6e 20  ase.** file run 
8d80: 66 61 73 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c  faster..**.** <l
8d90: 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  i>[[SQLITE_FCNTL
8da0: 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a  _CHUNK_SIZE]].**
8db0: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
8dc0: 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45 5d 20 6f  TL_CHUNK_SIZE] o
8dd0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f  pcode is used to
8de0: 20 72 65 71 75 65 73 74 20 74 68 61 74 20 74 68   request that th
8df0: 65 20 56 46 53 0a 2a 2a 20 65 78 74 65 6e 64 73  e VFS.** extends
8e00: 20 61 6e 64 20 74 72 75 6e 63 61 74 65 73 20 74   and truncates t
8e10: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
8e20: 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66 20 61 20   in chunks of a 
8e30: 73 69 7a 65 20 73 70 65 63 69 66 69 65 64 0a 2a  size specified.*
8e40: 2a 20 62 79 20 74 68 65 20 75 73 65 72 2e 20 54  * by the user. T
8e50: 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
8e60: 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66  nt to [sqlite3_f
8e70: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 73  ile_control()] s
8e80: 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69 6e 74 20  hould .** point 
8e90: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 28 74  to an integer (t
8ea0: 79 70 65 20 69 6e 74 29 20 63 6f 6e 74 61 69 6e  ype int) contain
8eb0: 69 6e 67 20 74 68 65 20 6e 65 77 20 63 68 75 6e  ing the new chun
8ec0: 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65 0a 2a 2a  k-size to use.**
8ed0: 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69 6e 61 74   for the nominat
8ee0: 65 64 20 64 61 74 61 62 61 73 65 2e 20 41 6c 6c  ed database. All
8ef0: 6f 63 61 74 69 6e 67 20 64 61 74 61 62 61 73 65  ocating database
8f00: 20 66 69 6c 65 20 73 70 61 63 65 20 69 6e 20 6c   file space in l
8f10: 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b 73 20 28  arge.** chunks (
8f20: 73 61 79 20 31 4d 42 20 61 74 20 61 20 74 69 6d  say 1MB at a tim
8f30: 65 29 2c 20 6d 61 79 20 72 65 64 75 63 65 20 66  e), may reduce f
8f40: 69 6c 65 2d 73 79 73 74 65 6d 20 66 72 61 67 6d  ile-system fragm
8f50: 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20  entation and.** 
8f60: 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61  improve performa
8f70: 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73 79 73 74  nce on some syst
8f80: 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ems..**.** <li>[
8f90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49  [SQLITE_FCNTL_FI
8fa0: 4c 45 5f 50 4f 49 4e 54 45 52 5d 5d 0a 2a 2a 20  LE_POINTER]].** 
8fb0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8fc0: 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20  L_FILE_POINTER] 
8fd0: 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 74  opcode is used t
8fe0: 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74  o obtain a point
8ff0: 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71  er.** to the [sq
9000: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
9010: 63 74 20 61 73 73 6f 63 69 61 74 65 64 20 77 69  ct associated wi
9020: 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  th a particular 
9030: 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
9040: 65 63 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65  ection.  See the
9050: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
9060: 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65  ontrol()] docume
9070: 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61  ntation for.** a
9080: 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
9090: 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ation..**.** <li
90a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
90b0: 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 5d 0a 2a  SYNC_OMITTED]].*
90c0: 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 69 6e 20 75  * No longer in u
90d0: 73 65 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  se..**.** <li>[[
90e0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
90f0: 43 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  C]].** The [SQLI
9100: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 20 6f  TE_FCNTL_SYNC] o
9110: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
9120: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9130: 20 53 51 4c 69 74 65 20 61 6e 64 0a 2a 2a 20 73   SQLite and.** s
9140: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 69  ent to the VFS i
9150: 6d 6d 65 64 69 61 74 65 6c 79 20 62 65 66 6f 72  mmediately befor
9160: 65 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  e the xSync meth
9170: 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e  od is invoked on
9180: 20 61 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 66   a.** database f
9190: 69 6c 65 20 64 65 73 63 72 69 70 74 6f 72 2e 20  ile descriptor. 
91a0: 4f 72 2c 20 69 66 20 74 68 65 20 78 53 79 6e 63  Or, if the xSync
91b0: 20 6d 65 74 68 6f 64 20 69 73 20 6e 6f 74 20 69   method is not i
91c0: 6e 76 6f 6b 65 64 20 0a 2a 2a 20 62 65 63 61 75  nvoked .** becau
91d0: 73 65 20 74 68 65 20 75 73 65 72 20 68 61 73 20  se the user has 
91e0: 63 6f 6e 66 69 67 75 72 65 64 20 53 51 4c 69 74  configured SQLit
91f0: 65 20 77 69 74 68 20 0a 2a 2a 20 5b 50 52 41 47  e with .** [PRAG
9200: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 20 7c  MA synchronous |
9210: 20 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e   PRAGMA synchron
9220: 6f 75 73 3d 4f 46 46 5d 20 69 74 20 69 73 20 69  ous=OFF] it is i
9230: 6e 76 6f 6b 65 64 20 69 6e 20 70 6c 61 63 65 20  nvoked in place 
9240: 0a 2a 2a 20 6f 66 20 74 68 65 20 78 53 79 6e 63  .** of the xSync
9250: 20 6d 65 74 68 6f 64 2e 20 49 6e 20 6d 6f 73 74   method. In most
9260: 20 63 61 73 65 73 2c 20 74 68 65 20 70 6f 69 6e   cases, the poin
9270: 74 65 72 20 61 72 67 75 6d 65 6e 74 20 70 61 73  ter argument pas
9280: 73 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 69 73  sed with.** this
9290: 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 69 73   file-control is
92a0: 20 4e 55 4c 4c 2e 20 48 6f 77 65 76 65 72 2c 20   NULL. However, 
92b0: 69 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  if the database 
92c0: 66 69 6c 65 20 69 73 20 62 65 69 6e 67 20 73 79  file is being sy
92d0: 6e 63 65 64 0a 2a 2a 20 61 73 20 70 61 72 74 20  nced.** as part 
92e0: 6f 66 20 61 20 6d 75 6c 74 69 2d 64 61 74 61 62  of a multi-datab
92f0: 61 73 65 20 63 6f 6d 6d 69 74 2c 20 74 68 65 20  ase commit, the 
9300: 61 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 73 20  argument points 
9310: 74 6f 20 61 20 6e 75 6c 2d 74 65 72 6d 69 6e 61  to a nul-termina
9320: 74 65 64 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f  ted.** string co
9330: 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 74 72 61  ntaining the tra
9340: 6e 73 61 63 74 69 6f 6e 73 20 6d 61 73 74 65 72  nsactions master
9350: 2d 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 6e 61  -journal file na
9360: 6d 65 2e 20 56 46 53 65 73 20 74 68 61 74 20 0a  me. VFSes that .
9370: 2a 2a 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74  ** do not need t
9380: 68 69 73 20 73 69 67 6e 61 6c 20 73 68 6f 75 6c  his signal shoul
9390: 64 20 73 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72  d silently ignor
93a0: 65 20 74 68 69 73 20 6f 70 63 6f 64 65 2e 20 41  e this opcode. A
93b0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 0a 2a 2a 20  pplications .** 
93c0: 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c 20  should not call 
93d0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
93e0: 6e 74 72 6f 6c 28 29 5d 20 77 69 74 68 20 74 68  ntrol()] with th
93f0: 69 73 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69  is opcode as doi
9400: 6e 67 20 73 6f 20 6d 61 79 20 0a 2a 2a 20 64 69  ng so may .** di
9410: 73 72 75 70 74 20 74 68 65 20 6f 70 65 72 61 74  srupt the operat
9420: 69 6f 6e 20 6f 66 20 74 68 65 20 73 70 65 63 69  ion of the speci
9430: 61 6c 69 7a 65 64 20 56 46 53 65 73 20 74 68 61  alized VFSes tha
9440: 74 20 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e  t do require it.
9450: 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53    .**.** <li>[[S
9460: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
9470: 49 54 5f 50 48 41 53 45 54 57 4f 5d 5d 0a 2a 2a  IT_PHASETWO]].**
9480: 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e   The [SQLITE_FCN
9490: 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48 41 53 45 54  TL_COMMIT_PHASET
94a0: 57 4f 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65  WO] opcode is ge
94b0: 6e 65 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c  nerated internal
94c0: 6c 79 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ly by SQLite.** 
94d0: 61 6e 64 20 73 65 6e 74 20 74 6f 20 74 68 65 20  and sent to the 
94e0: 56 46 53 20 61 66 74 65 72 20 61 20 74 72 61 6e  VFS after a tran
94f0: 73 61 63 74 69 6f 6e 20 68 61 73 20 62 65 65 6e  saction has been
9500: 20 63 6f 6d 6d 69 74 74 65 64 20 69 6d 6d 65 64   committed immed
9510: 69 61 74 65 6c 79 0a 2a 2a 20 62 75 74 20 62 65  iately.** but be
9520: 66 6f 72 65 20 74 68 65 20 64 61 74 61 62 61 73  fore the databas
9530: 65 20 69 73 20 75 6e 6c 6f 63 6b 65 64 2e 20 56  e is unlocked. V
9540: 46 53 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74  FSes that do not
9550: 20 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61   need this signa
9560: 6c 0a 2a 2a 20 73 68 6f 75 6c 64 20 73 69 6c 65  l.** should sile
9570: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
9580: 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63 61   opcode. Applica
9590: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f 74  tions should not
95a0: 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69 74 65   call.** [sqlite
95b0: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
95c0: 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70 63 6f  ] with this opco
95d0: 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20 6d  de as doing so m
95e0: 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20 0a  ay disrupt the .
95f0: 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20  ** operation of 
9600: 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20  the specialized 
9610: 56 46 53 65 73 20 74 68 61 74 20 64 6f 20 72 65  VFSes that do re
9620: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
9630: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
9640: 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45  CNTL_WIN32_AV_RE
9650: 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  TRY]].** ^The [S
9660: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33  QLITE_FCNTL_WIN3
9670: 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70 63 6f  2_AV_RETRY] opco
9680: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 63 6f  de is used to co
9690: 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61 74 69  nfigure automati
96a0: 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75 6e 74  c.** retry count
96b0: 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c 73 20  s and intervals 
96c0: 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69 73 6b  for certain disk
96d0: 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e 73 20   I/O operations 
96e0: 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e 64 6f  for the.** windo
96f0: 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72 64 65  ws [VFS] in orde
9700: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72 6f 62  r to provide rob
9710: 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65 20 70  ustness in the p
9720: 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20 61 6e  resence of.** an
9730: 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72 61 6d  ti-virus program
9740: 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74 2c 20  s.  By default, 
9750: 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46 53 20  the windows VFS 
9760: 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c 65 20  will retry file 
9770: 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20 77 72  read,.** file wr
9780: 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20 64 65  ite, and file de
9790: 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e 73 20  lete operations 
97a0: 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73 2c 20  up to 10 times, 
97b0: 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a 2a 20  with a delay.** 
97c0: 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e  of 25 millisecon
97d0: 64 73 20 62 65 66 6f 72 65 20 74 68 65 20 66 69  ds before the fi
97e0: 72 73 74 20 72 65 74 72 79 20 61 6e 64 20 77 69  rst retry and wi
97f0: 74 68 20 74 68 65 20 64 65 6c 61 79 20 69 6e 63  th the delay inc
9800: 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20 61 6e  reasing.** by an
9810: 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35 20 6d   additional 25 m
9820: 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69 74 68  illiseconds with
9830: 20 65 61 63 68 20 73 75 62 73 65 71 75 65 6e 74   each subsequent
9840: 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a 2a 2a   retry.  This.**
9850: 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73 20 74   opcode allows t
9860: 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65 73 20  hese two values 
9870: 28 31 30 20 72 65 74 72 69 65 73 20 61 6e 64 20  (10 retries and 
9880: 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  25 milliseconds 
9890: 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74 6f 20  of delay).** to 
98a0: 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20 54 68  be adjusted.  Th
98b0: 65 20 76 61 6c 75 65 73 20 61 72 65 20 63 68 61  e values are cha
98c0: 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64 61 74  nged for all dat
98d0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
98e0: 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68 65 20  s.** within the 
98f0: 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20 20 54  same process.  T
9900: 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  he argument is a
9910: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 61   pointer to an a
9920: 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a 20 69  rray of two.** i
9930: 6e 74 65 67 65 72 73 20 77 68 65 72 65 20 74 68  ntegers where th
9940: 65 20 66 69 72 73 74 20 69 6e 74 65 67 65 72 20  e first integer 
9950: 69 20 74 68 65 20 6e 65 77 20 72 65 74 72 79 20  i the new retry 
9960: 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20 73 65  count and the se
9970: 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  cond.** integer 
9980: 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20 20 49  is the delay.  I
9990: 66 20 65 69 74 68 65 72 20 69 6e 74 65 67 65 72  f either integer
99a0: 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
99b0: 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67 0a 2a  en the setting.*
99c0: 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65 64  * is not changed
99d0: 20 62 75 74 20 69 6e 73 74 65 61 64 20 74 68 65   but instead the
99e0: 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
99f0: 74 68 61 74 20 73 65 74 74 69 6e 67 20 69 73 20  that setting is 
9a00: 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74 6f 20  written.** into 
9a10: 74 68 65 20 61 72 72 61 79 20 65 6e 74 72 79 2c  the array entry,
9a20: 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20 63 75   allowing the cu
9a30: 72 72 65 6e 74 20 72 65 74 72 79 20 73 65 74 74  rrent retry sett
9a40: 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20 69 6e  ings to be.** in
9a50: 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54 68 65  terrogated.  The
9a60: 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d 65 74   zDbName paramet
9a70: 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a  er is ignored..*
9a80: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9a90: 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f  E_FCNTL_PERSIST_
9aa0: 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  WAL]].** ^The [S
9ab0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53  QLITE_FCNTL_PERS
9ac0: 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64 65 20  IST_WAL] opcode 
9ad0: 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20 6f  is used to set o
9ae0: 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20 70  r query the.** p
9af0: 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c 20 7c  ersistent [WAL |
9b00: 20 57 72 69 74 65 20 41 68 65 61 64 20 4c 6f 67   Write Ahead Log
9b10: 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79 20 64  ] setting.  By d
9b20: 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75 78 69  efault, the auxi
9b30: 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65 20 61  liary.** write a
9b40: 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73 68 61  head log and sha
9b50: 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c 65 73  red memory files
9b60: 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e 73 61   used for transa
9b70: 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a 2a 2a  ction control.**
9b80: 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c   are automatical
9b90: 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ly deleted when 
9ba0: 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e 6e 65  the latest conne
9bb0: 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64 61 74  ction to the dat
9bc0: 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65 73 2e  abase.** closes.
9bd0: 20 20 53 65 74 74 69 6e 67 20 70 65 72 73 69 73    Setting persis
9be0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 63 61  tent WAL mode ca
9bf0: 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c 65 73  uses those files
9c00: 20 74 6f 20 70 65 72 73 69 73 74 20 61 66 74 65   to persist afte
9c10: 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50 65 72  r.** close.  Per
9c20: 73 69 73 74 69 6e 67 20 74 68 65 20 66 69 6c 65  sisting the file
9c30: 73 20 69 73 20 75 73 65 66 75 6c 20 77 68 65 6e  s is useful when
9c40: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 65 73   other processes
9c50: 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a 2a 20   that do not.** 
9c60: 68 61 76 65 20 77 72 69 74 65 20 70 65 72 6d 69  have write permi
9c70: 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64 69 72  ssion on the dir
9c80: 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e 69 6e  ectory containin
9c90: 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  g the database f
9ca0: 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f 20 72  ile want.** to r
9cb0: 65 61 64 20 74 68 65 20 64 61 74 61 62 61 73 65  ead the database
9cc0: 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20 57 41   file, as the WA
9cd0: 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d 65 6d  L and shared mem
9ce0: 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74 20 65  ory files must e
9cf0: 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64 65 72  xist.** in order
9d00: 20 66 6f 72 20 74 68 65 20 64 61 74 61 62 61 73   for the databas
9d10: 65 20 74 6f 20 62 65 20 72 65 61 64 61 62 6c 65  e to be readable
9d20: 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20 70 61  .  The fourth pa
9d30: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73  rameter to.** [s
9d40: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
9d50: 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73 20  rol()] for this 
9d60: 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62 65  opcode should be
9d70: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
9d80: 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68 61   integer..** Tha
9d90: 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20 74  t integer is 0 t
9da0: 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73 69 73  o disable persis
9db0: 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20 6f 72  tent WAL mode or
9dc0: 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70 65 72   1 to enable per
9dd0: 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c 20 6d  sistent.** WAL m
9de0: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
9df0: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
9e00: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
9e10: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
9e20: 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72 73 69  ent.** WAL persi
9e30: 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67 2e 0a  stence setting..
9e40: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
9e50: 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41  TE_FCNTL_POWERSA
9e60: 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d 0a 2a  FE_OVERWRITE]].*
9e70: 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  * ^The [SQLITE_F
9e80: 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f  CNTL_POWERSAFE_O
9e90: 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65  VERWRITE] opcode
9ea0: 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74 20   is used to set 
9eb0: 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a 20  or query the.** 
9ec0: 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f 77 65  persistent "powe
9ed0: 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74 65 22  rsafe-overwrite"
9ee0: 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74 74 69   or "PSOW" setti
9ef0: 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20 73 65  ng.  The PSOW se
9f00: 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72 6d 69  tting.** determi
9f10: 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  nes the [SQLITE_
9f20: 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f  IOCAP_POWERSAFE_
9f30: 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74 20 6f  OVERWRITE] bit o
9f40: 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69 63 65  f the.** xDevice
9f50: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
9f60: 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66 6f 75  methods. The fou
9f70: 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
9f80: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
9f90: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66 6f 72  e_control()] for
9fa0: 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73 68 6f   this opcode sho
9fb0: 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74 65 72  uld be a pointer
9fc0: 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 2e 0a   to an integer..
9fd0: 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65 72 20  ** That integer 
9fe0: 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20  is 0 to disable 
9ff0: 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f 64 65  zero-damage mode
a000: 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20   or 1 to enable 
a010: 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a 20 6d  zero-damage.** m
a020: 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69 6e 74  ode.  If the int
a030: 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68 65 6e  eger is -1, then
a040: 20 69 74 20 69 73 20 6f 76 65 72 77 72 69 74 74   it is overwritt
a050: 65 6e 20 77 69 74 68 20 74 68 65 20 63 75 72 72  en with the curr
a060: 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61 6d 61  ent.** zero-dama
a070: 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e 67 2e  ge mode setting.
a080: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
a090: 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52  ITE_FCNTL_OVERWR
a0a0: 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53  ITE]].** ^The [S
a0b0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
a0c0: 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73  WRITE] opcode is
a0d0: 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51 4c 69   invoked by SQLi
a0e0: 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69 6e 67  te after opening
a0f0: 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72 61 6e  .** a write tran
a100: 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64 69 63  saction to indic
a110: 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65 73 73  ate that, unless
a120: 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20 62 61   it is rolled ba
a130: 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a 20 72  ck for some.** r
a140: 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74 69 72  eason, the entir
a150: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
a160: 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72 69 74  will be overwrit
a170: 74 65 6e 20 62 79 20 74 68 65 20 63 75 72 72 65  ten by the curre
a180: 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  nt .** transacti
a190: 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73 65 64  on. This is used
a1a0: 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65 72 61   by VACUUM opera
a1b0: 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  tions..**.** <li
a1c0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
a1d0: 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e 54 68  VFSNAME]].** ^Th
a1e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a1f0: 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64 65 20  VFSNAME] opcode 
a200: 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f  can be used to o
a210: 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20  btain the names 
a220: 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53 65 73  of.** all [VFSes
a230: 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 61  ] in the VFS sta
a240: 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73 20 61  ck.  The names a
a250: 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20 73 68  re of all VFS sh
a260: 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 66  ims and the.** f
a270: 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65 76 65  inal bottom-leve
a280: 6c 20 56 46 53 20 61 72 65 20 77 72 69 74 74 65  l VFS are writte
a290: 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62  n into memory ob
a2a0: 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20  tained from .** 
a2b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
a2c0: 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73 75 6c  )] and the resul
a2d0: 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 74  t is stored in t
a2e0: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a2f0: 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 66 6f  e.** that the fo
a300: 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f  urth parameter o
a310: 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  f [sqlite3_file_
a320: 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69 6e 74  control()] point
a330: 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63 61 6c  s to..** The cal
a340: 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73 69 62  ler is responsib
a350: 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67 20 74  le for freeing t
a360: 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e 20 64  he memory when d
a370: 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a 2a 2a  one.  As with.**
a380: 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74 72 6f   all file-contro
a390: 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 72 65  l actions, there
a3a0: 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74 65 65   is no guarantee
a3b0: 20 74 68 61 74 20 74 68 69 73 20 77 69 6c 6c 20   that this will 
a3c0: 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f 20 61  actually.** do a
a3d0: 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c 65 72  nything.  Caller
a3e0: 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69 61 6c  s should initial
a3f0: 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20 76 61  ize the char* va
a400: 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55 4c 4c  riable to a NULL
a410: 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 20 63  .** pointer in c
a420: 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d 63 6f  ase this file-co
a430: 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69 6d 70  ntrol is not imp
a440: 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69 73 20  lemented.  This 
a450: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20  file-control.** 
a460: 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  is intended for 
a470: 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65 20 6f  diagnostic use o
a480: 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  nly..**.** <li>[
a490: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52  [SQLITE_FCNTL_PR
a4a0: 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65 6e 65  AGMA]].** ^Whene
a4b0: 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d 20 73  ver a [PRAGMA] s
a4c0: 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61 72 73  tatement is pars
a4d0: 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45 5f 46  ed, an [SQLITE_F
a4e0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a 2a 2a  CNTL_PRAGMA] .**
a4f0: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73   file control is
a500: 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f 70 65   sent to the ope
a510: 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  n [sqlite3_file]
a520: 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73 70 6f   object correspo
a530: 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68 65 20  nding.** to the 
a540: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 6f  database file to
a550: 20 77 68 69 63 68 20 74 68 65 20 70 72 61 67 6d   which the pragm
a560: 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65 66 65  a statement refe
a570: 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d 65 6e  rs. ^The argumen
a580: 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53 51 4c  t.** to the [SQL
a590: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
a5a0: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69  ] file control i
a5b0: 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a 2a 2a  s an array of.**
a5c0: 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72   pointers to str
a5d0: 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20 69 6e  ings (char**) in
a5e0: 20 77 68 69 63 68 20 74 68 65 20 73 65 63 6f 6e   which the secon
a5f0: 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74 68 65  d element of the
a600: 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74 68 65   array.** is the
a610: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70 72 61   name of the pra
a620: 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68 69 72  gma and the thir
a630: 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74 68 65  d element is the
a640: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
a650: 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20 4e 55  .** pragma or NU
a660: 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  LL if the pragma
a670: 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65 6e 74   has no argument
a680: 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 20  .  ^The handler 
a690: 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c 49 54  for an.** [SQLIT
a6a0: 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20  E_FCNTL_PRAGMA] 
a6b0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63 61 6e  file control can
a6c0: 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61 6b 65   optionally make
a6d0: 20 74 68 65 20 66 69 72 73 74 20 65 6c 65 6d 65   the first eleme
a6e0: 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63 68 61  nt.** of the cha
a6f0: 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70 6f 69  r** argument poi
a700: 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67 20 6f  nt to a string o
a710: 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
a720: 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 29 5d  lite3_mprintf()]
a730: 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75 69 76  .** or the equiv
a740: 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74 20 73  alent and that s
a750: 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63 6f 6d  tring will becom
a760: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20  e the result of 
a770: 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a 2a 2a  the pragma or.**
a780: 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
a790: 67 65 20 69 66 20 74 68 65 20 70 72 61 67 6d 61  ge if the pragma
a7a0: 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68 65 0a   fails. ^If the.
a7b0: 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ** [SQLITE_FCNTL
a7c0: 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20 63 6f  _PRAGMA] file co
a7d0: 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20 5b 53  ntrol returns [S
a7e0: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a7f0: 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a 2a 2a   then normal .**
a800: 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63 65 73   [PRAGMA] proces
a810: 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73 2e 20  sing continues. 
a820: 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54 45   ^If the [SQLITE
a830: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 0a 2a  _FCNTL_PRAGMA].*
a840: 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72  * file control r
a850: 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
a860: 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70 61 72  K], then the par
a870: 73 65 72 20 61 73 73 75 6d 65 73 20 74 68 61 74  ser assumes that
a880: 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61 73 20   the.** VFS has 
a890: 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52 41 47  handled the PRAG
a8a0: 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20 74 68  MA itself and th
a8b0: 65 20 70 61 72 73 65 72 20 67 65 6e 65 72 61 74  e parser generat
a8c0: 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20 70 72  es a no-op.** pr
a8d0: 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
a8e0: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
a8f0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a900: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 72 65   file control re
a910: 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72 65 73  turns.** any res
a920: 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72 20 74  ult code other t
a930: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  han [SQLITE_OK] 
a940: 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  or [SQLITE_NOTFO
a950: 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73  UND], that means
a960: 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56 46 53  .** that the VFS
a970: 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61 6e 20   encountered an 
a980: 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61 6e 64  error while hand
a990: 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47 4d 41  ling the [PRAGMA
a9a0: 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63 6f 6d  ] and the.** com
a9b0: 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  pilation of the 
a9c0: 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77 69 74  PRAGMA fails wit
a9d0: 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e 54 68  h an error.  ^Th
a9e0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
a9f0: 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c 65 20  PRAGMA].** file 
aa00: 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73 20 61  control occurs a
aa10: 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  t the beginning 
aa20: 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74 65 6d  of pragma statem
aa30: 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61 6e 64  ent analysis and
aa40: 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61 62 6c   so.** it is abl
aa50: 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20 62 75  e to override bu
aa60: 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41 5d 20  ilt-in [PRAGMA] 
aa70: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
aa80: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
aa90: 43 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52  CNTL_BUSYHANDLER
aaa0: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  ]].** ^The [SQLI
aab0: 54 45 5f 46 43 4e 54 4c 5f 42 55 53 59 48 41 4e  TE_FCNTL_BUSYHAN
aac0: 44 4c 45 52 5d 0a 2a 2a 20 66 69 6c 65 2d 63 6f  DLER].** file-co
aad0: 6e 74 72 6f 6c 20 6d 61 79 20 62 65 20 69 6e 76  ntrol may be inv
aae0: 6f 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 6f  oked by SQLite o
aaf0: 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  n the database f
ab00: 69 6c 65 20 68 61 6e 64 6c 65 0a 2a 2a 20 73 68  ile handle.** sh
ab10: 6f 72 74 6c 79 20 61 66 74 65 72 20 69 74 20 69  ortly after it i
ab20: 73 20 6f 70 65 6e 65 64 20 69 6e 20 6f 72 64 65  s opened in orde
ab30: 72 20 74 6f 20 70 72 6f 76 69 64 65 20 61 20 63  r to provide a c
ab40: 75 73 74 6f 6d 20 56 46 53 20 77 69 74 68 20 61  ustom VFS with a
ab50: 63 63 65 73 73 0a 2a 2a 20 74 6f 20 74 68 65 20  ccess.** to the 
ab60: 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 62 75 73 79  connections busy
ab70: 2d 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63  -handler callbac
ab80: 6b 2e 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20  k. The argument 
ab90: 69 73 20 6f 66 20 74 79 70 65 20 28 76 6f 69 64  is of type (void
aba0: 20 2a 2a 29 0a 2a 2a 20 2d 20 61 6e 20 61 72 72   **).** - an arr
abb0: 61 79 20 6f 66 20 74 77 6f 20 28 76 6f 69 64 20  ay of two (void 
abc0: 2a 29 20 76 61 6c 75 65 73 2e 20 54 68 65 20 66  *) values. The f
abd0: 69 72 73 74 20 28 76 6f 69 64 20 2a 29 20 61 63  irst (void *) ac
abe0: 74 75 61 6c 6c 79 20 70 6f 69 6e 74 73 0a 2a 2a  tually points.**
abf0: 20 74 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f   to a function o
ac00: 66 20 74 79 70 65 20 28 69 6e 74 20 28 2a 29 28  f type (int (*)(
ac10: 76 6f 69 64 20 2a 29 29 2e 20 49 6e 20 6f 72 64  void *)). In ord
ac20: 65 72 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  er to invoke the
ac30: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
ac40: 62 75 73 79 2d 68 61 6e 64 6c 65 72 2c 20 74 68  busy-handler, th
ac50: 69 73 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  is function shou
ac60: 6c 64 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ld be invoked wi
ac70: 74 68 20 74 68 65 20 73 65 63 6f 6e 64 20 28 76  th the second (v
ac80: 6f 69 64 20 2a 29 20 69 6e 0a 2a 2a 20 74 68 65  oid *) in.** the
ac90: 20 61 72 72 61 79 20 61 73 20 74 68 65 20 6f 6e   array as the on
aca0: 6c 79 20 61 72 67 75 6d 65 6e 74 2e 20 49 66 20  ly argument. If 
acb0: 69 74 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  it returns non-z
acc0: 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 6f 70  ero, then the op
acd0: 65 72 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c  eration.** shoul
ace0: 64 20 62 65 20 72 65 74 72 69 65 64 2e 20 49 66  d be retried. If
acf0: 20 69 74 20 72 65 74 75 72 6e 73 20 7a 65 72 6f   it returns zero
ad00: 2c 20 74 68 65 20 63 75 73 74 6f 6d 20 56 46 53  , the custom VFS
ad10: 20 73 68 6f 75 6c 64 20 61 62 61 6e 64 6f 6e 20   should abandon 
ad20: 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 20 6f  the.** current o
ad30: 70 65 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  peration..**.** 
ad40: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
ad50: 54 4c 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 5d  TL_TEMPFILENAME]
ad60: 5d 0a 2a 2a 20 5e 41 70 70 6c 69 63 61 74 69 6f  ].** ^Applicatio
ad70: 6e 20 63 61 6e 20 69 6e 76 6f 6b 65 20 74 68 65  n can invoke the
ad80: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
ad90: 45 4d 50 46 49 4c 45 4e 41 4d 45 5d 20 66 69 6c  EMPFILENAME] fil
ada0: 65 2d 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 74 6f 20  e-control.** to 
adb0: 68 61 76 65 20 53 51 4c 69 74 65 20 67 65 6e 65  have SQLite gene
adc0: 72 61 74 65 20 61 0a 2a 2a 20 74 65 6d 70 6f 72  rate a.** tempor
add0: 61 72 79 20 66 69 6c 65 6e 61 6d 65 20 75 73 69  ary filename usi
ade0: 6e 67 20 74 68 65 20 73 61 6d 65 20 61 6c 67 6f  ng the same algo
adf0: 72 69 74 68 6d 20 74 68 61 74 20 69 73 20 66 6f  rithm that is fo
ae00: 6c 6c 6f 77 65 64 20 74 6f 20 67 65 6e 65 72 61  llowed to genera
ae10: 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20  te.** temporary 
ae20: 66 69 6c 65 6e 61 6d 65 73 20 66 6f 72 20 54 45  filenames for TE
ae30: 4d 50 20 74 61 62 6c 65 73 20 61 6e 64 20 6f 74  MP tables and ot
ae40: 68 65 72 20 69 6e 74 65 72 6e 61 6c 20 75 73 65  her internal use
ae50: 73 2e 20 20 54 68 65 0a 2a 2a 20 61 72 67 75 6d  s.  The.** argum
ae60: 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 61 20  ent should be a 
ae70: 63 68 61 72 2a 2a 20 77 68 69 63 68 20 77 69 6c  char** which wil
ae80: 6c 20 62 65 20 66 69 6c 6c 65 64 20 77 69 74 68  l be filled with
ae90: 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a   the filename.**
aea0: 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 6d 65   written into me
aeb0: 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
aec0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
aed0: 6f 63 28 29 5d 2e 20 20 54 68 65 20 63 61 6c 6c  oc()].  The call
aee0: 65 72 20 73 68 6f 75 6c 64 0a 2a 2a 20 69 6e 76  er should.** inv
aef0: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
af00: 65 28 29 5d 20 6f 6e 20 74 68 65 20 72 65 73 75  e()] on the resu
af10: 6c 74 20 74 6f 20 61 76 6f 69 64 20 61 20 6d 65  lt to avoid a me
af20: 6d 6f 72 79 20 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a  mory leak..**.**
af30: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
af40: 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d 0a  NTL_MMAP_SIZE]].
af50: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
af60: 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20  CNTL_MMAP_SIZE] 
af70: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20  file control is 
af80: 75 73 65 64 20 74 6f 20 71 75 65 72 79 20 6f 72  used to query or
af90: 20 73 65 74 20 74 68 65 0a 2a 2a 20 6d 61 78 69   set the.** maxi
afa0: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  mum number of by
afb0: 74 65 73 20 74 68 61 74 20 77 69 6c 6c 20 62 65  tes that will be
afc0: 20 75 73 65 64 20 66 6f 72 20 6d 65 6d 6f 72 79   used for memory
afd0: 2d 6d 61 70 70 65 64 20 49 2f 4f 2e 0a 2a 2a 20  -mapped I/O..** 
afe0: 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  The argument is 
aff0: 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76  a pointer to a v
b000: 61 6c 75 65 20 6f 66 20 74 79 70 65 20 73 71 6c  alue of type sql
b010: 69 74 65 33 5f 69 6e 74 36 34 20 74 68 61 74 0a  ite3_int64 that.
b020: 2a 2a 20 69 73 20 61 6e 20 61 64 76 69 73 6f 72  ** is an advisor
b030: 79 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  y maximum number
b040: 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
b050: 20 66 69 6c 65 20 74 6f 20 6d 65 6d 6f 72 79 20   file to memory 
b060: 6d 61 70 2e 20 20 54 68 65 0a 2a 2a 20 70 6f 69  map.  The.** poi
b070: 6e 74 65 72 20 69 73 20 6f 76 65 72 77 72 69 74  nter is overwrit
b080: 74 65 6e 20 77 69 74 68 20 74 68 65 20 6f 6c 64  ten with the old
b090: 20 76 61 6c 75 65 2e 20 20 54 68 65 20 6c 69 6d   value.  The lim
b0a0: 69 74 20 69 73 20 6e 6f 74 20 63 68 61 6e 67 65  it is not change
b0b0: 64 20 69 66 0a 2a 2a 20 74 68 65 20 76 61 6c 75  d if.** the valu
b0c0: 65 20 6f 72 69 67 69 6e 61 6c 6c 79 20 70 6f 69  e originally poi
b0d0: 6e 74 65 64 20 74 6f 20 69 73 20 6e 65 67 61 74  nted to is negat
b0e0: 69 76 65 2c 20 61 6e 64 20 73 6f 20 74 68 65 20  ive, and so the 
b0f0: 63 75 72 72 65 6e 74 20 6c 69 6d 69 74 20 0a 2a  current limit .*
b100: 2a 20 63 61 6e 20 62 65 20 71 75 65 72 69 65 64  * can be queried
b110: 20 62 79 20 70 61 73 73 69 6e 67 20 69 6e 20 61   by passing in a
b120: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6e 65   pointer to a ne
b130: 67 61 74 69 76 65 20 6e 75 6d 62 65 72 2e 20 20  gative number.  
b140: 54 68 69 73 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e  This.** file-con
b150: 74 72 6f 6c 20 69 73 20 75 73 65 64 20 69 6e 74  trol is used int
b160: 65 72 6e 61 6c 6c 79 20 74 6f 20 69 6d 70 6c 65  ernally to imple
b170: 6d 65 6e 74 20 5b 50 52 41 47 4d 41 20 6d 6d 61  ment [PRAGMA mma
b180: 70 5f 73 69 7a 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  p_size]..**.** <
b190: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
b1a0: 4c 5f 54 52 41 43 45 5d 5d 0a 2a 2a 20 54 68 65  L_TRACE]].** The
b1b0: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54   [SQLITE_FCNTL_T
b1c0: 52 41 43 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72  RACE] file contr
b1d0: 6f 6c 20 70 72 6f 76 69 64 65 73 20 61 64 76 69  ol provides advi
b1e0: 73 6f 72 79 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  sory information
b1f0: 0a 2a 2a 20 74 6f 20 74 68 65 20 56 46 53 20 61  .** to the VFS a
b200: 62 6f 75 74 20 77 68 61 74 20 74 68 65 20 68 69  bout what the hi
b210: 67 68 65 72 20 6c 61 79 65 72 73 20 6f 66 20 74  gher layers of t
b220: 68 65 20 53 51 4c 69 74 65 20 73 74 61 63 6b 20  he SQLite stack 
b230: 61 72 65 20 64 6f 69 6e 67 2e 0a 2a 2a 20 54 68  are doing..** Th
b240: 69 73 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  is file control 
b250: 69 73 20 75 73 65 64 20 62 79 20 73 6f 6d 65 20  is used by some 
b260: 56 46 53 20 61 63 74 69 76 69 74 79 20 74 72 61  VFS activity tra
b270: 63 69 6e 67 20 5b 73 68 69 6d 73 5d 2e 0a 2a 2a  cing [shims]..**
b280: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
b290: 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
b2a0: 65 64 20 73 74 72 69 6e 67 2e 20 20 48 69 67 68  ed string.  High
b2b0: 65 72 20 6c 61 79 65 72 73 20 69 6e 20 74 68 65  er layers in the
b2c0: 0a 2a 2a 20 53 51 4c 69 74 65 20 73 74 61 63 6b  .** SQLite stack
b2d0: 20 6d 61 79 20 67 65 6e 65 72 61 74 65 20 69 6e   may generate in
b2e0: 73 74 61 6e 63 65 73 20 6f 66 20 74 68 69 73 20  stances of this 
b2f0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 66 0a  file control if.
b300: 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 55  ** the [SQLITE_U
b310: 53 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d 20  SE_FCNTL_TRACE] 
b320: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
b330: 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a  ion is enabled..
b340: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
b350: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b360: 45 44 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  ED]].** The [SQL
b370: 49 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f  ITE_FCNTL_HAS_MO
b380: 56 45 44 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f  VED] file contro
b390: 6c 20 69 6e 74 65 72 70 72 65 74 73 20 69 74 73  l interprets its
b3a0: 20 61 72 67 75 6d 65 6e 74 20 61 73 20 61 0a 2a   argument as a.*
b3b0: 2a 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  * pointer to an 
b3c0: 69 6e 74 65 67 65 72 20 61 6e 64 20 69 74 20 77  integer and it w
b3d0: 72 69 74 65 73 20 61 20 62 6f 6f 6c 65 61 6e 20  rites a boolean 
b3e0: 69 6e 74 6f 20 74 68 61 74 20 69 6e 74 65 67 65  into that intege
b3f0: 72 20 64 65 70 65 6e 64 69 6e 67 0a 2a 2a 20 6f  r depending.** o
b400: 6e 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  n whether or not
b410: 20 74 68 65 20 66 69 6c 65 20 68 61 73 20 62 65   the file has be
b420: 65 6e 20 72 65 6e 61 6d 65 64 2c 20 6d 6f 76 65  en renamed, move
b430: 64 2c 20 6f 72 20 64 65 6c 65 74 65 64 20 73 69  d, or deleted si
b440: 6e 63 65 20 69 74 0a 2a 2a 20 77 61 73 20 66 69  nce it.** was fi
b450: 72 73 74 20 6f 70 65 6e 65 64 2e 0a 2a 2a 0a 2a  rst opened..**.*
b460: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
b470: 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f 48  CNTL_WIN32_SET_H
b480: 41 4e 44 4c 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b  ANDLE]].** The [
b490: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e  SQLITE_FCNTL_WIN
b4a0: 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45 5d 20 6f  32_SET_HANDLE] o
b4b0: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
b4c0: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
b4d0: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
b4e0: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
b4f0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 73  trol method to s
b500: 77 61 70 20 74 68 65 20 66 69 6c 65 20 68 61 6e  wap the file han
b510: 64 6c 65 20 77 69 74 68 20 74 68 65 20 6f 6e 65  dle with the one
b520: 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  .** pointed to b
b530: 79 20 74 68 65 20 70 41 72 67 20 61 72 67 75 6d  y the pArg argum
b540: 65 6e 74 2e 20 20 54 68 69 73 20 63 61 70 61 62  ent.  This capab
b550: 69 6c 69 74 79 20 69 73 20 75 73 65 64 20 64 75  ility is used du
b560: 72 69 6e 67 20 74 65 73 74 69 6e 67 0a 2a 2a 20  ring testing.** 
b570: 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64 73 20 74  and only needs t
b580: 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64 20 77  o be supported w
b590: 68 65 6e 20 53 51 4c 49 54 45 5f 54 45 53 54 20  hen SQLITE_TEST 
b5a0: 69 73 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a  is defined..**.*
b5b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69  * </ul>.*/.#defi
b5c0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b5d0: 4c 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20  LOCKSTATE       
b5e0: 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
b5f0: 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43  e SQLITE_GET_LOC
b600: 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20  KPROXYFILE      
b610: 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65         2.#define
b620: 20 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b   SQLITE_SET_LOCK
b630: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
b640: 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20        3.#define 
b650: 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e  SQLITE_LAST_ERRN
b660: 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  O               
b670: 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53       4.#define S
b680: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
b690: 5f 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  _HINT           
b6a0: 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51      5.#define SQ
b6b0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
b6c0: 5f 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20  _SIZE           
b6d0: 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
b6e0: 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50  ITE_FCNTL_FILE_P
b6f0: 4f 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20  OINTER          
b700: 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
b710: 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d  TE_FCNTL_SYNC_OM
b720: 49 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20  ITTED           
b730: 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
b740: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56  E_FCNTL_WIN32_AV
b750: 5f 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20  _RETRY          
b760: 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  9.#define SQLITE
b770: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
b780: 41 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30  AL            10
b790: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b7a0: 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20  FCNTL_OVERWRITE 
b7b0: 20 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a               11.
b7c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b7d0: 43 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20  CNTL_VFSNAME    
b7e0: 20 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23              12.#
b7f0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b800: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
b810: 45 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64  ERWRITE    13.#d
b820: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b830: 54 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20  TL_PRAGMA       
b840: 20 20 20 20 20 20 20 20 20 20 31 34 0a 23 64 65            14.#de
b850: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b860: 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 20 20 20  L_BUSYHANDLER   
b870: 20 20 20 20 20 20 20 20 20 31 35 0a 23 64 65 66           15.#def
b880: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b890: 5f 54 45 4d 50 46 49 4c 45 4e 41 4d 45 20 20 20  _TEMPFILENAME   
b8a0: 20 20 20 20 20 20 20 20 31 36 0a 23 64 65 66 69          16.#defi
b8b0: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b8c0: 4d 4d 41 50 5f 53 49 5a 45 20 20 20 20 20 20 20  MMAP_SIZE       
b8d0: 20 20 20 20 20 20 20 31 38 0a 23 64 65 66 69 6e         18.#defin
b8e0: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54  e SQLITE_FCNTL_T
b8f0: 52 41 43 45 20 20 20 20 20 20 20 20 20 20 20 20  RACE            
b900: 20 20 20 20 20 20 31 39 0a 23 64 65 66 69 6e 65        19.#define
b910: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 48 41   SQLITE_FCNTL_HA
b920: 53 5f 4d 4f 56 45 44 20 20 20 20 20 20 20 20 20  S_MOVED         
b930: 20 20 20 20 20 32 30 0a 23 64 65 66 69 6e 65 20       20.#define 
b940: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e  SQLITE_FCNTL_SYN
b950: 43 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  C               
b960: 20 20 20 20 32 31 0a 23 64 65 66 69 6e 65 20 53      21.#define S
b970: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f 4d 4d  QLITE_FCNTL_COMM
b980: 49 54 5f 50 48 41 53 45 54 57 4f 20 20 20 20 20  IT_PHASETWO     
b990: 20 20 20 32 32 0a 23 64 65 66 69 6e 65 20 53 51     22.#define SQ
b9a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32  LITE_FCNTL_WIN32
b9b0: 5f 53 45 54 5f 48 41 4e 44 4c 45 20 20 20 20 20  _SET_HANDLE     
b9c0: 20 20 32 33 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    23../*.** CAPI
b9d0: 33 52 45 46 3a 20 4d 75 74 65 78 20 48 61 6e 64  3REF: Mutex Hand
b9e0: 6c 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6d 75 74  le.**.** The mut
b9f0: 65 78 20 6d 6f 64 75 6c 65 20 77 69 74 68 69 6e  ex module within
ba00: 20 53 51 4c 69 74 65 20 64 65 66 69 6e 65 73 20   SQLite defines 
ba10: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
ba20: 74 6f 20 62 65 20 61 6e 0a 2a 2a 20 61 62 73 74  to be an.** abst
ba30: 72 61 63 74 20 74 79 70 65 20 66 6f 72 20 61 20  ract type for a 
ba40: 6d 75 74 65 78 20 6f 62 6a 65 63 74 2e 20 20 54  mutex object.  T
ba50: 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 6e  he SQLite core n
ba60: 65 76 65 72 20 6c 6f 6f 6b 73 0a 2a 2a 20 61 74  ever looks.** at
ba70: 20 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65   the internal re
ba80: 70 72 65 73 65 6e 74 61 74 69 6f 6e 20 6f 66 20  presentation of 
ba90: 61 6e 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  an [sqlite3_mute
baa0: 78 5d 2e 20 20 49 74 20 6f 6e 6c 79 0a 2a 2a 20  x].  It only.** 
bab0: 64 65 61 6c 73 20 77 69 74 68 20 70 6f 69 6e 74  deals with point
bac0: 65 72 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ers to the [sqli
bad0: 74 65 33 5f 6d 75 74 65 78 5d 20 6f 62 6a 65 63  te3_mutex] objec
bae0: 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75 74 65 78 65 73  t..**.** Mutexes
baf0: 20 61 72 65 20 63 72 65 61 74 65 64 20 75 73 69   are created usi
bb00: 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
bb10: 78 5f 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 74  x_alloc()]..*/.t
bb20: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
bb30: 6c 69 74 65 33 5f 6d 75 74 65 78 20 73 71 6c 69  lite3_mutex sqli
bb40: 74 65 33 5f 6d 75 74 65 78 3b 0a 0a 2f 2a 0a 2a  te3_mutex;../*.*
bb50: 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20 49  * CAPI3REF: OS I
bb60: 6e 74 65 72 66 61 63 65 20 4f 62 6a 65 63 74 0a  nterface Object.
bb70: 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
bb80: 65 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33  e of the sqlite3
bb90: 5f 76 66 73 20 6f 62 6a 65 63 74 20 64 65 66 69  _vfs object defi
bba0: 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63  nes the interfac
bbb0: 65 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  e between.** the
bbc0: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 61 6e 64   SQLite core and
bbd0: 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
bbe0: 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d  operating system
bbf0: 2e 20 20 54 68 65 20 22 76 66 73 22 0a 2a 2a 20  .  The "vfs".** 
bc00: 69 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  in the name of t
bc10: 68 65 20 6f 62 6a 65 63 74 20 73 74 61 6e 64 73  he object stands
bc20: 20 66 6f 72 20 22 76 69 72 74 75 61 6c 20 66 69   for "virtual fi
bc30: 6c 65 20 73 79 73 74 65 6d 22 2e 20 20 53 65 65  le system".  See
bc40: 0a 2a 2a 20 74 68 65 20 5b 56 46 53 20 7c 20 56  .** the [VFS | V
bc50: 46 53 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  FS documentation
bc60: 5d 20 66 6f 72 20 66 75 72 74 68 65 72 20 69 6e  ] for further in
bc70: 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
bc80: 20 54 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   The value of th
bc90: 65 20 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64  e iVersion field
bca0: 20 69 73 20 69 6e 69 74 69 61 6c 6c 79 20 31 20   is initially 1 
bcb0: 62 75 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65  but may be large
bcc0: 72 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65 20 76  r in.** future v
bcd0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
bce0: 65 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 20 66  e.  Additional f
bcf0: 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70 70  ields may be app
bd00: 65 6e 64 65 64 20 74 6f 20 74 68 69 73 0a 2a 2a  ended to this.**
bd10: 20 6f 62 6a 65 63 74 20 77 68 65 6e 20 74 68 65   object when the
bd20: 20 69 56 65 72 73 69 6f 6e 20 76 61 6c 75 65 20   iVersion value 
bd30: 69 73 20 69 6e 63 72 65 61 73 65 64 2e 20 20 4e  is increased.  N
bd40: 6f 74 65 20 74 68 61 74 20 74 68 65 20 73 74 72  ote that the str
bd50: 75 63 74 75 72 65 0a 2a 2a 20 6f 66 20 74 68 65  ucture.** of the
bd60: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
bd70: 65 63 74 20 63 68 61 6e 67 65 73 20 69 6e 20 74  ect changes in t
bd80: 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 62  he transaction b
bd90: 65 74 77 65 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  etween.** SQLite
bda0: 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 39 20 61   version 3.5.9 a
bdb0: 6e 64 20 33 2e 36 2e 30 20 61 6e 64 20 79 65 74  nd 3.6.0 and yet
bdc0: 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 66 69   the iVersion fi
bdd0: 65 6c 64 20 77 61 73 20 6e 6f 74 0a 2a 2a 20 6d  eld was not.** m
bde0: 6f 64 69 66 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  odified..**.** T
bdf0: 68 65 20 73 7a 4f 73 46 69 6c 65 20 66 69 65 6c  he szOsFile fiel
be00: 64 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  d is the size of
be10: 20 74 68 65 20 73 75 62 63 6c 61 73 73 65 64 20   the subclassed 
be20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 0a 2a  [sqlite3_file].*
be30: 2a 20 73 74 72 75 63 74 75 72 65 20 75 73 65 64  * structure used
be40: 20 62 79 20 74 68 69 73 20 56 46 53 2e 20 20 6d   by this VFS.  m
be50: 78 50 61 74 68 6e 61 6d 65 20 69 73 20 74 68 65  xPathname is the
be60: 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   maximum length 
be70: 6f 66 0a 2a 2a 20 61 20 70 61 74 68 6e 61 6d 65  of.** a pathname
be80: 20 69 6e 20 74 68 69 73 20 56 46 53 2e 0a 2a 2a   in this VFS..**
be90: 0a 2a 2a 20 52 65 67 69 73 74 65 72 65 64 20 73  .** Registered s
bea0: 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63  qlite3_vfs objec
beb0: 74 73 20 61 72 65 20 6b 65 70 74 20 6f 6e 20 61  ts are kept on a
bec0: 20 6c 69 6e 6b 65 64 20 6c 69 73 74 20 66 6f 72   linked list for
bed0: 6d 65 64 20 62 79 0a 2a 2a 20 74 68 65 20 70 4e  med by.** the pN
bee0: 65 78 74 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ext pointer.  Th
bef0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 72  e [sqlite3_vfs_r
bf00: 65 67 69 73 74 65 72 28 29 5d 0a 2a 2a 20 61 6e  egister()].** an
bf10: 64 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 75  d [sqlite3_vfs_u
bf20: 6e 72 65 67 69 73 74 65 72 28 29 5d 20 69 6e 74  nregister()] int
bf30: 65 72 66 61 63 65 73 20 6d 61 6e 61 67 65 20 74  erfaces manage t
bf40: 68 69 73 20 6c 69 73 74 0a 2a 2a 20 69 6e 20 61  his list.** in a
bf50: 20 74 68 72 65 61 64 2d 73 61 66 65 20 77 61 79   thread-safe way
bf60: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
bf70: 76 66 73 5f 66 69 6e 64 28 29 5d 20 69 6e 74 65  vfs_find()] inte
bf80: 72 66 61 63 65 0a 2a 2a 20 73 65 61 72 63 68 65  rface.** searche
bf90: 73 20 74 68 65 20 6c 69 73 74 2e 20 20 4e 65 69  s the list.  Nei
bfa0: 74 68 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  ther the applica
bfb0: 74 69 6f 6e 20 63 6f 64 65 20 6e 6f 72 20 74 68  tion code nor th
bfc0: 65 20 56 46 53 0a 2a 2a 20 69 6d 70 6c 65 6d 65  e VFS.** impleme
bfd0: 6e 74 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75  ntation should u
bfe0: 73 65 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  se the pNext poi
bff0: 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nter..**.** The 
c000: 70 4e 65 78 74 20 66 69 65 6c 64 20 69 73 20 74  pNext field is t
c010: 68 65 20 6f 6e 6c 79 20 66 69 65 6c 64 20 69 6e  he only field in
c020: 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73   the sqlite3_vfs
c030: 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 20 74 68  .** structure th
c040: 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65  at SQLite will e
c050: 76 65 72 20 6d 6f 64 69 66 79 2e 20 20 53 51 4c  ver modify.  SQL
c060: 69 74 65 20 77 69 6c 6c 20 6f 6e 6c 79 20 61 63  ite will only ac
c070: 63 65 73 73 0a 2a 2a 20 6f 72 20 6d 6f 64 69 66  cess.** or modif
c080: 79 20 74 68 69 73 20 66 69 65 6c 64 20 77 68 69  y this field whi
c090: 6c 65 20 68 6f 6c 64 69 6e 67 20 61 20 70 61 72  le holding a par
c0a0: 74 69 63 75 6c 61 72 20 73 74 61 74 69 63 20 6d  ticular static m
c0b0: 75 74 65 78 2e 0a 2a 2a 20 54 68 65 20 61 70 70  utex..** The app
c0c0: 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  lication should 
c0d0: 6e 65 76 65 72 20 6d 6f 64 69 66 79 20 61 6e 79  never modify any
c0e0: 74 68 69 6e 67 20 77 69 74 68 69 6e 20 74 68 65  thing within the
c0f0: 20 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20   sqlite3_vfs.** 
c100: 6f 62 6a 65 63 74 20 6f 6e 63 65 20 74 68 65 20  object once the 
c110: 6f 62 6a 65 63 74 20 68 61 73 20 62 65 65 6e 20  object has been 
c120: 72 65 67 69 73 74 65 72 65 64 2e 0a 2a 2a 0a 2a  registered..**.*
c130: 2a 20 54 68 65 20 7a 4e 61 6d 65 20 66 69 65 6c  * The zName fiel
c140: 64 20 68 6f 6c 64 73 20 74 68 65 20 6e 61 6d 65  d holds the name
c150: 20 6f 66 20 74 68 65 20 56 46 53 20 6d 6f 64 75   of the VFS modu
c160: 6c 65 2e 20 20 54 68 65 20 6e 61 6d 65 20 6d 75  le.  The name mu
c170: 73 74 0a 2a 2a 20 62 65 20 75 6e 69 71 75 65 20  st.** be unique 
c180: 61 63 72 6f 73 73 20 61 6c 6c 20 56 46 53 20 6d  across all VFS m
c190: 6f 64 75 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  odules..**.** [[
c1a0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
c1b0: 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  n]].** ^SQLite g
c1c0: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
c1d0: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
c1e0: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
c1f0: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
c200: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
c210: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
c220: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
c230: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
c240: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
c250: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
c260: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
c270: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
c280: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
c290: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
c2a0: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
c2b0: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
c2c0: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
c2d0: 0a 2a 2a 20 31 31 20 61 6c 70 68 61 6e 75 6d 65  .** 11 alphanume
c2e0: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
c2f0: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
c300: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
c310: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
c320: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
c330: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
c340: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
c350: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
c360: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
c370: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
c380: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
c390: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
c3a0: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
c3b0: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
c3c0: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
c3d0: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
c3e0: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
c3f0: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
c400: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
c410: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
c420: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
c430: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
c440: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
c450: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
c460: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
c470: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
c480: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
c490: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
c4a0: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
c4b0: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
c4c0: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
c4d0: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
c4e0: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
c4f0: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
c500: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
c510: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
c520: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
c530: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
c540: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
c550: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
c560: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
c570: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
c580: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
c590: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
c5a0: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
c5b0: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
c5c0: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
c5d0: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
c5e0: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
c5f0: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
c600: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
c610: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
c620: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
c630: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
c640: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
c650: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
c660: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
c670: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
c680: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
c690: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
c6a0: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
c6b0: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
c6c0: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
c6d0: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
c6e0: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
c6f0: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
c700: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
c710: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
c720: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
c730: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
c740: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
c750: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
c760: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
c770: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
c780: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
c790: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
c7a0: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
c7b0: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c7c0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
c7d0: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
c7e0: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
c7f0: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
c800: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
c810: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
c820: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
c830: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
c840: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
c850: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
c860: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
c870: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
c880: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
c890: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
c8a0: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
c8b0: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
c8c0: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
c8d0: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
c8e0: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
c8f0: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
c900: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
c910: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
c920: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
c930: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
c940: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
c950: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
c960: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
c970: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
c980: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
c990: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
c9a0: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
c9b0: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
c9c0: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
c9d0: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
c9e0: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
c9f0: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
ca00: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
ca10: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
ca20: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
ca30: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
ca40: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
ca50: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
ca60: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
ca70: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
ca80: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
ca90: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
caa0: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
cab0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
cac0: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
cad0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
cae0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
caf0: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
cb00: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
cb10: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
cb20: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
cb30: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
cb40: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
cb50: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
cb60: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
cb70: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
cb80: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
cb90: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
cba0: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
cbb0: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
cbc0: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
cbd0: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
cbe0: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
cbf0: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
cc00: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
cc10: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
cc20: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
cc30: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
cc40: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
cc50: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
cc60: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
cc70: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
cc80: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
cc90: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
cca0: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
ccb0: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
ccc0: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
ccd0: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
cce0: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
ccf0: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
cd00: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
cd10: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
cd20: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
cd30: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
cd40: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
cd50: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
cd60: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
cd70: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
cd80: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
cd90: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
cda0: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
cdb0: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
cdc0: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
cdd0: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
cde0: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
cdf0: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
ce00: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
ce10: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
ce20: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
ce30: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
ce40: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
ce50: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
ce60: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
ce70: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
ce80: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
ce90: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
cea0: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
ceb0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
cec0: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
ced0: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
cee0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
cef0: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
cf00: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
cf10: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
cf20: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
cf30: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
cf40: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
cf50: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cf60: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
cf70: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
cf80: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
cf90: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
cfa0: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
cfb0: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
cfc0: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
cfd0: 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 41  [[sqlite3_vfs.xA
cfe0: 63 63 65 73 73 5d 5d 0a 2a 2a 20 5e 54 68 65 20  ccess]].** ^The 
cff0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
d000: 6f 20 78 41 63 63 65 73 73 28 29 20 6d 61 79 20  o xAccess() may 
d010: 62 65 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53  be [SQLITE_ACCES
d020: 53 5f 45 58 49 53 54 53 5d 0a 2a 2a 20 74 6f 20  S_EXISTS].** to 
d030: 74 65 73 74 20 66 6f 72 20 74 68 65 20 65 78 69  test for the exi
d040: 73 74 65 6e 63 65 20 6f 66 20 61 20 66 69 6c 65  stence of a file
d050: 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43 43  , or [SQLITE_ACC
d060: 45 53 53 5f 52 45 41 44 57 52 49 54 45 5d 20 74  ESS_READWRITE] t
d070: 6f 0a 2a 2a 20 74 65 73 74 20 77 68 65 74 68 65  o.** test whethe
d080: 72 20 61 20 66 69 6c 65 20 69 73 20 72 65 61 64  r a file is read
d090: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
d0a0: 65 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 41 43  e, or [SQLITE_AC
d0b0: 43 45 53 53 5f 52 45 41 44 5d 0a 2a 2a 20 74 6f  CESS_READ].** to
d0c0: 20 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20   test whether a 
d0d0: 66 69 6c 65 20 69 73 20 61 74 20 6c 65 61 73 74  file is at least
d0e0: 20 72 65 61 64 61 62 6c 65 2e 20 20 20 54 68 65   readable.   The
d0f0: 20 66 69 6c 65 20 63 61 6e 20 62 65 20 61 0a 2a   file can be a.*
d100: 2a 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  * directory..**.
d110: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
d120: 61 6c 77 61 79 73 20 61 6c 6c 6f 63 61 74 65 20  always allocate 
d130: 61 74 20 6c 65 61 73 74 20 6d 78 50 61 74 68 6e  at least mxPathn
d140: 61 6d 65 2b 31 20 62 79 74 65 73 20 66 6f 72 20  ame+1 bytes for 
d150: 74 68 65 0a 2a 2a 20 6f 75 74 70 75 74 20 62 75  the.** output bu
d160: 66 66 65 72 20 78 46 75 6c 6c 50 61 74 68 6e 61  ffer xFullPathna
d170: 6d 65 2e 20 20 54 68 65 20 65 78 61 63 74 20 73  me.  The exact s
d180: 69 7a 65 20 6f 66 20 74 68 65 20 6f 75 74 70 75  ize of the outpu
d190: 74 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 61  t buffer.** is a
d1a0: 6c 73 6f 20 70 61 73 73 65 64 20 61 73 20 61 20  lso passed as a 
d1b0: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 6f 74  parameter to bot
d1c0: 68 20 20 6d 65 74 68 6f 64 73 2e 20 49 66 20 74  h  methods. If t
d1d0: 68 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72  he output buffer
d1e0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 6c 61 72 67 65  .** is not large
d1f0: 20 65 6e 6f 75 67 68 2c 20 5b 53 51 4c 49 54 45   enough, [SQLITE
d200: 5f 43 41 4e 54 4f 50 45 4e 5d 20 73 68 6f 75 6c  _CANTOPEN] shoul
d210: 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e 20 53  d be returned. S
d220: 69 6e 63 65 20 74 68 69 73 20 69 73 0a 2a 2a 20  ince this is.** 
d230: 68 61 6e 64 6c 65 64 20 61 73 20 61 20 66 61 74  handled as a fat
d240: 61 6c 20 65 72 72 6f 72 20 62 79 20 53 51 4c 69  al error by SQLi
d250: 74 65 2c 20 76 66 73 20 69 6d 70 6c 65 6d 65 6e  te, vfs implemen
d260: 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 65  tations should e
d270: 6e 64 65 61 76 6f 72 0a 2a 2a 20 74 6f 20 70 72  ndeavor.** to pr
d280: 65 76 65 6e 74 20 74 68 69 73 20 62 79 20 73 65  event this by se
d290: 74 74 69 6e 67 20 6d 78 50 61 74 68 6e 61 6d 65  tting mxPathname
d2a0: 20 74 6f 20 61 20 73 75 66 66 69 63 69 65 6e 74   to a sufficient
d2b0: 6c 79 20 6c 61 72 67 65 20 76 61 6c 75 65 2e 0a  ly large value..
d2c0: 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64 6f  **.** The xRando
d2d0: 6d 6e 65 73 73 28 29 2c 20 78 53 6c 65 65 70 28  mness(), xSleep(
d2e0: 29 2c 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  ), xCurrentTime(
d2f0: 29 2c 20 61 6e 64 20 78 43 75 72 72 65 6e 74 54  ), and xCurrentT
d300: 69 6d 65 49 6e 74 36 34 28 29 0a 2a 2a 20 69 6e  imeInt64().** in
d310: 74 65 72 66 61 63 65 73 20 61 72 65 20 6e 6f 74  terfaces are not
d320: 20 73 74 72 69 63 74 6c 79 20 61 20 70 61 72 74   strictly a part
d330: 20 6f 66 20 74 68 65 20 66 69 6c 65 73 79 73 74   of the filesyst
d340: 65 6d 2c 20 62 75 74 20 74 68 65 79 20 61 72 65  em, but they are
d350: 0a 2a 2a 20 69 6e 63 6c 75 64 65 64 20 69 6e 20  .** included in 
d360: 74 68 65 20 56 46 53 20 73 74 72 75 63 74 75 72  the VFS structur
d370: 65 20 66 6f 72 20 63 6f 6d 70 6c 65 74 65 6e 65  e for completene
d380: 73 73 2e 0a 2a 2a 20 54 68 65 20 78 52 61 6e 64  ss..** The xRand
d390: 6f 6d 6e 65 73 73 28 29 20 66 75 6e 63 74 69 6f  omness() functio
d3a0: 6e 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65  n attempts to re
d3b0: 74 75 72 6e 20 6e 42 79 74 65 73 20 62 79 74 65  turn nBytes byte
d3c0: 73 0a 2a 2a 20 6f 66 20 67 6f 6f 64 2d 71 75 61  s.** of good-qua
d3d0: 6c 69 74 79 20 72 61 6e 64 6f 6d 6e 65 73 73 20  lity randomness 
d3e0: 69 6e 74 6f 20 7a 4f 75 74 2e 20 20 54 68 65 20  into zOut.  The 
d3f0: 72 65 74 75 72 6e 20 76 61 6c 75 65 20 69 73 0a  return value is.
d400: 2a 2a 20 74 68 65 20 61 63 74 75 61 6c 20 6e 75  ** the actual nu
d410: 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 6f 66  mber of bytes of
d420: 20 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61   randomness obta
d430: 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 78 53 6c  ined..** The xSl
d440: 65 65 70 28 29 20 6d 65 74 68 6f 64 20 63 61 75  eep() method cau
d450: 73 65 73 20 74 68 65 20 63 61 6c 6c 69 6e 67 20  ses the calling 
d460: 74 68 72 65 61 64 20 74 6f 20 73 6c 65 65 70 20  thread to sleep 
d470: 66 6f 72 20 61 74 0a 2a 2a 20 6c 65 61 73 74 20  for at.** least 
d480: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d490: 63 72 6f 73 65 63 6f 6e 64 73 20 67 69 76 65 6e  croseconds given
d4a0: 2e 20 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  .  ^The xCurrent
d4b0: 54 69 6d 65 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  Time().** method
d4c0: 20 72 65 74 75 72 6e 73 20 61 20 4a 75 6c 69 61   returns a Julia
d4d0: 6e 20 44 61 79 20 4e 75 6d 62 65 72 20 66 6f 72  n Day Number for
d4e0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74   the current dat
d4f0: 65 20 61 6e 64 20 74 69 6d 65 20 61 73 0a 2a 2a  e and time as.**
d500: 20 61 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e   a floating poin
d510: 74 20 76 61 6c 75 65 2e 0a 2a 2a 20 5e 54 68 65  t value..** ^The
d520: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d530: 36 34 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  64() method retu
d540: 72 6e 73 2c 20 61 73 20 61 6e 20 69 6e 74 65 67  rns, as an integ
d550: 65 72 2c 20 74 68 65 20 4a 75 6c 69 61 6e 0a 2a  er, the Julian.*
d560: 2a 20 44 61 79 20 4e 75 6d 62 65 72 20 6d 75 6c  * Day Number mul
d570: 74 69 70 6c 69 65 64 20 62 79 20 38 36 34 30 30  tiplied by 86400
d580: 30 30 30 20 28 74 68 65 20 6e 75 6d 62 65 72 20  000 (the number 
d590: 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20  of milliseconds 
d5a0: 69 6e 20 0a 2a 2a 20 61 20 32 34 2d 68 6f 75 72  in .** a 24-hour
d5b0: 20 64 61 79 29 2e 20 20 0a 2a 2a 20 5e 53 51 4c   day).  .** ^SQL
d5c0: 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65  ite will use the
d5d0: 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74   xCurrentTimeInt
d5e0: 36 34 28 29 20 6d 65 74 68 6f 64 20 74 6f 20 67  64() method to g
d5f0: 65 74 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  et the current.*
d600: 2a 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  * date and time 
d610: 69 66 20 74 68 61 74 20 6d 65 74 68 6f 64 20 69  if that method i
d620: 73 20 61 76 61 69 6c 61 62 6c 65 20 28 69 66 20  s available (if 
d630: 69 56 65 72 73 69 6f 6e 20 69 73 20 32 20 6f 72  iVersion is 2 or
d640: 20 0a 2a 2a 20 67 72 65 61 74 65 72 20 61 6e 64   .** greater and
d650: 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
d660: 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
d670: 4c 29 20 61 6e 64 20 77 69 6c 6c 20 66 61 6c 6c  L) and will fall
d680: 20 62 61 63 6b 0a 2a 2a 20 74 6f 20 78 43 75 72   back.** to xCur
d690: 72 65 6e 74 54 69 6d 65 28 29 20 69 66 20 78 43  rentTime() if xC
d6a0: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
d6b0: 29 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c 65  ) is unavailable
d6c0: 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78 53 65  ..**.** ^The xSe
d6d0: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c 20 78  tSystemCall(), x
d6e0: 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 2c  GetSystemCall(),
d6f0: 20 61 6e 64 20 78 4e 65 73 74 53 79 73 74 65 6d   and xNestSystem
d700: 43 61 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  Call() interface
d710: 73 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 75 73 65  s.** are not use
d720: 64 20 62 79 20 74 68 65 20 53 51 4c 69 74 65 20  d by the SQLite 
d730: 63 6f 72 65 2e 20 20 54 68 65 73 65 20 6f 70 74  core.  These opt
d740: 69 6f 6e 61 6c 20 69 6e 74 65 72 66 61 63 65 73  ional interfaces
d750: 20 61 72 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a   are provided.**
d760: 20 62 79 20 73 6f 6d 65 20 56 46 53 65 73 20 74   by some VFSes t
d770: 6f 20 66 61 63 69 6c 69 74 61 74 65 20 74 65 73  o facilitate tes
d780: 74 69 6e 67 20 6f 66 20 74 68 65 20 56 46 53 20  ting of the VFS 
d790: 63 6f 64 65 2e 20 42 79 20 6f 76 65 72 72 69 64  code. By overrid
d7a0: 69 6e 67 20 0a 2a 2a 20 73 79 73 74 65 6d 20 63  ing .** system c
d7b0: 61 6c 6c 73 20 77 69 74 68 20 66 75 6e 63 74 69  alls with functi
d7c0: 6f 6e 73 20 75 6e 64 65 72 20 69 74 73 20 63 6f  ons under its co
d7d0: 6e 74 72 6f 6c 2c 20 61 20 74 65 73 74 20 70 72  ntrol, a test pr
d7e0: 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a 20 73 69 6d  ogram can.** sim
d7f0: 75 6c 61 74 65 20 66 61 75 6c 74 73 20 61 6e 64  ulate faults and
d800: 20 65 72 72 6f 72 20 63 6f 6e 64 69 74 69 6f 6e   error condition
d810: 73 20 74 68 61 74 20 77 6f 75 6c 64 20 6f 74 68  s that would oth
d820: 65 72 77 69 73 65 20 62 65 20 64 69 66 66 69 63  erwise be diffic
d830: 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d 70 6f 73 73  ult.** or imposs
d840: 69 62 6c 65 20 74 6f 20 69 6e 64 75 63 65 2e 20  ible to induce. 
d850: 20 54 68 65 20 73 65 74 20 6f 66 20 73 79 73 74   The set of syst
d860: 65 6d 20 63 61 6c 6c 73 20 74 68 61 74 20 63 61  em calls that ca
d870: 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 0a  n be overridden.
d880: 2a 2a 20 76 61 72 69 65 73 20 66 72 6f 6d 20 6f  ** varies from o
d890: 6e 65 20 56 46 53 20 74 6f 20 61 6e 6f 74 68 65  ne VFS to anothe
d8a0: 72 2c 20 61 6e 64 20 66 72 6f 6d 20 6f 6e 65 20  r, and from one 
d8b0: 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 73  version of the s
d8c0: 61 6d 65 20 56 46 53 20 74 6f 20 74 68 65 0a 2a  ame VFS to the.*
d8d0: 2a 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61  * next.  Applica
d8e0: 74 69 6f 6e 73 20 74 68 61 74 20 75 73 65 20 74  tions that use t
d8f0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
d900: 6d 75 73 74 20 62 65 20 70 72 65 70 61 72 65 64  must be prepared
d910: 20 66 6f 72 20 61 6e 79 0a 2a 2a 20 6f 72 20 61   for any.** or a
d920: 6c 6c 20 6f 66 20 74 68 65 73 65 20 69 6e 74 65  ll of these inte
d930: 72 66 61 63 65 73 20 74 6f 20 62 65 20 4e 55 4c  rfaces to be NUL
d940: 4c 20 6f 72 20 66 6f 72 20 74 68 65 69 72 20 62  L or for their b
d950: 65 68 61 76 69 6f 72 20 74 6f 20 63 68 61 6e 67  ehavior to chang
d960: 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e 65 20 72 65  e.** from one re
d970: 6c 65 61 73 65 20 74 6f 20 74 68 65 20 6e 65 78  lease to the nex
d980: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d990: 20 6d 75 73 74 20 6e 6f 74 20 61 74 74 65 6d 70   must not attemp
d9a0: 74 20 74 6f 20 61 63 63 65 73 73 0a 2a 2a 20 61  t to access.** a
d9b0: 6e 79 20 6f 66 20 74 68 65 73 65 20 6d 65 74 68  ny of these meth
d9c0: 6f 64 73 20 69 66 20 74 68 65 20 69 56 65 72 73  ods if the iVers
d9d0: 69 6f 6e 20 6f 66 20 74 68 65 20 56 46 53 20 69  ion of the VFS i
d9e0: 73 20 6c 65 73 73 20 74 68 61 6e 20 33 2e 0a 2a  s less than 3..*
d9f0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
da00: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 73 71 6c   sqlite3_vfs sql
da10: 69 74 65 33 5f 76 66 73 3b 0a 74 79 70 65 64 65  ite3_vfs;.typede
da20: 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
da30: 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 28 76 6f  _syscall_ptr)(vo
da40: 69 64 29 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  id);.struct sqli
da50: 74 65 33 5f 76 66 73 20 7b 0a 20 20 69 6e 74 20  te3_vfs {.  int 
da60: 69 56 65 72 73 69 6f 6e 3b 20 20 20 20 20 20 20  iVersion;       
da70: 20 20 20 20 20 2f 2a 20 53 74 72 75 63 74 75 72       /* Structur
da80: 65 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65 72  e version number
da90: 20 28 63 75 72 72 65 6e 74 6c 79 20 33 29 20 2a   (currently 3) *
daa0: 2f 0a 20 20 69 6e 74 20 73 7a 4f 73 46 69 6c 65  /.  int szOsFile
dab0: 3b 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ;            /* 
dac0: 53 69 7a 65 20 6f 66 20 73 75 62 63 6c 61 73 73  Size of subclass
dad0: 65 64 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 20  ed sqlite3_file 
dae0: 2a 2f 0a 20 20 69 6e 74 20 6d 78 50 61 74 68 6e  */.  int mxPathn
daf0: 61 6d 65 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ame;          /*
db00: 20 4d 61 78 69 6d 75 6d 20 66 69 6c 65 20 70 61   Maximum file pa
db10: 74 68 6e 61 6d 65 20 6c 65 6e 67 74 68 20 2a 2f  thname length */
db20: 0a 20 20 73 71 6c 69 74 65 33 5f 76 66 73 20 2a  .  sqlite3_vfs *
db30: 70 4e 65 78 74 3b 20 20 20 20 20 20 2f 2a 20 4e  pNext;      /* N
db40: 65 78 74 20 72 65 67 69 73 74 65 72 65 64 20 56  ext registered V
db50: 46 53 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  FS */.  const ch
db60: 61 72 20 2a 7a 4e 61 6d 65 3b 20 20 20 20 20 20  ar *zName;      
db70: 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 69 73   /* Name of this
db80: 20 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79   virtual file sy
db90: 73 74 65 6d 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  stem */.  void *
dba0: 70 41 70 70 44 61 74 61 3b 20 20 20 20 20 20 20  pAppData;       
dbb0: 20 20 20 2f 2a 20 50 6f 69 6e 74 65 72 20 74 6f     /* Pointer to
dbc0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 70 65   application-spe
dbd0: 63 69 66 69 63 20 64 61 74 61 20 2a 2f 0a 20 20  cific data */.  
dbe0: 69 6e 74 20 28 2a 78 4f 70 65 6e 29 28 73 71 6c  int (*xOpen)(sql
dbf0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
dc00: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
dc10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 0a 20 20 20  lite3_file*,.   
dc20: 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
dc30: 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 4f 75 74  flags, int *pOut
dc40: 46 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a  Flags);.  int (*
dc50: 78 44 65 6c 65 74 65 29 28 73 71 6c 69 74 65 33  xDelete)(sqlite3
dc60: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dc70: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 73 79  r *zName, int sy
dc80: 6e 63 44 69 72 29 3b 0a 20 20 69 6e 74 20 28 2a  ncDir);.  int (*
dc90: 78 41 63 63 65 73 73 29 28 73 71 6c 69 74 65 33  xAccess)(sqlite3
dca0: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
dcb0: 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20 66 6c  r *zName, int fl
dcc0: 61 67 73 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75  ags, int *pResOu
dcd0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 75 6c  t);.  int (*xFul
dce0: 6c 50 61 74 68 6e 61 6d 65 29 28 73 71 6c 69 74  lPathname)(sqlit
dcf0: 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63  e3_vfs*, const c
dd00: 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e 74 20  har *zName, int 
dd10: 6e 4f 75 74 2c 20 63 68 61 72 20 2a 7a 4f 75 74  nOut, char *zOut
dd20: 29 3b 0a 20 20 76 6f 69 64 20 2a 28 2a 78 44 6c  );.  void *(*xDl
dd30: 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66  Open)(sqlite3_vf
dd40: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dd50: 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a 20 20 76 6f  zFilename);.  vo
dd60: 69 64 20 28 2a 78 44 6c 45 72 72 6f 72 29 28 73  id (*xDlError)(s
dd70: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74  qlite3_vfs*, int
dd80: 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 45   nByte, char *zE
dd90: 72 72 4d 73 67 29 3b 0a 20 20 76 6f 69 64 20 28  rrMsg);.  void (
dda0: 2a 28 2a 78 44 6c 53 79 6d 29 28 73 71 6c 69 74  *(*xDlSym)(sqlit
ddb0: 65 33 5f 76 66 73 2a 2c 76 6f 69 64 2a 2c 20 63  e3_vfs*,void*, c
ddc0: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 79 6d 62  onst char *zSymb
ddd0: 6f 6c 29 29 28 76 6f 69 64 29 3b 0a 20 20 76 6f  ol))(void);.  vo
dde0: 69 64 20 28 2a 78 44 6c 43 6c 6f 73 65 29 28 73  id (*xDlClose)(s
ddf0: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 76 6f 69  qlite3_vfs*, voi
de00: 64 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 61  d*);.  int (*xRa
de10: 6e 64 6f 6d 6e 65 73 73 29 28 73 71 6c 69 74 65  ndomness)(sqlite
de20: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
de30: 65 2c 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a  e, char *zOut);.
de40: 20 20 69 6e 74 20 28 2a 78 53 6c 65 65 70 29 28    int (*xSleep)(
de50: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e  sqlite3_vfs*, in
de60: 74 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 29 3b  t microseconds);
de70: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
de80: 74 54 69 6d 65 29 28 73 71 6c 69 74 65 33 5f 76  tTime)(sqlite3_v
de90: 66 73 2a 2c 20 64 6f 75 62 6c 65 2a 29 3b 0a 20  fs*, double*);. 
dea0: 20 69 6e 74 20 28 2a 78 47 65 74 4c 61 73 74 45   int (*xGetLastE
deb0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
dec0: 73 2a 2c 20 69 6e 74 2c 20 63 68 61 72 20 2a 29  s*, int, char *)
ded0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
dee0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
def0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 20 31 20 6f  e in version 1 o
df00: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
df10: 20 6f 62 6a 65 63 74 0a 20 20 2a 2a 20 64 65 66   object.  ** def
df20: 69 6e 69 74 69 6f 6e 2e 20 20 54 68 6f 73 65 20  inition.  Those 
df30: 74 68 61 74 20 66 6f 6c 6c 6f 77 20 61 72 65 20  that follow are 
df40: 61 64 64 65 64 20 69 6e 20 76 65 72 73 69 6f 6e  added in version
df50: 20 32 20 6f 72 20 6c 61 74 65 72 0a 20 20 2a 2f   2 or later.  */
df60: 0a 20 20 69 6e 74 20 28 2a 78 43 75 72 72 65 6e  .  int (*xCurren
df70: 74 54 69 6d 65 49 6e 74 36 34 29 28 73 71 6c 69  tTimeInt64)(sqli
df80: 74 65 33 5f 76 66 73 2a 2c 20 73 71 6c 69 74 65  te3_vfs*, sqlite
df90: 33 5f 69 6e 74 36 34 2a 29 3b 0a 20 20 2f 2a 0a  3_int64*);.  /*.
dfa0: 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73    ** The methods
dfb0: 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65   above are in ve
dfc0: 72 73 69 6f 6e 73 20 31 20 61 6e 64 20 32 20 6f  rsions 1 and 2 o
dfd0: 66 20 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73  f the sqlite_vfs
dfe0: 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 54 68   object..  ** Th
dff0: 6f 73 65 20 62 65 6c 6f 77 20 61 72 65 20 66 6f  ose below are fo
e000: 72 20 76 65 72 73 69 6f 6e 20 33 20 61 6e 64 20  r version 3 and 
e010: 67 72 65 61 74 65 72 2e 0a 20 20 2a 2f 0a 20 20  greater..  */.  
e020: 69 6e 74 20 28 2a 78 53 65 74 53 79 73 74 65 6d  int (*xSetSystem
e030: 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66  Call)(sqlite3_vf
e040: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
e050: 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 73  zName, sqlite3_s
e060: 79 73 63 61 6c 6c 5f 70 74 72 29 3b 0a 20 20 73  yscall_ptr);.  s
e070: 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70  qlite3_syscall_p
e080: 74 72 20 28 2a 78 47 65 74 53 79 73 74 65 6d 43  tr (*xGetSystemC
e090: 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73  all)(sqlite3_vfs
e0a0: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
e0b0: 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e 73 74 20 63  Name);.  const c
e0c0: 68 61 72 20 2a 28 2a 78 4e 65 78 74 53 79 73 74  har *(*xNextSyst
e0d0: 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33 5f  emCall)(sqlite3_
e0e0: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
e0f0: 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 2f 2a 0a 20   *zName);.  /*. 
e100: 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20   ** The methods 
e110: 61 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72  above are in ver
e120: 73 69 6f 6e 73 20 31 20 74 68 72 6f 75 67 68 20  sions 1 through 
e130: 33 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 5f  3 of the sqlite_
e140: 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a 2a  vfs object..  **
e150: 20 4e 65 77 20 66 69 65 6c 64 73 20 6d 61 79 20   New fields may 
e160: 62 65 20 61 70 70 65 6e 64 65 64 20 69 6e 20 66  be appended in f
e170: 69 67 75 72 65 20 76 65 72 73 69 6f 6e 73 2e 20  igure versions. 
e180: 20 54 68 65 20 69 56 65 72 73 69 6f 6e 0a 20 20   The iVersion.  
e190: 2a 2a 20 76 61 6c 75 65 20 77 69 6c 6c 20 69 6e  ** value will in
e1a0: 63 72 65 6d 65 6e 74 20 77 68 65 6e 65 76 65 72  crement whenever
e1b0: 20 74 68 69 73 20 68 61 70 70 65 6e 73 2e 20 0a   this happens. .
e1c0: 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43    */.};../*.** C
e1d0: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e1e0: 6f 72 20 74 68 65 20 78 41 63 63 65 73 73 20 56  or the xAccess V
e1f0: 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20  FS method.**.** 
e200: 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63 6f  These integer co
e210: 6e 73 74 61 6e 74 73 20 63 61 6e 20 62 65 20 75  nstants can be u
e220: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
e230: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
e240: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
e250: 68 6f 64 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  hod of an [sqlit
e260: 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20  e3_vfs] object. 
e270: 20 54 68 65 79 20 64 65 74 65 72 6d 69 6e 65 0a   They determine.
e280: 2a 2a 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20  ** what kind of 
e290: 70 65 72 6d 69 73 73 69 6f 6e 73 20 74 68 65 20  permissions the 
e2a0: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 69  xAccess method i
e2b0: 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f 72 2e 0a 2a  s looking for..*
e2c0: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e2d0: 43 45 53 53 5f 45 58 49 53 54 53 2c 20 74 68 65  CESS_EXISTS, the
e2e0: 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a   xAccess method.
e2f0: 2a 2a 20 73 69 6d 70 6c 79 20 63 68 65 63 6b 73  ** simply checks
e300: 20 77 68 65 74 68 65 72 20 74 68 65 20 66 69 6c   whether the fil
e310: 65 20 65 78 69 73 74 73 2e 0a 2a 2a 20 57 69 74  e exists..** Wit
e320: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e330: 52 45 41 44 57 52 49 54 45 2c 20 74 68 65 20 78  READWRITE, the x
e340: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e350: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e360: 74 68 65 20 6e 61 6d 65 64 20 64 69 72 65 63 74  the named direct
e370: 6f 72 79 20 69 73 20 62 6f 74 68 20 72 65 61 64  ory is both read
e380: 61 62 6c 65 20 61 6e 64 20 77 72 69 74 61 62 6c  able and writabl
e390: 65 0a 2a 2a 20 28 69 6e 20 6f 74 68 65 72 20 77  e.** (in other w
e3a0: 6f 72 64 73 2c 20 69 66 20 66 69 6c 65 73 20 63  ords, if files c
e3b0: 61 6e 20 62 65 20 61 64 64 65 64 2c 20 72 65 6d  an be added, rem
e3c0: 6f 76 65 64 2c 20 61 6e 64 20 72 65 6e 61 6d 65  oved, and rename
e3d0: 64 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  d within.** the 
e3e0: 64 69 72 65 63 74 6f 72 79 29 2e 0a 2a 2a 20 54  directory)..** T
e3f0: 68 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53  he SQLITE_ACCESS
e400: 5f 52 45 41 44 57 52 49 54 45 20 63 6f 6e 73 74  _READWRITE const
e410: 61 6e 74 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ant is currently
e420: 20 75 73 65 64 20 6f 6e 6c 79 20 62 79 20 74 68   used only by th
e430: 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73 74 6f 72 65  e.** [temp_store
e440: 5f 64 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d  _directory pragm
e450: 61 5d 2c 20 74 68 6f 75 67 68 20 74 68 69 73 20  a], though this 
e460: 63 6f 75 6c 64 20 63 68 61 6e 67 65 20 69 6e 20  could change in 
e470: 61 20 66 75 74 75 72 65 0a 2a 2a 20 72 65 6c 65  a future.** rele
e480: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
e490: 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43  * With SQLITE_AC
e4a0: 43 45 53 53 5f 52 45 41 44 2c 20 74 68 65 20 78  CESS_READ, the x
e4b0: 41 63 63 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a  Access method.**
e4c0: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
e4d0: 74 68 65 20 66 69 6c 65 20 69 73 20 72 65 61 64  the file is read
e4e0: 61 62 6c 65 2e 20 20 54 68 65 20 53 51 4c 49 54  able.  The SQLIT
e4f0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 63 6f  E_ACCESS_READ co
e500: 6e 73 74 61 6e 74 20 69 73 0a 2a 2a 20 63 75 72  nstant is.** cur
e510: 72 65 6e 74 6c 79 20 75 6e 75 73 65 64 2c 20 74  rently unused, t
e520: 68 6f 75 67 68 20 69 74 20 6d 69 67 68 74 20 62  hough it might b
e530: 65 20 75 73 65 64 20 69 6e 20 61 20 66 75 74 75  e used in a futu
e540: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a  re release of.**
e550: 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66   SQLite..*/.#def
e560: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e570: 53 5f 45 58 49 53 54 53 20 20 20 20 30 0a 23 64  S_EXISTS    0.#d
e580: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43  efine SQLITE_ACC
e590: 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 31 20  ESS_READWRITE 1 
e5a0: 20 20 2f 2a 20 55 73 65 64 20 62 79 20 50 52 41    /* Used by PRA
e5b0: 47 4d 41 20 74 65 6d 70 5f 73 74 6f 72 65 5f 64  GMA temp_store_d
e5c0: 69 72 65 63 74 6f 72 79 20 2a 2f 0a 23 64 65 66  irectory */.#def
e5d0: 69 6e 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53  ine SQLITE_ACCES
e5e0: 53 5f 52 45 41 44 20 20 20 20 20 20 32 20 20 20  S_READ      2   
e5f0: 2f 2a 20 55 6e 75 73 65 64 20 2a 2f 0a 0a 2f 2a  /* Unused */../*
e600: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c  .** CAPI3REF: Fl
e610: 61 67 73 20 66 6f 72 20 74 68 65 20 78 53 68 6d  ags for the xShm
e620: 4c 6f 63 6b 20 56 46 53 20 6d 65 74 68 6f 64 0a  Lock VFS method.
e630: 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65  **.** These inte
e640: 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ger constants de
e650: 66 69 6e 65 20 74 68 65 20 76 61 72 69 6f 75 73  fine the various
e660: 20 6c 6f 63 6b 69 6e 67 20 6f 70 65 72 61 74 69   locking operati
e670: 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 62  ons.** allowed b
e680: 79 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d  y the xShmLock m
e690: 65 74 68 6f 64 20 6f 66 20 5b 73 71 6c 69 74 65  ethod of [sqlite
e6a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 2e 20 20  3_io_methods].  
e6b0: 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  The.** following
e6c0: 20 61 72 65 20 74 68 65 20 6f 6e 6c 79 20 6c 65   are the only le
e6d0: 67 61 6c 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73  gal combinations
e6e0: 20 6f 66 20 66 6c 61 67 73 20 74 6f 20 74 68 65   of flags to the
e6f0: 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74  .** xShmLock met
e700: 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  hod:.**.** <ul>.
e710: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
e720: 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54  SHM_LOCK | SQLIT
e730: 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20  E_SHM_SHARED.** 
e740: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e750: 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53  _LOCK | SQLITE_S
e760: 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a 20  HM_EXCLUSIVE.** 
e770: 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d  <li>  SQLITE_SHM
e780: 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45  _UNLOCK | SQLITE
e790: 5f 53 48 4d 5f 53 48 41 52 45 44 0a 2a 2a 20 3c  _SHM_SHARED.** <
e7a0: 6c 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f  li>  SQLITE_SHM_
e7b0: 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f  UNLOCK | SQLITE_
e7c0: 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 0a 2a 2a  SHM_EXCLUSIVE.**
e7d0: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 57 68 65   </ul>.**.** Whe
e7e0: 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c 20 74 68 65  n unlocking, the
e7f0: 20 73 61 6d 65 20 53 48 41 52 45 44 20 6f 72 20   same SHARED or 
e800: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 20 6d  EXCLUSIVE flag m
e810: 75 73 74 20 62 65 20 73 75 70 70 6c 69 65 64 20  ust be supplied 
e820: 61 73 0a 2a 2a 20 77 61 73 20 67 69 76 65 6e 20  as.** was given 
e830: 6e 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  no the correspon
e840: 64 69 6e 67 20 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a  ding lock.  .**.
e850: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e860: 6d 65 74 68 6f 64 20 63 61 6e 20 74 72 61 6e 73  method can trans
e870: 69 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 75 6e  ition between un
e880: 6c 6f 63 6b 65 64 20 61 6e 64 20 53 48 41 52 45  locked and SHARE
e890: 44 20 6f 72 0a 2a 2a 20 62 65 74 77 65 65 6e 20  D or.** between 
e8a0: 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 45 58 43  unlocked and EXC
e8b0: 4c 55 53 49 56 45 2e 20 20 49 74 20 63 61 6e 6e  LUSIVE.  It cann
e8c0: 6f 74 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65  ot transition be
e8d0: 74 77 65 65 6e 20 53 48 41 52 45 44 0a 2a 2a 20  tween SHARED.** 
e8e0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 0a 2a  and EXCLUSIVE..*
e8f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
e900: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 20 20 20 20  _SHM_UNLOCK     
e910: 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    1.#define SQLI
e920: 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 20 20 20 20  TE_SHM_LOCK     
e930: 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
e940: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 20  LITE_SHM_SHARED 
e950: 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20        4.#define 
e960: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
e970: 53 49 56 45 20 20 20 20 38 0a 0a 2f 2a 0a 2a 2a  SIVE    8../*.**
e980: 20 43 41 50 49 33 52 45 46 3a 20 4d 61 78 69 6d   CAPI3REF: Maxim
e990: 75 6d 20 78 53 68 6d 4c 6f 63 6b 20 69 6e 64 65  um xShmLock inde
e9a0: 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d  x.**.** The xShm
e9b0: 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 6e 20 5b  Lock method on [
e9c0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
e9d0: 64 73 5d 20 6d 61 79 20 75 73 65 20 76 61 6c 75  ds] may use valu
e9e0: 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  es.** between 0 
e9f0: 61 6e 64 20 74 68 69 73 20 75 70 70 65 72 20 62  and this upper b
ea00: 6f 75 6e 64 20 61 73 20 69 74 73 20 22 6f 66 66  ound as its "off
ea10: 73 65 74 22 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  set" argument..*
ea20: 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
ea30: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 61 74 74  e will never att
ea40: 65 6d 70 74 20 74 6f 20 61 63 71 75 69 72 65 20  empt to acquire 
ea50: 6f 72 20 72 65 6c 65 61 73 65 20 61 0a 2a 2a 20  or release a.** 
ea60: 6c 6f 63 6b 20 6f 75 74 73 69 64 65 20 6f 66 20  lock outside of 
ea70: 74 68 69 73 20 72 61 6e 67 65 0a 2a 2f 0a 23 64  this range.*/.#d
ea80: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d  efine SQLITE_SHM
ea90: 5f 4e 4c 4f 43 4b 20 20 20 20 20 20 20 20 38 0a  _NLOCK        8.
eaa0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
eab0: 3a 20 49 6e 69 74 69 61 6c 69 7a 65 20 54 68 65  : Initialize The
eac0: 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a   SQLite Library.
ead0: 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
eae0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
eaf0: 72 6f 75 74 69 6e 65 20 69 6e 69 74 69 61 6c 69  routine initiali
eb00: 7a 65 73 20 74 68 65 0a 2a 2a 20 53 51 4c 69 74  zes the.** SQLit
eb10: 65 20 6c 69 62 72 61 72 79 2e 20 20 5e 54 68 65  e library.  ^The
eb20: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
eb30: 6e 28 29 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 64  n() routine.** d
eb40: 65 61 6c 6c 6f 63 61 74 65 73 20 61 6e 79 20 72  eallocates any r
eb50: 65 73 6f 75 72 63 65 73 20 74 68 61 74 20 77 65  esources that we
eb60: 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  re allocated by 
eb70: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
eb80: 7a 65 28 29 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ze()..** These r
eb90: 6f 75 74 69 6e 65 73 20 61 72 65 20 64 65 73 69  outines are desi
eba0: 67 6e 65 64 20 74 6f 20 61 69 64 20 69 6e 20 70  gned to aid in p
ebb0: 72 6f 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a  rocess initializ
ebc0: 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a 20 73 68 75  ation and.** shu
ebd0: 74 64 6f 77 6e 20 6f 6e 20 65 6d 62 65 64 64 65  tdown on embedde
ebe0: 64 20 73 79 73 74 65 6d 73 2e 20 20 57 6f 72 6b  d systems.  Work
ebf0: 73 74 61 74 69 6f 6e 20 61 70 70 6c 69 63 61 74  station applicat
ec00: 69 6f 6e 73 20 75 73 69 6e 67 0a 2a 2a 20 53 51  ions using.** SQ
ec10: 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c 79 20 64 6f  Lite normally do
ec20: 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 69 6e 76   not need to inv
ec30: 6f 6b 65 20 65 69 74 68 65 72 20 6f 66 20 74 68  oke either of th
ec40: 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  ese routines..**
ec50: 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73 71  .** A call to sq
ec60: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
ec70: 28 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74  () is an "effect
ec80: 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20  ive" call if it 
ec90: 69 73 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  is.** the first 
eca0: 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  time sqlite3_ini
ecb0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
ecc0: 6f 6b 65 64 20 64 75 72 69 6e 67 20 74 68 65 20  oked during the 
ecd0: 6c 69 66 65 74 69 6d 65 20 6f 66 0a 2a 2a 20 74  lifetime of.** t
ece0: 68 65 20 70 72 6f 63 65 73 73 2c 20 6f 72 20 69  he process, or i
ecf0: 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72 73  f it is the firs
ed00: 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33 5f 69  t time sqlite3_i
ed10: 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
ed20: 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nvoked.** follow
ed30: 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f 20 73 71  ing a call to sq
ed40: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ed50: 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e 20 65 66 66  .  ^(Only an eff
ed60: 65 63 74 69 76 65 20 63 61 6c 6c 0a 2a 2a 20 6f  ective call.** o
ed70: 66 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  f sqlite3_initia
ed80: 6c 69 7a 65 28 29 20 64 6f 65 73 20 61 6e 79 20  lize() does any 
ed90: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 20  initialization. 
eda0: 20 41 6c 6c 20 6f 74 68 65 72 20 63 61 6c 6c 73   All other calls
edb0: 0a 2a 2a 20 61 72 65 20 68 61 72 6d 6c 65 73 73  .** are harmless
edc0: 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a   no-ops.)^.**.**
edd0: 20 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74   A call to sqlit
ede0: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 73  e3_shutdown() is
edf0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ee00: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 20 74 68  call if it is th
ee10: 65 20 66 69 72 73 74 0a 2a 2a 20 63 61 6c 6c 20  e first.** call 
ee20: 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  to sqlite3_shutd
ee30: 6f 77 6e 28 29 20 73 69 6e 63 65 20 74 68 65 20  own() since the 
ee40: 6c 61 73 74 20 73 71 6c 69 74 65 33 5f 69 6e 69  last sqlite3_ini
ee50: 74 69 61 6c 69 7a 65 28 29 2e 20 20 5e 28 4f 6e  tialize().  ^(On
ee60: 6c 79 0a 2a 2a 20 61 6e 20 65 66 66 65 63 74 69  ly.** an effecti
ee70: 76 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  ve call to sqlit
ee80: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 64 6f  e3_shutdown() do
ee90: 65 73 20 61 6e 79 20 64 65 69 6e 69 74 69 61 6c  es any deinitial
eea0: 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20  ization..** All 
eeb0: 6f 74 68 65 72 20 76 61 6c 69 64 20 63 61 6c 6c  other valid call
eec0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  s to sqlite3_shu
eed0: 74 64 6f 77 6e 28 29 20 61 72 65 20 68 61 72 6d  tdown() are harm
eee0: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
eef0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
ef00: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 6e  _initialize() in
ef10: 74 65 72 66 61 63 65 20 69 73 20 74 68 72 65 61  terface is threa
ef20: 64 73 61 66 65 2c 20 62 75 74 20 73 71 6c 69 74  dsafe, but sqlit
ef30: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a  e3_shutdown().**
ef40: 20 69 73 20 6e 6f 74 2e 20 20 54 68 65 20 73 71   is not.  The sq
ef50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ef60: 20 69 6e 74 65 72 66 61 63 65 20 6d 75 73 74 20   interface must 
ef70: 6f 6e 6c 79 20 62 65 20 63 61 6c 6c 65 64 20 66  only be called f
ef80: 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e 67 6c 65 20  rom a.** single 
ef90: 74 68 72 65 61 64 2e 20 20 41 6c 6c 20 6f 70 65  thread.  All ope
efa0: 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
efb0: 65 63 74 69 6f 6e 73 5d 20 6d 75 73 74 20 62 65  ections] must be
efc0: 20 63 6c 6f 73 65 64 20 61 6e 64 20 61 6c 6c 0a   closed and all.
efd0: 2a 2a 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ** other SQLite 
efe0: 72 65 73 6f 75 72 63 65 73 20 6d 75 73 74 20 62  resources must b
eff0: 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 70 72  e deallocated pr
f000: 69 6f 72 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 0a  ior to invoking.
f010: 2a 2a 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  ** sqlite3_shutd
f020: 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f  own()..**.** Amo
f030: 6e 67 20 6f 74 68 65 72 20 74 68 69 6e 67 73 2c  ng other things,
f040: 20 5e 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   ^sqlite3_initia
f050: 6c 69 7a 65 28 29 20 77 69 6c 6c 20 69 6e 76 6f  lize() will invo
f060: 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  ke.** sqlite3_os
f070: 5f 69 6e 69 74 28 29 2e 20 20 53 69 6d 69 6c 61  _init().  Simila
f080: 72 6c 79 2c 20 5e 73 71 6c 69 74 65 33 5f 73 68  rly, ^sqlite3_sh
f090: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 77 69 6c 6c  utdown().** will
f0a0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f0b0: 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a 0a 2a 2a 20  os_end()..**.** 
f0c0: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69  ^The sqlite3_ini
f0d0: 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e  tialize() routin
f0e0: 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
f0f0: 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
f100: 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72 20 73 6f 6d  ..** ^If for som
f110: 65 20 72 65 61 73 6f 6e 2c 20 73 71 6c 69 74 65  e reason, sqlite
f120: 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69  3_initialize() i
f130: 73 20 75 6e 61 62 6c 65 20 74 6f 20 69 6e 69 74  s unable to init
f140: 69 61 6c 69 7a 65 0a 2a 2a 20 74 68 65 20 6c 69  ialize.** the li
f150: 62 72 61 72 79 20 28 70 65 72 68 61 70 73 20 69  brary (perhaps i
f160: 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  t is unable to a
f170: 6c 6c 6f 63 61 74 65 20 61 20 6e 65 65 64 65 64  llocate a needed
f180: 20 72 65 73 6f 75 72 63 65 20 73 75 63 68 0a 2a   resource such.*
f190: 2a 20 61 73 20 61 20 6d 75 74 65 78 29 20 69 74  * as a mutex) it
f1a0: 20 72 65 74 75 72 6e 73 20 61 6e 20 5b 65 72 72   returns an [err
f1b0: 6f 72 20 63 6f 64 65 5d 20 6f 74 68 65 72 20 74  or code] other t
f1c0: 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e  han [SQLITE_OK].
f1d0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
f1e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
f1f0: 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
f200: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
f210: 20 6d 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 53   many other.** S
f220: 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 73  QLite interfaces
f230: 20 73 6f 20 74 68 61 74 20 61 6e 20 61 70 70 6c   so that an appl
f240: 69 63 61 74 69 6f 6e 20 75 73 75 61 6c 6c 79 20  ication usually 
f250: 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
f260: 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  .** invoke sqlit
f270: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
f280: 64 69 72 65 63 74 6c 79 2e 20 20 46 6f 72 20 65  directly.  For e
f290: 78 61 6d 70 6c 65 2c 20 5b 73 71 6c 69 74 65 33  xample, [sqlite3
f2a0: 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 63 61 6c 6c  _open()].** call
f2b0: 73 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  s sqlite3_initia
f2c0: 6c 69 7a 65 28 29 20 73 6f 20 74 68 65 20 53 51  lize() so the SQ
f2d0: 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c  Lite library wil
f2e0: 6c 20 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  l be automatical
f2f0: 6c 79 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 65  ly.** initialize
f300: 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  d when [sqlite3_
f310: 6f 70 65 6e 28 29 5d 20 69 73 20 63 61 6c 6c 65  open()] is calle
f320: 64 20 69 66 20 69 74 20 68 61 73 20 6e 6f 74 20  d if it has not 
f330: 62 65 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a 2a  be initialized.*
f340: 2a 20 61 6c 72 65 61 64 79 2e 20 20 5e 48 6f 77  * already.  ^How
f350: 65 76 65 72 2c 20 69 66 20 53 51 4c 69 74 65 20  ever, if SQLite 
f360: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f370: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 4d 49   the [SQLITE_OMI
f380: 54 5f 41 55 54 4f 49 4e 49 54 5d 0a 2a 2a 20 63  T_AUTOINIT].** c
f390: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
f3a0: 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 61 75 74  on, then the aut
f3b0: 6f 6d 61 74 69 63 20 63 61 6c 6c 73 20 74 6f 20  omatic calls to 
f3c0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f3d0: 7a 65 28 29 0a 2a 2a 20 61 72 65 20 6f 6d 69 74  ze().** are omit
f3e0: 74 65 64 20 61 6e 64 20 74 68 65 20 61 70 70 6c  ted and the appl
f3f0: 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 63 61 6c  ication must cal
f400: 6c 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  l sqlite3_initia
f410: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 0a  lize() directly.
f420: 2a 2a 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e  ** prior to usin
f430: 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69  g any other SQLi
f440: 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46  te interface.  F
f450: 6f 72 20 6d 61 78 69 6d 75 6d 20 70 6f 72 74 61  or maximum porta
f460: 62 69 6c 69 74 79 2c 0a 2a 2a 20 69 74 20 69 73  bility,.** it is
f470: 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61   recommended tha
f480: 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61  t applications a
f490: 6c 77 61 79 73 20 69 6e 76 6f 6b 65 20 73 71 6c  lways invoke sql
f4a0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f4b0: 29 0a 2a 2a 20 64 69 72 65 63 74 6c 79 20 70 72  ).** directly pr
f4c0: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f4d0: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f4e0: 74 65 72 66 61 63 65 2e 20 20 46 75 74 75 72 65  terface.  Future
f4f0: 20 72 65 6c 65 61 73 65 73 0a 2a 2a 20 6f 66 20   releases.** of 
f500: 53 51 4c 69 74 65 20 6d 61 79 20 72 65 71 75 69  SQLite may requi
f510: 72 65 20 74 68 69 73 2e 20 20 49 6e 20 6f 74 68  re this.  In oth
f520: 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20 62 65  er words, the be
f530: 68 61 76 69 6f 72 20 65 78 68 69 62 69 74 65 64  havior exhibited
f540: 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65 20  .** when SQLite 
f550: 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
f560: 20 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55   [SQLITE_OMIT_AU
f570: 54 4f 49 4e 49 54 5d 20 6d 69 67 68 74 20 62 65  TOINIT] might be
f580: 63 6f 6d 65 20 74 68 65 0a 2a 2a 20 64 65 66 61  come the.** defa
f590: 75 6c 74 20 62 65 68 61 76 69 6f 72 20 69 6e 20  ult behavior in 
f5a0: 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
f5b0: 61 73 65 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ase of SQLite..*
f5c0: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
f5d0: 5f 6f 73 5f 69 6e 69 74 28 29 20 72 6f 75 74 69  _os_init() routi
f5e0: 6e 65 20 64 6f 65 73 20 6f 70 65 72 61 74 69 6e  ne does operatin
f5f0: 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
f600: 63 0a 2a 2a 20 69 6e 69 74 69 61 6c 69 7a 61 74  c.** initializat
f610: 69 6f 6e 20 6f 66 20 74 68 65 20 53 51 4c 69 74  ion of the SQLit
f620: 65 20 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20  e library.  The 
f630: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f640: 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 75 6e 64 6f  .** routine undo
f650: 65 73 20 74 68 65 20 65 66 66 65 63 74 20 6f 66  es the effect of
f660: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f670: 28 29 2e 20 20 54 79 70 69 63 61 6c 20 74 61 73  ().  Typical tas
f680: 6b 73 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20  ks.** performed 
f690: 62 79 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  by these routine
f6a0: 73 20 69 6e 63 6c 75 64 65 20 61 6c 6c 6f 63 61  s include alloca
f6b0: 74 69 6f 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tion or dealloca
f6c0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73 74 61 74 69  tion.** of stati
f6d0: 63 20 72 65 73 6f 75 72 63 65 73 2c 20 69 6e 69  c resources, ini
f6e0: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 67  tialization of g
f6f0: 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 73 2c  lobal variables,
f700: 0a 2a 2a 20 73 65 74 74 69 6e 67 20 75 70 20 61  .** setting up a
f710: 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
f720: 33 5f 76 66 73 5d 20 6d 6f 64 75 6c 65 2c 20 6f  3_vfs] module, o
f730: 72 20 73 65 74 74 69 6e 67 20 75 70 0a 2a 2a 20  r setting up.** 
f740: 61 20 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67  a default config
f750: 75 72 61 74 69 6f 6e 20 75 73 69 6e 67 20 5b 73  uration using [s
f760: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f770: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ..**.** The appl
f780: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e  ication should n
f790: 65 76 65 72 20 69 6e 76 6f 6b 65 20 65 69 74 68  ever invoke eith
f7a0: 65 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  er sqlite3_os_in
f7b0: 69 74 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  it().** or sqlit
f7c0: 65 33 5f 6f 73 5f 65 6e 64 28 29 20 64 69 72 65  e3_os_end() dire
f7d0: 63 74 6c 79 2e 20 20 54 68 65 20 61 70 70 6c 69  ctly.  The appli
f7e0: 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6f 6e  cation should on
f7f0: 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ly invoke.** sql
f800: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f810: 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 73 68  ) and sqlite3_sh
f820: 75 74 64 6f 77 6e 28 29 2e 20 20 54 68 65 20 73  utdown().  The s
f830: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
f840: 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
f850: 20 63 61 6c 6c 65 64 20 61 75 74 6f 6d 61 74 69   called automati
f860: 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
f870: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e  _initialize() an
f880: 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73 5f  d.** sqlite3_os_
f890: 65 6e 64 28 29 20 69 73 20 63 61 6c 6c 65 64 20  end() is called 
f8a0: 62 79 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64  by sqlite3_shutd
f8b0: 6f 77 6e 28 29 2e 20 20 41 70 70 72 6f 70 72 69  own().  Appropri
f8c0: 61 74 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  ate.** implement
f8d0: 61 74 69 6f 6e 73 20 66 6f 72 20 73 71 6c 69 74  ations for sqlit
f8e0: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64  e3_os_init() and
f8f0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
f900: 29 0a 2a 2a 20 61 72 65 20 62 75 69 6c 74 20 69  ).** are built i
f910: 6e 74 6f 20 53 51 4c 69 74 65 20 77 68 65 6e 20  nto SQLite when 
f920: 69 74 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 66  it is compiled f
f930: 6f 72 20 55 6e 69 78 2c 20 57 69 6e 64 6f 77 73  or Unix, Windows
f940: 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a 2a 20 57 68  , or OS/2..** Wh
f950: 65 6e 20 5b 63 75 73 74 6f 6d 20 62 75 69 6c 64  en [custom build
f960: 73 20 7c 20 62 75 69 6c 74 20 66 6f 72 20 6f 74  s | built for ot
f970: 68 65 72 20 70 6c 61 74 66 6f 72 6d 73 5d 0a 2a  her platforms].*
f980: 2a 20 28 75 73 69 6e 67 20 74 68 65 20 5b 53 51  * (using the [SQ
f990: 4c 49 54 45 5f 4f 53 5f 4f 54 48 45 52 3d 31 5d  LITE_OS_OTHER=1]
f9a0: 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a   compile-time.**
f9b0: 20 6f 70 74 69 6f 6e 29 20 74 68 65 20 61 70 70   option) the app
f9c0: 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 73 75  lication must su
f9d0: 70 70 6c 79 20 61 20 73 75 69 74 61 62 6c 65 20  pply a suitable 
f9e0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 66  implementation f
f9f0: 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 73  or.** sqlite3_os
fa00: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
fa10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 20 20 41  te3_os_end().  A
fa20: 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 73 75  n application-su
fa30: 70 70 6c 69 65 64 0a 2a 2a 20 69 6d 70 6c 65 6d  pplied.** implem
fa40: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69  entation of sqli
fa50: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 6f 72  te3_os_init() or
fa60: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fa70: 29 0a 2a 2a 20 6d 75 73 74 20 72 65 74 75 72 6e  ).** must return
fa80: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
fa90: 73 75 63 63 65 73 73 20 61 6e 64 20 73 6f 6d 65  success and some
faa0: 20 6f 74 68 65 72 20 5b 65 72 72 6f 72 20 63 6f   other [error co
fab0: 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20 66 61 69 6c  de] upon.** fail
fac0: 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ure..*/.int sqli
fad0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 76  te3_initialize(v
fae0: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
faf0: 33 5f 73 68 75 74 64 6f 77 6e 28 76 6f 69 64 29  3_shutdown(void)
fb00: 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73  ;.int sqlite3_os
fb10: 5f 69 6e 69 74 28 76 6f 69 64 29 3b 0a 69 6e 74  _init(void);.int
fb20: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28   sqlite3_os_end(
fb30: 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  void);../*.** CA
fb40: 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72  PI3REF: Configur
fb50: 69 6e 67 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ing The SQLite L
fb60: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 54 68 65  ibrary.**.** The
fb70: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
fb80: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
fb90: 73 65 64 20 74 6f 20 6d 61 6b 65 20 67 6c 6f 62  sed to make glob
fba0: 61 6c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  al configuration
fbb0: 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 53  .** changes to S
fbc0: 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74  QLite in order t
fbd0: 6f 20 74 75 6e 65 20 53 51 4c 69 74 65 20 74 6f  o tune SQLite to
fbe0: 20 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65   the specific ne
fbf0: 65 64 73 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  eds of.** the ap
fc00: 70 6c 69 63 61 74 69 6f 6e 2e 20 20 54 68 65 20  plication.  The 
fc10: 64 65 66 61 75 6c 74 20 63 6f 6e 66 69 67 75 72  default configur
fc20: 61 74 69 6f 6e 20 69 73 20 72 65 63 6f 6d 6d 65  ation is recomme
fc30: 6e 64 65 64 20 66 6f 72 20 6d 6f 73 74 0a 2a 2a  nded for most.**
fc40: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
fc50: 64 20 73 6f 20 74 68 69 73 20 72 6f 75 74 69 6e  d so this routin
fc60: 65 20 69 73 20 75 73 75 61 6c 6c 79 20 6e 6f 74  e is usually not
fc70: 20 6e 65 63 65 73 73 61 72 79 2e 20 20 49 74 20   necessary.  It 
fc80: 69 73 0a 2a 2a 20 70 72 6f 76 69 64 65 64 20 74  is.** provided t
fc90: 6f 20 73 75 70 70 6f 72 74 20 72 61 72 65 20 61  o support rare a
fca0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 77 69 74 68  pplications with
fcb0: 20 75 6e 75 73 75 61 6c 20 6e 65 65 64 73 2e 0a   unusual needs..
fcc0: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
fcd0: 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72  3_config() inter
fce0: 66 61 63 65 20 69 73 20 6e 6f 74 20 74 68 72 65  face is not thre
fcf0: 61 64 73 61 66 65 2e 20 20 54 68 65 20 61 70 70  adsafe.  The app
fd00: 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  lication.** must
fd10: 20 69 6e 73 75 72 65 20 74 68 61 74 20 6e 6f 20   insure that no 
fd20: 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
fd30: 65 72 66 61 63 65 73 20 61 72 65 20 69 6e 76 6f  erfaces are invo
fd40: 6b 65 64 20 62 79 20 6f 74 68 65 72 0a 2a 2a 20  ked by other.** 
fd50: 74 68 72 65 61 64 73 20 77 68 69 6c 65 20 73 71  threads while sq
fd60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fd70: 73 20 72 75 6e 6e 69 6e 67 2e 20 20 46 75 72 74  s running.  Furt
fd80: 68 65 72 6d 6f 72 65 2c 20 73 71 6c 69 74 65 33  hermore, sqlite3
fd90: 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a 20 6d 61 79  _config().** may
fda0: 20 6f 6e 6c 79 20 62 65 20 69 6e 76 6f 6b 65 64   only be invoked
fdb0: 20 70 72 69 6f 72 20 74 6f 20 6c 69 62 72 61 72   prior to librar
fdc0: 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  y initialization
fdd0: 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
fde0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
fdf0: 20 6f 72 20 61 66 74 65 72 20 73 68 75 74 64 6f   or after shutdo
fe00: 77 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 73  wn by [sqlite3_s
fe10: 68 75 74 64 6f 77 6e 28 29 5d 2e 0a 2a 2a 20 5e  hutdown()]..** ^
fe20: 49 66 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  If sqlite3_confi
fe30: 67 28 29 20 69 73 20 63 61 6c 6c 65 64 20 61 66  g() is called af
fe40: 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69  ter [sqlite3_ini
fe50: 74 69 61 6c 69 7a 65 28 29 5d 20 61 6e 64 20 62  tialize()] and b
fe60: 65 66 6f 72 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  efore.** [sqlite
fe70: 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 74 68  3_shutdown()] th
fe80: 65 6e 20 69 74 20 77 69 6c 6c 20 72 65 74 75 72  en it will retur
fe90: 6e 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2e  n SQLITE_MISUSE.
fea0: 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f 77 65 76 65  .** Note, howeve
feb0: 72 2c 20 74 68 61 74 20 5e 73 71 6c 69 74 65 33  r, that ^sqlite3
fec0: 5f 63 6f 6e 66 69 67 28 29 20 63 61 6e 20 62 65  _config() can be
fed0: 20 63 61 6c 6c 65 64 20 61 73 20 70 61 72 74 20   called as part 
fee0: 6f 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  of the.** implem
fef0: 65 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 61  entation of an a
ff00: 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
ff10: 65 64 20 5b 73 71 6c 69 74 65 33 5f 6f 73 5f 69  ed [sqlite3_os_i
ff20: 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  nit()]..**.** Th
ff30: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
ff40: 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66   to sqlite3_conf
ff50: 69 67 28 29 20 69 73 20 61 6e 20 69 6e 74 65 67  ig() is an integ
ff60: 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69 67 75 72 61  er.** [configura
ff70: 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68 61  tion option] tha
ff80: 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a 20  t determines.** 
ff90: 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f 66  what property of
ffa0: 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62 65   SQLite is to be
ffb0: 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53 75   configured.  Su
ffc0: 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e  bsequent argumen
ffd0: 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65 6e  ts.** vary depen
ffe0: 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 63 6f 6e  ding on the [con
fff0: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
10000 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72  n].** in the fir
10010 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a  st argument..**.
10020 2a 2a 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69  ** ^When a confi
10030 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
10040 69 73 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f  is set, sqlite3_
10050 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73  config() returns
10060 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
10070 20 5e 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20   ^If the option 
10080 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51  is unknown or SQ
10090 4c 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74  Lite is unable t
100a0 6f 20 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e  o set the option
100b0 0a 2a 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f  .** then this ro
100c0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20  utine returns a 
100d0 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20  non-zero [error 
100e0 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  code]..*/.int sq
100f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74  lite3_config(int
10100 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , ...);../*.** C
10110 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75  API3REF: Configu
10120 72 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  re database conn
10130 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  ections.**.** Th
10140 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  e sqlite3_db_con
10150 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
10160 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
10170 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a  configuration.**
10180 20 63 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64   changes to a [d
10190 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
101a0 6f 6e 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66  on].  The interf
101b0 61 63 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74  ace is similar t
101c0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
101d0 6e 66 69 67 28 29 5d 20 65 78 63 65 70 74 20 74  nfig()] except t
101e0 68 61 74 20 74 68 65 20 63 68 61 6e 67 65 73 20  hat the changes 
101f0 61 70 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c  apply to a singl
10200 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  e.** [database c
10210 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63  onnection] (spec
10220 69 66 69 65 64 20 69 6e 20 74 68 65 20 66 69 72  ified in the fir
10230 73 74 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a  st argument)..**
10240 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61  .** The second a
10250 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
10260 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56  e3_db_config(D,V
10270 2c 2e 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a  ,...)  is the.**
10280 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49   [SQLITE_DBCONFI
10290 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f  G_LOOKASIDE | co
102a0 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
102b0 5d 20 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63  ] - an integer c
102c0 6f 64 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64  ode .** that ind
102d0 69 63 61 74 65 73 20 77 68 61 74 20 61 73 70 65  icates what aspe
102e0 63 74 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  ct of the [datab
102f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
10300 69 73 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75  is being configu
10310 72 65 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65  red..** Subseque
10320 6e 74 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72  nt arguments var
10330 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
10340 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10350 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61   verb..**.** ^Ca
10360 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64  lls to sqlite3_d
10370 62 5f 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72  b_config() retur
10380 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61  n SQLITE_OK if a
10390 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68  nd only if.** th
103a0 65 20 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64  e call is consid
103b0 65 72 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e  ered successful.
103c0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
103d0 64 62 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65  db_config(sqlite
103e0 33 2a 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29  3*, int op, ...)
103f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
10400 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61  F: Memory Alloca
10410 74 69 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a  tion Routines.**
10420 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
10430 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64  of this object d
10440 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72  efines the inter
10450 66 61 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c  face between SQL
10460 69 74 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c  ite.** and low-l
10470 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
10480 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e  cation routines.
10490 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  .**.** This obje
104a0 63 74 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e  ct is used in on
104b0 6c 79 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20  ly one place in 
104c0 74 68 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72  the SQLite inter
104d0 66 61 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74  face..** A point
104e0 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63  er to an instanc
104f0 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
10500 20 69 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74   is the argument
10510 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
10520 63 6f 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74  config()] when t
10530 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  he configuration
10540 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53   option is.** [S
10550 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
10560 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  LOC] or [SQLITE_
10570 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
10580 5d 2e 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74  ].  .** By creat
10590 69 6e 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20  ing an instance 
105a0 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a  of this object.*
105b0 2a 20 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74  * and passing it
105c0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   to [sqlite3_con
105d0 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
105e0 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20  FIG_MALLOC]).** 
105f0 64 75 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61  during configura
10600 74 69 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61  tion, an applica
10610 74 69 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79  tion can specify
10620 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a   an alternative.
10630 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ** memory alloca
10640 74 69 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66  tion subsystem f
10650 6f 72 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65  or SQLite to use
10660 20 66 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a   for all of its.
10670 2a 2a 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72  ** dynamic memor
10680 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e  y needs..**.** N
10690 6f 74 65 20 74 68 61 74 20 53 51 4c 69 74 65 20  ote that SQLite 
106a0 63 6f 6d 65 73 20 77 69 74 68 20 73 65 76 65 72  comes with sever
106b0 61 6c 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  al [built-in mem
106c0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a  ory allocators].
106d0 2a 2a 20 74 68 61 74 20 61 72 65 20 70 65 72 66  ** that are perf
106e0 65 63 74 6c 79 20 61 64 65 71 75 61 74 65 20 66  ectly adequate f
106f0 6f 72 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d  or the overwhelm
10700 69 6e 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20  ing majority of 
10710 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20  applications.** 
10720 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 6f 62  and that this ob
10730 6a 65 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65  ject is only use
10740 66 75 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69  ful to a tiny mi
10750 6e 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63  nority of applic
10760 61 74 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73  ations.** with s
10770 70 65 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72  pecialized memor
10780 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10790 75 69 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73  uirements.  This
107a0 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c   object is.** al
107b0 73 6f 20 75 73 65 64 20 64 75 72 69 6e 67 20 74  so used during t
107c0 65 73 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65  esting of SQLite
107d0 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65   in order to spe
107e0 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
107f0 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
10800 6c 6f 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d  locator that sim
10810 75 6c 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75  ulates memory ou
10820 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64  t-of-memory cond
10830 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64  itions in.** ord
10840 65 72 20 74 6f 20 76 65 72 69 66 79 20 74 68 61  er to verify tha
10850 74 20 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72  t SQLite recover
10860 73 20 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f  s gracefully fro
10870 6d 20 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74  m such.** condit
10880 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ions..**.** The 
10890 78 4d 61 6c 6c 6f 63 2c 20 78 52 65 61 6c 6c 6f  xMalloc, xReallo
108a0 63 2c 20 61 6e 64 20 78 46 72 65 65 20 6d 65 74  c, and xFree met
108b0 68 6f 64 73 20 6d 75 73 74 20 77 6f 72 6b 20 6c  hods must work l
108c0 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61 6c 6c 6f  ike the.** mallo
108d0 63 28 29 2c 20 72 65 61 6c 6c 6f 63 28 29 20 61  c(), realloc() a
108e0 6e 64 20 66 72 65 65 28 29 20 66 75 6e 63 74 69  nd free() functi
108f0 6f 6e 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61  ons from the sta
10900 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
10910 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72  .** ^SQLite guar
10920 61 6e 74 65 65 73 20 74 68 61 74 20 74 68 65 20  antees that the 
10930 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
10940 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69  to.** xRealloc i
10950 73 20 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65  s always a value
10960 20 72 65 74 75 72 6e 65 64 20 62 79 20 61 20 70   returned by a p
10970 72 69 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f  rior call to xRo
10980 75 6e 64 75 70 2e 0a 2a 2a 0a 2a 2a 20 78 53 69  undup..**.** xSi
10990 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72 6e  ze should return
109a0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
109b0 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79 20  ize of a memory 
109c0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70 72  allocation.** pr
109d0 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e 65  eviously obtaine
109e0 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20 6f  d from xMalloc o
109f0 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68 65  r xRealloc.  The
10a00 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 0a   allocated size.
10a10 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74 20  ** is always at 
10a20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73 20  least as big as 
10a30 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73 69  the requested si
10a40 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c 61  ze but may be la
10a50 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  rger..**.** The 
10a60 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64 20  xRoundup method 
10a70 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f 75  returns what wou
10a80 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63 61  ld be the alloca
10a90 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20 61  ted size of.** a
10aa0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
10ab0 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74 69  on given a parti
10ac0 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64 20  cular requested 
10ad0 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d 6f  size.  Most memo
10ae0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72 73  ry.** allocators
10af0 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72 79   round up memory
10b00 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74 20   allocations at 
10b10 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65 78  least to the nex
10b20 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f 66  t multiple.** of
10b30 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63 61   8.  Some alloca
10b40 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74 6f  tors round up to
10b50 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69 70   a larger multip
10b60 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65 72  le or to a power
10b70 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79 20   of 2..** Every 
10b80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
10b90 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e 67  n request coming
10ba0 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71 6c   in through [sql
10bb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a 2a  ite3_malloc()].*
10bc0 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  * or [sqlite3_re
10bd0 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20 63  alloc()] first c
10be0 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20 20  alls xRoundup.  
10bf0 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74 75  If xRoundup retu
10c00 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74 20  rns 0, .** that 
10c10 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72 65  causes the corre
10c20 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79 20  sponding memory 
10c30 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66 61  allocation to fa
10c40 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 49  il..**.** The xI
10c50 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74 69  nit method initi
10c60 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f 72  alizes the memor
10c70 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 46 6f  y allocator.  Fo
10c80 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74  r example,.** it
10c90 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74 65 20   might allocate 
10ca0 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75 74 65  any require mute
10cb0 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c 69 7a  xes or initializ
10cc0 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 0a  e internal data.
10cd0 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e 20 20  ** structures.  
10ce0 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  The xShutdown me
10cf0 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65 64 20  thod is invoked 
10d00 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62 79 0a  (indirectly) by.
10d10 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74  ** [sqlite3_shut
10d20 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68 6f 75  down()] and shou
10d30 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20 61 6e  ld deallocate an
10d40 79 20 72 65 73 6f 75 72 63 65 73 20 61 63 71 75  y resources acqu
10d50 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e 69 74  ired.** by xInit
10d60 2e 20 20 54 68 65 20 70 41 70 70 44 61 74 61 20  .  The pAppData 
10d70 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65 64 20  pointer is used 
10d80 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
10d90 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49 6e 69  meter to.** xIni
10da0 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77 6e 2e  t and xShutdown.
10db0 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 68 6f  .**.** SQLite ho
10dc0 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  lds the [SQLITE_
10dd0 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d 41 53  MUTEX_STATIC_MAS
10de0 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65 6e 20  TER] mutex when 
10df0 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68  it invokes.** th
10e00 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 2c 20  e xInit method, 
10e10 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d 65 74  so the xInit met
10e20 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62 65 20  hod need not be 
10e30 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
10e40 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20 6d 65  .** xShutdown me
10e50 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63 61 6c  thod is only cal
10e60 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  led from [sqlite
10e70 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20 73 6f  3_shutdown()] so
10e80 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20   it does.** not 
10e90 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72 65 61  need to be threa
10ea0 64 73 61 66 65 20 65 69 74 68 65 72 2e 20 20 46  dsafe either.  F
10eb0 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d 65 74  or all other met
10ec0 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a 2a 20  hods, SQLite.** 
10ed0 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
10ee0 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
10ef0 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c 6f 6e  EM] mutex as lon
10f00 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c  g as the.** [SQL
10f10 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
10f20 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72 61 74  ATUS] configurat
10f30 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 74 75  ion option is tu
10f40 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68 0a 2a  rned on (which.*
10f50 2a 20 69 74 20 69 73 20 62 79 20 64 65 66 61 75  * it is by defau
10f60 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65 20 6d  lt) and so the m
10f70 65 74 68 6f 64 73 20 61 72 65 20 61 75 74 6f 6d  ethods are autom
10f80 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61 6c 69  atically seriali
10f90 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  zed..** However,
10fa0 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   if [SQLITE_CONF
10fb0 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 69 73  IG_MEMSTATUS] is
10fc0 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 6e 20   disabled, then 
10fd0 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 74  the other.** met
10fe0 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74 68 72  hods must be thr
10ff0 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73 65 20  eadsafe or else 
11000 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e 20 61  make their own a
11010 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f 72 0a  rrangements for.
11020 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69 6f 6e  ** serialization
11030 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 77  ..**.** SQLite w
11040 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65  ill never invoke
11050 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20 74 68   xInit() more th
11060 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75 74 20  an once without 
11070 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67 0a 2a  an intervening.*
11080 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75 74 64  * call to xShutd
11090 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65 64 65  own()..*/.typede
110a0 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
110b0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73 71 6c  _mem_methods sql
110c0 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73  ite3_mem_methods
110d0 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  ;.struct sqlite3
110e0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  _mem_methods {. 
110f0 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63   void *(*xMalloc
11100 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
11110 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  /* Memory alloca
11120 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20 2a 2f  tion function */
11130 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65 65 29  .  void (*xFree)
11140 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20  (void*);        
11150 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72 69 6f    /* Free a prio
11160 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  r allocation */.
11170 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61 6c 6c    void *(*xReall
11180 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29 3b 20  oc)(void*,int); 
11190 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20 61 6c   /* Resize an al
111a0 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
111b0 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69 64 2a  t (*xSize)(void*
111c0 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
111d0 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a 65 20  Return the size 
111e0 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  of an allocation
111f0 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52 6f 75   */.  int (*xRou
11200 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20 20 20  ndup)(int);     
11210 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20 75 70       /* Round up
11220 20 72 65 71 75 65 73 74 20 73 69 7a 65 20 74 6f   request size to
11230 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65   allocation size
11240 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49 6e 69   */.  int (*xIni
11250 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  t)(void*);      
11260 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61 6c 69       /* Initiali
11270 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  ze the memory al
11280 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f 69  locator */.  voi
11290 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29 28 76  d (*xShutdown)(v
112a0 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a 20 44  oid*);      /* D
112b0 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20  einitialize the 
112c0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
112d0 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70   */.  void *pApp
112e0 44 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 20  Data;           
112f0 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65 6e 74       /* Argument
11300 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e 64 20   to xInit() and 
11310 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d  xShutdown() */.}
11320 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
11330 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69 6f 6e  F: Configuration
11340 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57   Options.** KEYW
11350 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75 72 61  ORDS: {configura
11360 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a  tion option}.**.
11370 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e  ** These constan
11380 74 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c  ts are the avail
11390 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e  able integer con
113a0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
113b0 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62  ns that.** can b
113c0 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
113d0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
113e0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
113f0 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61  onfig()] interfa
11400 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63 6f  ce..**.** New co
11410 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11420 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ons may be added
11430 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
11440 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a  ses of SQLite..*
11450 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66 69  * Existing confi
11460 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73  guration options
11470 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f 6e   might be discon
11480 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63 61  tinued.  Applica
11490 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20  tions.** should 
114a0 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e  check the return
114b0 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c 69   code from [sqli
114c0 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f  te3_config()] to
114d0 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a   make sure that.
114e0 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b  ** the call work
114f0 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  ed.  The [sqlite
11500 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  3_config()] inte
11510 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72  rface will retur
11520 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20  n a.** non-zero 
11530 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
11540 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f  a discontinued o
11550 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f  r unsupported co
11560 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11570 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64  on.** is invoked
11580 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
11590 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
115a0 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d 20 3c  SINGLETHREAD]] <
115b0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
115c0 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c 2f 64  _SINGLETHREAD</d
115d0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
115e0 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
115f0 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
11600 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
11610 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
11620 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
11630 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20 20 49  ingle-thread.  I
11640 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
11650 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 61 6c  t disables.** al
11660 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64 20 70  l mutexing and p
11670 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74 6f 20  uts SQLite into 
11680 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69 74 20  a mode where it 
11690 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73 65 64  can only be used
116a0 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c 65 20  .** by a single 
116b0 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20 53 51  thread.   ^If SQ
116c0 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
116d0 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
116e0 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
116f0 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11700 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11710 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11720 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11730 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67 65 20  sible to change 
11740 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  the [threading m
11750 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20 64 65  ode] from its de
11760 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65 20 6f  fault.** value o
11770 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  f Single-thread 
11780 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65 33 5f  and so [sqlite3_
11790 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
117a0 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c 49 54  eturn .** [SQLIT
117b0 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
117c0 65 64 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  ed with the SQLI
117d0 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
117e0 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66 69 67  THREAD.** config
117f0 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c  uration option.<
11800 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
11810 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11820 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c  THREAD]] <dt>SQL
11830 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49  ITE_CONFIG_MULTI
11840 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
11850 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
11860 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
11870 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
11880 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
11890 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
118a0 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d 74 68  ode] to Multi-th
118b0 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
118c0 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
118d0 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67 20 6f  es.** mutexing o
118e0 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  n [database conn
118f0 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70 72 65  ection] and [pre
11900 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
11910 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54 68 65   objects..** The
11920 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20   application is 
11930 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 20  responsible for 
11940 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63 63 65  serializing acce
11950 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61 62 61  ss to.** [databa
11960 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
11970 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
11980 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75 74 20  atements].  But 
11990 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a 2a 2a  other mutexes.**
119a0 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73 6f 20   are enabled so 
119b0 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c  that SQLite will
119c0 20 62 65 20 73 61 66 65 20 74 6f 20 75 73 65 20   be safe to use 
119d0 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61  in a multi-threa
119e0 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e 6d 65  ded.** environme
119f0 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20 6e 6f  nt as long as no
11a00 20 74 77 6f 20 74 68 72 65 61 64 73 20 61 74 74   two threads att
11a10 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 20  empt to use the 
11a20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73  same.** [databas
11a30 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 74  e connection] at
11a40 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 20   the same time. 
11a50 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
11a60 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
11a70 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
11a80 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
11a90 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
11aa0 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
11ab0 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
11ac0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
11ad0 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d 74 68  set the Multi-th
11ae0 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e 67 20  read [threading 
11af0 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71  mode] and.** [sq
11b00 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11b10 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c  will return [SQL
11b20 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
11b30 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  lled with the.**
11b40 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
11b50 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e 66 69  ULTITHREAD confi
11b60 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e  guration option.
11b70 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11b80 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49  LITE_CONFIG_SERI
11b90 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53 51 4c  ALIZED]] <dt>SQL
11ba0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11bb0 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  LIZED</dt>.** <d
11bc0 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
11bd0 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
11be0 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
11bf0 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
11c00 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
11c10 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65  de] to Serialize
11c20 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  d. In other word
11c30 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65  s, this option e
11c40 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75  nables.** all mu
11c50 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20  texes including 
11c60 74 68 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a  the recursive.**
11c70 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74   mutexes on [dat
11c80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11c90 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
11ca0 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63  statement] objec
11cb0 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d  ts..** In this m
11cc0 6f 64 65 20 28 77 68 69 63 68 20 69 73 20 74 68  ode (which is th
11cd0 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53  e default when S
11ce0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
11cf0 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54  d with.** [SQLIT
11d00 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29  E_THREADSAFE=1])
11d10 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
11d20 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20  ary will itself 
11d30 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73  serialize access
11d40 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65  .** to [database
11d50 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e   connections] an
11d60 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
11d70 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20  ements] so that 
11d80 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69  the.** applicati
11d90 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20 75 73  on is free to us
11da0 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  e the same [data
11db0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
11dc0 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20   or the.** same 
11dd0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
11de0 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e  ent] in differen
11df0 74 20 74 68 72 65 61 64 73 20 61 74 20 74 68 65  t threads at the
11e00 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e   same time..** ^
11e10 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
11e20 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68  piled with.** th
11e30 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  e [SQLITE_THREAD
11e40 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48  SAFE | SQLITE_TH
11e50 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70  READSAFE=0] comp
11e60 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
11e70 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f  then.** it is no
11e80 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65  t possible to se
11e90 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64  t the Serialized
11ea0 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
11eb0 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  ] and.** [sqlite
11ec0 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
11ed0 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
11ee0 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64  ERROR] if called
11ef0 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c   with the.** SQL
11f00 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11f10 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74  LIZED configurat
11f20 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11f30 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11f40 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 5d 20  CONFIG_MALLOC]] 
11f50 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11f60 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  G_MALLOC</dt>.**
11f70 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
11f80 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
11f90 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
11fa0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
11fb0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
11fc0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
11fd0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
11fe0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
11ff0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
12000 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
12010 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79  low-level memory
12020 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74   allocation rout
12030 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20  ines to be used 
12040 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a 20 74  in place of.** t
12050 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
12060 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 62 75  tion routines bu
12070 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
12080 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  )^ ^SQLite makes
12090 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72 69 76  .** its own priv
120a0 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ate copy of the 
120b0 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b  content of the [
120c0 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
120d0 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 0a 2a  ods] structure.*
120e0 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b 73 71  * before the [sq
120f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
12100 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c 2f 64  call returns.</d
12110 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
12120 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
12130 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OC]] <dt>SQLITE_
12140 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43  CONFIG_GETMALLOC
12150 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
12160 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
12170 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
12180 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
12190 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
121a0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
121b0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
121c0 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
121d0 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d    The [sqlite3_m
121e0 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  em_methods].** s
121f0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
12200 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
12210 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 65  ently defined me
12220 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12230 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54  routines.)^.** T
12240 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  his option can b
12250 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f  e used to overlo
12260 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d  ad the default m
12270 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
12280 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
12290 68 20 61 20 77 72 61 70 70 65 72 20 74 68 61 74  h a wrapper that
122a0 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d 65 6d   simulations mem
122b0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66  ory allocation f
122c0 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74 72 61  ailure or.** tra
122d0 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61 67 65  cks memory usage
122e0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 3c  , for example. <
122f0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12300 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
12310 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  ATUS]] <dt>SQLIT
12320 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
12330 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  US</dt>.** <dd> 
12340 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  ^This option tak
12350 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65  es single argume
12360 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2c 20  nt of type int, 
12370 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
12380 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68   .** boolean, wh
12390 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72 20 64  ich enables or d
123a0 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c  isables the coll
123b0 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79  ection of memory
123c0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20   allocation .** 
123d0 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28 57 68  statistics. ^(Wh
123e0 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  en memory alloca
123f0 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12400 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20 74 68  are disabled, th
12410 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20  e .** following 
12420 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
12430 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65  s become non-ope
12440 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c  rational:.**   <
12450 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73  ul>.**   <li> [s
12460 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
12470 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20  ed()].**   <li> 
12480 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
12490 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20  highwater()].** 
124a0 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
124b0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
124c0 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  4()].**   <li> [
124d0 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73 28 29  sqlite3_status()
124e0 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a  ].**   </ul>)^.*
124f0 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  * ^Memory alloca
12500 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20  tion statistics 
12510 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
12520 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20 53 51  efault unless SQ
12530 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69  Lite is.** compi
12540 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45  led with [SQLITE
12550 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54  _DEFAULT_MEMSTAT
12560 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68 20 63  US]=0 in which c
12570 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c  ase memory.** al
12580 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74  location statist
12590 69 63 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ics are disabled
125a0 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
125b0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
125c0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
125d0 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  TCH]] <dt>SQLITE
125e0 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 3c  _CONFIG_SCRATCH<
125f0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
12600 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66  is option specif
12610 69 65 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d  ies a static mem
12620 6f 72 79 20 62 75 66 66 65 72 20 74 68 61 74 20  ory buffer that 
12630 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66  SQLite can use f
12640 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  or.** scratch me
12650 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61 72 65  mory.  There are
12660 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12670 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61 6e 20  :  A pointer an 
12680 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67 6e 65  8-byte.** aligne
12690 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20  d memory buffer 
126a0 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65 20 73  from which the s
126b0 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
126c0 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 64 72  ns will be.** dr
126d0 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  awn, the size of
126e0 20 65 61 63 68 20 73 63 72 61 74 63 68 20 61 6c   each scratch al
126f0 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c 0a 2a  location (sz),.*
12700 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69 6d 75  * and the maximu
12710 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63 72 61  m number of scra
12720 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20  tch allocations 
12730 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a 2a 20  (N).  The sz.** 
12740 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
12750 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 31   a multiple of 1
12760 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  6..** The first 
12770 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62 65  argument must be
12780 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12790 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20   8-byte aligned 
127a0 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61 74 20  buffer.** of at 
127b0 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73  least sz*N bytes
127c0 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e   of memory..** ^
127d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
127e0 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74 77 6f  no more than two
127f0 20 73 63 72 61 74 63 68 20 62 75 66 66 65 72 73   scratch buffers
12800 20 70 65 72 20 74 68 72 65 61 64 2e 20 20 53 6f   per thread.  So
12810 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62 65 20  .** N should be 
12820 73 65 74 20 74 6f 20 74 77 69 63 65 20 74 68 65  set to twice the
12830 20 65 78 70 65 63 74 65 64 20 6d 61 78 69 6d 75   expected maximu
12840 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68 72 65  m number of thre
12850 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ads..** ^SQLite 
12860 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71 75 69  will never requi
12870 72 65 20 61 20 73 63 72 61 74 63 68 20 62 75 66  re a scratch buf
12880 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f 72 65  fer that is more
12890 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d 65 73   than 6.** times
128a0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70 61   the database pa
128b0 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53 51 4c  ge size. ^If SQL
128c0 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64 73 20  ite needs needs 
128d0 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 73 63  additional.** sc
128e0 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62 65 79  ratch memory bey
128f0 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f 76  ond what is prov
12900 69 64 65 64 20 62 79 20 74 68 69 73 20 63 6f 6e  ided by this con
12910 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
12920 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73 71 6c  n, then .** [sql
12930 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 77  ite3_malloc()] w
12940 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f 20 6f  ill be used to o
12950 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79  btain the memory
12960 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a 2a 2a   needed.</dd>.**
12970 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12980 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 5d 20  FIG_PAGECACHE]] 
12990 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
129a0 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64 74 3e  G_PAGECACHE</dt>
129b0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
129c0 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20  ption specifies 
129d0 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20  a static memory 
129e0 62 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69  buffer that SQLi
129f0 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a  te can use for.*
12a00 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 70  * the database p
12a10 61 67 65 20 63 61 63 68 65 20 77 69 74 68 20 74  age cache with t
12a20 68 65 20 64 65 66 61 75 6c 74 20 70 61 67 65 20  he default page 
12a30 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
12a40 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73 20  tion.  .** This 
12a50 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73 68  configuration sh
12a60 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65 64  ould not be used
12a70 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69   if an applicati
12a80 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a 2a  on-define page.*
12a90 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  * cache implemen
12aa0 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65 64  tation is loaded
12ab0 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49 54   using the SQLIT
12ac0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
12ad0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
12ae0 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
12af0 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
12b00 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
12b10 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
12b20 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
12b30 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
12b40 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
12b50 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
12b60 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
12b70 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
12b80 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
12b90 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
12ba0 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
12bb0 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
12bc0 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
12bd0 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
12be0 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
12bf0 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
12c00 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
12c10 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
12c20 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
12c30 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
12c40 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
12c50 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
12c60 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
12c70 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
12c80 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
12c90 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
12ca0 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
12cb0 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
12cc0 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
12cd0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
12ce0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
12cf0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
12d00 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
12d10 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
12d20 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
12d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
12d40 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
12d50 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
12d60 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
12d70 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
12d80 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
12d90 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
12da0 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
12db0 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
12dc0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
12dd0 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
12de0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
12df0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
12e00 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
12e10 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
12e20 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
12e30 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
12e40 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
12e50 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
12e60 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
12e70 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
12e80 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
12e90 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
12ea0 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
12eb0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
12ec0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
12ed0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
12ee0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
12ef0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12f00 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12f10 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12f20 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12f30 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
12f40 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
12f50 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
12f60 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
12f70 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
12f80 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
12f90 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
12fa0 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
12fb0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
12fc0 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
12fd0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12fe0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
12ff0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
13000 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
13010 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
13020 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
13030 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
13040 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
13050 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
13060 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
13070 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
13080 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
13090 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
130a0 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
130b0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
130c0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
130d0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
130e0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
130f0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
13100 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
13110 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
13120 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
13130 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
13140 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
13150 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
13160 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
13170 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
13180 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
13190 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
131a0 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
131b0 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
131c0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
131d0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
131e0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
131f0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
13200 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
13210 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
13220 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
13230 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
13240 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
13250 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
13260 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
13270 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
13280 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
13290 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
132a0 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
132b0 73 20 63 61 70 70 65 64 20 61 74 20 32 2a 2a 31  s capped at 2**1
132c0 32 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61  2. Reasonable va
132d0 6c 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20  lues.** for the 
132e0 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
132f0 6f 6e 20 73 69 7a 65 20 61 72 65 20 32 2a 2a 35  on size are 2**5
13300 20 74 68 72 6f 75 67 68 20 32 2a 2a 38 2e 3c 2f   through 2**8.</
13310 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13320 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d  TE_CONFIG_MUTEX]
13330 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
13340 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  FIG_MUTEX</dt>.*
13350 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
13360 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13370 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13380 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
13390 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
133a0 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
133b0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
133c0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
133d0 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66   argument specif
133e0 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69  ies.** alternati
133f0 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74  ve low-level mut
13400 65 78 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62  ex routines to b
13410 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65 0a  e used in place.
13420 2a 2a 20 74 68 65 20 6d 75 74 65 78 20 72 6f 75  ** the mutex rou
13430 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
13440 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c   SQLite.)^  ^SQL
13450 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
13460 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65   of the.** conte
13470 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
13480 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
13490 5d 20 73 74 72 75 63 74 75 72 65 20 62 65 66 6f  ] structure befo
134a0 72 65 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a  re the call to.*
134b0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
134c0 67 28 29 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49  g()] returns. ^I
134d0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
134e0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
134f0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
13500 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
13510 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
13520 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
13530 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
13540 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
13550 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
13560 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
13570 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
13580 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
13590 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
135a0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
135b0 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69  UTEX configurati
135c0 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a  on option will.*
135d0 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  * return [SQLITE
135e0 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a  _ERROR].</dd>.**
135f0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13600 46 49 47 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c  FIG_GETMUTEX]] <
13610 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
13620 5f 47 45 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a  _GETMUTEX</dt>.*
13630 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
13640 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
13650 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
13660 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
13670 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
13680 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
13690 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d  3_mutex_methods]
136a0 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
136b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  .** [sqlite3_mut
136c0 65 78 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73  ex_methods].** s
136d0 74 72 75 63 74 75 72 65 20 69 73 20 66 69 6c 6c  tructure is fill
136e0 65 64 20 77 69 74 68 20 74 68 65 20 63 75 72 72  ed with the curr
136f0 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20 6d 75  ently defined mu
13700 74 65 78 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a  tex routines.)^.
13710 2a 2a 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63  ** This option c
13720 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76  an be used to ov
13730 65 72 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75  erload the defau
13740 6c 74 20 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74  lt mutex allocat
13750 69 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ion.** routines 
13760 77 69 74 68 20 61 20 77 72 61 70 70 65 72 20 75  with a wrapper u
13770 73 65 64 20 74 6f 20 74 72 61 63 6b 20 6d 75 74  sed to track mut
13780 65 78 20 75 73 61 67 65 20 66 6f 72 20 70 65 72  ex usage for per
13790 66 6f 72 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66  formance.** prof
137a0 69 6c 69 6e 67 20 6f 72 20 74 65 73 74 69 6e 67  iling or testing
137b0 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20  , for example.  
137c0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
137d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
137e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
137f0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
13800 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
13810 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
13820 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
13830 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
13840 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
13850 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
13860 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
13870 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
13880 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
13890 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
138a0 47 5f 47 45 54 4d 55 54 45 58 20 63 6f 6e 66 69  G_GETMUTEX confi
138b0 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20  guration option 
138c0 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b  will.** return [
138d0 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f  SQLITE_ERROR].</
138e0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
138f0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  TE_CONFIG_LOOKAS
13900 49 44 45 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  IDE]] <dt>SQLITE
13910 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  _CONFIG_LOOKASID
13920 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  E</dt>.** <dd> ^
13930 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
13940 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
13950 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
13960 74 68 65 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d  the default.** m
13970 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
13980 20 66 6f 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69   for the lookasi
13990 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
139a0 74 6f 72 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b  tor on each.** [
139b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
139c0 69 6f 6e 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ion].  The first
139d0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
139e0 0a 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68  .** size of each
139f0 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65   lookaside buffe
13a00 72 20 73 6c 6f 74 20 61 6e 64 20 74 68 65 20 73  r slot and the s
13a10 65 63 6f 6e 64 20 69 73 20 74 68 65 20 6e 75 6d  econd is the num
13a20 62 65 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20  ber of.** slots 
13a30 61 6c 6c 6f 63 61 74 65 64 20 74 6f 20 65 61 63  allocated to eac
13a40 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  h database conne
13a50 63 74 69 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73  ction.)^  ^(This
13a60 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
13a70 0a 2a 2a 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f  .** <i>default</
13a80 69 3e 20 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a  i> lookaside siz
13a90 65 2e 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 44  e. The [SQLITE_D
13aa0 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
13ab0 45 5d 0a 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73  E].** verb to [s
13ac0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
13ad0 28 29 5d 20 63 61 6e 20 62 65 20 75 73 65 64 20  ()] can be used 
13ae0 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 6c 6f  to change the lo
13af0 6f 6b 61 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69  okaside.** confi
13b00 67 75 72 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69  guration on indi
13b10 76 69 64 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f  vidual connectio
13b20 6e 73 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ns.)^ </dd>.**.*
13b30 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
13b40 47 5f 50 43 41 43 48 45 32 5d 5d 20 3c 64 74 3e  G_PCACHE2]] <dt>
13b50 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
13b60 41 43 48 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHE2</dt>.** <d
13b70 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e  d> ^(This option
13b80 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20   takes a single 
13b90 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
13ba0 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a  s a pointer to.*
13bb0 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70 63  * an [sqlite3_pc
13bc0 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f  ache_methods2] o
13bd0 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
13be0 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
13bf0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
13c00 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
13c10 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
13c20 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
13c30 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
13c40 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
13c50 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
13c60 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
13c70 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
13c80 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
13c90 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
13ca0 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45  HE2]] <dt>SQLITE
13cb0 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48  _CONFIG_GETPCACH
13cc0 45 32 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  E2</dt>.** <dd> 
13cd0 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
13ce0 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
13cf0 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
13d00 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
13d10 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68  * [sqlite3_pcach
13d20 65 5f 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65  e_methods2] obje
13d30 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70 69  ct.  SQLite copi
13d40 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e  es of the curren
13d50 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  t.** page cache 
13d60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
13d70 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74 2e  nto that object.
13d80 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
13d90 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  [SQLITE_CONFIG_L
13da0 4f 47 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f  OG]] <dt>SQLITE_
13db0 43 4f 4e 46 49 47 5f 4c 4f 47 3c 2f 64 74 3e 0a  CONFIG_LOG</dt>.
13dc0 2a 2a 20 3c 64 64 3e 20 54 68 65 20 53 51 4c 49  ** <dd> The SQLI
13dd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70  TE_CONFIG_LOG op
13de0 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20  tion is used to 
13df0 63 6f 6e 66 69 67 75 72 65 20 74 68 65 20 53 51  configure the SQ
13e00 4c 69 74 65 0a 2a 2a 20 67 6c 6f 62 61 6c 20 5b  Lite.** global [
13e10 65 72 72 6f 72 20 6c 6f 67 5d 2e 0a 2a 2a 20 28  error log]..** (
13e20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
13e30 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
13e40 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
13e50 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
13e60 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
13e70 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
13e80 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
13e90 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
13ea0 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
13eb0 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
13ec0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
13ed0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
13ee0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
13ef0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
13f00 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
13f10 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
13f20 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
13f30 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
13f40 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
13f50 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
13f60 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
13f70 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
13f80 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
13f90 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
13fa0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13fb0 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
13fc0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
13fd0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
13fe0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
13ff0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
14000 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
14010 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
14020 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
14030 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
14040 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
14050 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
14060 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
14070 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
14080 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
14090 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
140a0 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
140b0 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
140c0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
140d0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
140e0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
140f0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
14100 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
14110 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
14120 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
14130 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
14140 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
14150 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
14160 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
14170 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
14180 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
14190 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
141a0 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
141b0 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
141c0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
141d0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
141e0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
141f0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
14200 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
14210 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
14220 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14230 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14240 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
14250 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
14260 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
14270 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
14280 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14290 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 5e 28  IG_URI.** <dd>^(
142a0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
142b0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
142c0 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e  ent of type int.
142d0 20 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68   If non-zero, th
142e0 65 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69  en.** URI handli
142f0 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65  ng is globally e
14300 6e 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70  nabled. If the p
14310 61 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f  arameter is zero
14320 2c 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c  , then URI handl
14330 69 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c  ing.** is global
14340 6c 79 20 64 69 73 61 62 6c 65 64 2e 29 5e 20 5e  ly disabled.)^ ^
14350 49 66 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20  If URI handling 
14360 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62  is globally enab
14370 6c 65 64 2c 20 61 6c 6c 20 66 69 6c 65 6e 61 6d  led, all filenam
14380 65 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 6f 20  es.** passed to 
14390 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
143a0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
143b0 76 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  v2()], [sqlite3_
143c0 6f 70 65 6e 31 36 28 29 5d 20 6f 72 0a 2a 2a 20  open16()] or.** 
143d0 73 70 65 63 69 66 69 65 64 20 61 73 20 70 61 72  specified as par
143e0 74 20 6f 66 20 5b 41 54 54 41 43 48 5d 20 63 6f  t of [ATTACH] co
143f0 6d 6d 61 6e 64 73 20 61 72 65 20 69 6e 74 65 72  mmands are inter
14400 70 72 65 74 65 64 20 61 73 20 55 52 49 73 2c 20  preted as URIs, 
14410 72 65 67 61 72 64 6c 65 73 73 0a 2a 2a 20 6f 66  regardless.** of
14420 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
14430 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
14440 5f 55 52 49 5d 20 66 6c 61 67 20 69 73 20 73 65  _URI] flag is se
14450 74 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  t when the datab
14460 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
14470 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 49 66  n is opened. ^If
14480 20 69 74 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20   it is globally 
14490 64 69 73 61 62 6c 65 64 2c 20 66 69 6c 65 6e 61  disabled, filena
144a0 6d 65 73 20 61 72 65 0a 2a 2a 20 6f 6e 6c 79 20  mes are.** only 
144b0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55  interpreted as U
144c0 52 49 73 20 69 66 20 74 68 65 20 53 51 4c 49 54  RIs if the SQLIT
144d0 45 5f 4f 50 45 4e 5f 55 52 49 20 66 6c 61 67 20  E_OPEN_URI flag 
144e0 69 73 20 73 65 74 20 77 68 65 6e 20 74 68 65 0a  is set when the.
144f0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
14500 65 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 65 64  ection is opened
14510 2e 20 5e 28 42 79 20 64 65 66 61 75 6c 74 2c 20  . ^(By default, 
14520 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20  URI handling is 
14530 67 6c 6f 62 61 6c 6c 79 0a 2a 2a 20 64 69 73 61  globally.** disa
14540 62 6c 65 64 2e 20 54 68 65 20 64 65 66 61 75 6c  bled. The defaul
14550 74 20 76 61 6c 75 65 20 6d 61 79 20 62 65 20 63  t value may be c
14560 68 61 6e 67 65 64 20 62 79 20 63 6f 6d 70 69 6c  hanged by compil
14570 69 6e 67 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  ing with the.** 
14580 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49 5d  [SQLITE_USE_URI]
14590 20 73 79 6d 62 6f 6c 20 64 65 66 69 6e 65 64 2e   symbol defined.
145a0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
145b0 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52 49 4e  E_CONFIG_COVERIN
145c0 47 5f 49 4e 44 45 58 5f 53 43 41 4e 5d 5d 20 3c  G_INDEX_SCAN]] <
145d0 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
145e0 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f  _COVERING_INDEX_
145f0 53 43 41 4e 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69  SCAN.** <dd>^Thi
14600 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
14610 20 73 69 6e 67 6c 65 20 69 6e 74 65 67 65 72 20   single integer 
14620 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69  argument which i
14630 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
14640 0a 2a 2a 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e  .** a boolean in
14650 20 6f 72 64 65 72 20 74 6f 20 65 6e 61 62 6c 65   order to enable
14660 20 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20   or disable the 
14670 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e 67 20  use of covering 
14680 69 6e 64 69 63 65 73 20 66 6f 72 0a 2a 2a 20 66  indices for.** f
14690 75 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 20  ull table scans 
146a0 69 6e 20 74 68 65 20 71 75 65 72 79 20 6f 70 74  in the query opt
146b0 69 6d 69 7a 65 72 2e 20 20 5e 54 68 65 20 64 65  imizer.  ^The de
146c0 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 69 73  fault setting is
146d0 20 64 65 74 65 72 6d 69 6e 65 64 0a 2a 2a 20 62   determined.** b
146e0 79 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 41 4c  y the [SQLITE_AL
146f0 4c 4f 57 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  LOW_COVERING_IND
14700 45 58 5f 53 43 41 4e 5d 20 63 6f 6d 70 69 6c 65  EX_SCAN] compile
14710 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 6f 72  -time option, or
14720 20 69 73 20 22 6f 6e 22 0a 2a 2a 20 69 66 20 74   is "on".** if t
14730 68 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  hat compile-time
14740 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74   option is omitt
14750 65 64 2e 0a 2a 2a 20 54 68 65 20 61 62 69 6c 69  ed..** The abili
14760 74 79 20 74 6f 20 64 69 73 61 62 6c 65 20 74 68  ty to disable th
14770 65 20 75 73 65 20 6f 66 20 63 6f 76 65 72 69 6e  e use of coverin
14780 67 20 69 6e 64 69 63 65 73 20 66 6f 72 20 66 75  g indices for fu
14790 6c 6c 20 74 61 62 6c 65 20 73 63 61 6e 73 0a 2a  ll table scans.*
147a0 2a 20 69 73 20 62 65 63 61 75 73 65 20 73 6f 6d  * is because som
147b0 65 20 69 6e 63 6f 72 72 65 63 74 6c 79 20 63 6f  e incorrectly co
147c0 64 65 64 20 6c 65 67 61 63 79 20 61 70 70 6c 69  ded legacy appli
147d0 63 61 74 69 6f 6e 73 20 6d 69 67 68 74 20 6d 61  cations might ma
147e0 6c 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 68 65  lfunction.** whe
147f0 6e 20 74 68 65 20 6f 70 74 69 6d 69 7a 61 74 69  n the optimizati
14800 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 20 20  on is enabled.  
14810 50 72 6f 76 69 64 69 6e 67 20 74 68 65 20 61 62  Providing the ab
14820 69 6c 69 74 79 20 74 6f 0a 2a 2a 20 64 69 73 61  ility to.** disa
14830 62 6c 65 20 74 68 65 20 6f 70 74 69 6d 69 7a 61  ble the optimiza
14840 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 74 68 65 20  tion allows the 
14850 6f 6c 64 65 72 2c 20 62 75 67 67 79 20 61 70 70  older, buggy app
14860 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 74 6f  lication code to
14870 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 6f 75 74   work.** without
14880 20 63 68 61 6e 67 65 20 65 76 65 6e 20 77 69 74   change even wit
14890 68 20 6e 65 77 65 72 20 76 65 72 73 69 6f 6e 73  h newer versions
148a0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
148b0 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
148c0 47 5f 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c  G_PCACHE]] [[SQL
148d0 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
148e0 41 43 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51  ACHE]].** <dt>SQ
148f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43  LITE_CONFIG_PCAC
14900 48 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f  HE and SQLITE_CO
14910 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a  NFIG_GETPCACHE.*
14920 2a 20 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74  * <dd> These opt
14930 69 6f 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74  ions are obsolet
14940 65 20 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74  e and should not
14950 20 62 65 20 75 73 65 64 20 62 79 20 6e 65 77 20   be used by new 
14960 63 6f 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72  code..** They ar
14970 65 20 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62  e retained for b
14980 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
14990 62 69 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e  bility but are n
149a0 6f 77 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f  ow no-ops..** </
149b0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
149c0 54 45 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47  TE_CONFIG_SQLLOG
149d0 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45  ]].** <dt>SQLITE
149e0 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 0a 2a  _CONFIG_SQLLOG.*
149f0 2a 20 3c 64 64 3e 54 68 69 73 20 6f 70 74 69 6f  * <dd>This optio
14a00 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69 6c 61  n is only availa
14a10 62 6c 65 20 69 66 20 73 71 6c 69 74 65 20 69 73  ble if sqlite is
14a20 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
14a30 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
14a40 41 42 4c 45 5f 53 51 4c 4c 4f 47 5d 20 70 72 65  ABLE_SQLLOG] pre
14a50 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f  -processor macro
14a60 20 64 65 66 69 6e 65 64 2e 20 54 68 65 20 66 69   defined. The fi
14a70 72 73 74 20 61 72 67 75 6d 65 6e 74 20 73 68 6f  rst argument sho
14a80 75 6c 64 0a 2a 2a 20 62 65 20 61 20 70 6f 69 6e  uld.** be a poin
14a90 74 65 72 20 74 6f 20 61 20 66 75 6e 63 74 69 6f  ter to a functio
14aa0 6e 20 6f 66 20 74 79 70 65 20 76 6f 69 64 28 2a  n of type void(*
14ab0 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
14ac0 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e  ,const char*, in
14ad0 74 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  t)..** The secon
14ae0 64 20 73 68 6f 75 6c 64 20 62 65 20 6f 66 20 74  d should be of t
14af0 79 70 65 20 28 76 6f 69 64 2a 29 2e 20 54 68 65  ype (void*). The
14b00 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
14b10 6f 6b 65 64 20 62 79 20 74 68 65 20 6c 69 62 72  oked by the libr
14b20 61 72 79 0a 2a 2a 20 69 6e 20 74 68 72 65 65 20  ary.** in three 
14b30 73 65 70 61 72 61 74 65 20 63 69 72 63 75 6d 73  separate circums
14b40 74 61 6e 63 65 73 2c 20 69 64 65 6e 74 69 66 69  tances, identifi
14b50 65 64 20 62 79 20 74 68 65 20 76 61 6c 75 65 20  ed by the value 
14b60 70 61 73 73 65 64 20 61 73 20 74 68 65 0a 2a 2a  passed as the.**
14b70 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
14b80 72 2e 20 49 66 20 74 68 65 20 66 6f 75 72 74 68  r. If the fourth
14b90 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 30 2c   parameter is 0,
14ba0 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61   then the databa
14bb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
14bc0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
14bd0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 68  econd argument h
14be0 61 73 20 6a 75 73 74 20 62 65 65 6e 20 6f 70 65  as just been ope
14bf0 6e 65 64 2e 20 54 68 65 20 74 68 69 72 64 20 61  ned. The third a
14c00 72 67 75 6d 65 6e 74 0a 2a 2a 20 70 6f 69 6e 74  rgument.** point
14c10 73 20 74 6f 20 61 20 62 75 66 66 65 72 20 63 6f  s to a buffer co
14c20 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 6e 61 6d  ntaining the nam
14c30 65 20 6f 66 20 74 68 65 20 6d 61 69 6e 20 64 61  e of the main da
14c40 74 61 62 61 73 65 20 66 69 6c 65 2e 20 49 66 20  tabase file. If 
14c50 74 68 65 0a 2a 2a 20 66 6f 75 72 74 68 20 70 61  the.** fourth pa
14c60 72 61 6d 65 74 65 72 20 69 73 20 31 2c 20 74 68  rameter is 1, th
14c70 65 6e 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  en the SQL state
14c80 6d 65 6e 74 20 74 68 61 74 20 74 68 65 20 74 68  ment that the th
14c90 69 72 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a  ird parameter.**
14ca0 20 70 6f 69 6e 74 73 20 74 6f 20 68 61 73 20 6a   points to has j
14cb0 75 73 74 20 62 65 65 6e 20 65 78 65 63 75 74 65  ust been execute
14cc0 64 2e 20 4f 72 2c 20 69 66 20 74 68 65 20 66 6f  d. Or, if the fo
14cd0 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  urth parameter i
14ce0 73 20 32 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65  s 2, then.** the
14cf0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 69 6e   connection bein
14d00 67 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  g passed as the 
14d10 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
14d20 20 69 73 20 62 65 69 6e 67 20 63 6c 6f 73 65 64   is being closed
14d30 2e 20 54 68 65 0a 2a 2a 20 74 68 69 72 64 20 70  . The.** third p
14d40 61 72 61 6d 65 74 65 72 20 69 73 20 70 61 73 73  arameter is pass
14d50 65 64 20 4e 55 4c 4c 20 49 6e 20 74 68 69 73 20  ed NULL In this 
14d60 63 61 73 65 2e 20 20 41 6e 20 65 78 61 6d 70 6c  case.  An exampl
14d70 65 20 6f 66 20 75 73 69 6e 67 20 74 68 69 73 0a  e of using this.
14d80 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
14d90 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 73   option can be s
14da0 65 65 6e 20 69 6e 20 74 68 65 20 22 74 65 73 74  een in the "test
14db0 5f 73 71 6c 6c 6f 67 2e 63 22 20 73 6f 75 72 63  _sqllog.c" sourc
14dc0 65 20 66 69 6c 65 20 69 6e 0a 2a 2a 20 74 68 65  e file in.** the
14dd0 20 63 61 6e 6f 6e 69 63 61 6c 20 53 51 4c 69 74   canonical SQLit
14de0 65 20 73 6f 75 72 63 65 20 74 72 65 65 2e 3c 2f  e source tree.</
14df0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
14e00 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53  TE_CONFIG_MMAP_S
14e10 49 5a 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c  IZE]].** <dt>SQL
14e20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14e30 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 53 51 4c  SIZE.** <dd>^SQL
14e40 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 4d 41 50 5f  ITE_CONFIG_MMAP_
14e50 53 49 5a 45 20 74 61 6b 65 73 20 74 77 6f 20 36  SIZE takes two 6
14e60 34 2d 62 69 74 20 69 6e 74 65 67 65 72 20 28 73  4-bit integer (s
14e70 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 20 76 61  qlite3_int64) va
14e80 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  lues.** that are
14e90 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 6d 61   the default mma
14ea0 70 20 73 69 7a 65 20 6c 69 6d 69 74 20 28 74 68  p size limit (th
14eb0 65 20 64 65 66 61 75 6c 74 20 73 65 74 74 69 6e  e default settin
14ec0 67 20 66 6f 72 0a 2a 2a 20 5b 50 52 41 47 4d 41  g for.** [PRAGMA
14ed0 20 6d 6d 61 70 5f 73 69 7a 65 5d 29 20 61 6e 64   mmap_size]) and
14ee0 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c 6c   the maximum all
14ef0 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 20 6c  owed mmap size l
14f00 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68 65 20 64 65  imit..** ^The de
14f10 66 61 75 6c 74 20 73 65 74 74 69 6e 67 20 63 61  fault setting ca
14f20 6e 20 62 65 20 6f 76 65 72 72 69 64 64 65 6e 20  n be overridden 
14f30 62 79 20 65 61 63 68 20 64 61 74 61 62 61 73 65  by each database
14f40 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 75 73 69 6e   connection usin
14f50 67 0a 2a 2a 20 65 69 74 68 65 72 20 74 68 65 20  g.** either the 
14f60 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
14f70 65 5d 20 63 6f 6d 6d 61 6e 64 2c 20 6f 72 20 62  e] command, or b
14f80 79 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b  y using the.** [
14f90 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41  SQLITE_FCNTL_MMA
14fa0 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20 63 6f 6e  P_SIZE] file con
14fb0 74 72 6f 6c 2e 20 20 5e 28 54 68 65 20 6d 61 78  trol.  ^(The max
14fc0 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20 6d 6d 61  imum allowed mma
14fd0 70 20 73 69 7a 65 0a 2a 2a 20 63 61 6e 6e 6f 74  p size.** cannot
14fe0 20 62 65 20 63 68 61 6e 67 65 64 20 61 74 20 72   be changed at r
14ff0 75 6e 2d 74 69 6d 65 2e 20 20 4e 6f 72 20 6d 61  un-time.  Nor ma
15000 79 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 61 6c  y the maximum al
15010 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a 65 0a  lowed mmap size.
15020 2a 2a 20 65 78 63 65 65 64 20 74 68 65 20 63 6f  ** exceed the co
15030 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 61 78 69 6d  mpile-time maxim
15040 75 6d 20 6d 6d 61 70 20 73 69 7a 65 20 73 65 74  um mmap size set
15050 20 62 79 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49   by the.** [SQLI
15060 54 45 5f 4d 41 58 5f 4d 4d 41 50 5f 53 49 5a 45  TE_MAX_MMAP_SIZE
15070 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
15080 70 74 69 6f 6e 2e 29 5e 0a 2a 2a 20 5e 49 66 20  ption.)^.** ^If 
15090 65 69 74 68 65 72 20 61 72 67 75 6d 65 6e 74 20  either argument 
150a0 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  to this option i
150b0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
150c0 20 74 68 61 74 20 61 72 67 75 6d 65 6e 74 20 69   that argument i
150d0 73 0a 2a 2a 20 63 68 61 6e 67 65 64 20 74 6f 20  s.** changed to 
150e0 69 74 73 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  its compile-time
150f0 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20   default..**.** 
15100 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
15110 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 5d 5d  WIN32_HEAPSIZE]]
15120 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
15130 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45 41 50  ONFIG_WIN32_HEAP
15140 53 49 5a 45 0a 2a 2a 20 3c 64 64 3e 5e 54 68 69  SIZE.** <dd>^Thi
15150 73 20 6f 70 74 69 6f 6e 20 69 73 20 6f 6e 6c 79  s option is only
15160 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 53 51   available if SQ
15170 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
15180 20 66 6f 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20   for Windows.** 
15190 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
151a0 5f 57 49 4e 33 32 5f 4d 41 4c 4c 4f 43 5d 20 70  _WIN32_MALLOC] p
151b0 72 65 2d 70 72 6f 63 65 73 73 6f 72 20 6d 61 63  re-processor mac
151c0 72 6f 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 53  ro defined..** S
151d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e  QLITE_CONFIG_WIN
151e0 33 32 5f 48 45 41 50 53 49 5a 45 20 74 61 6b 65  32_HEAPSIZE take
151f0 73 20 61 20 33 32 2d 62 69 74 20 75 6e 73 69 67  s a 32-bit unsig
15200 6e 65 64 20 69 6e 74 65 67 65 72 20 76 61 6c 75  ned integer valu
15210 65 0a 2a 2a 20 74 68 61 74 20 73 70 65 63 69 66  e.** that specif
15220 69 65 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20  ies the maximum 
15230 73 69 7a 65 20 6f 66 20 74 68 65 20 63 72 65 61  size of the crea
15240 74 65 64 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 64  ted heap..** </d
15250 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
15260 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
15270 4c 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20  LETHREAD  1  /* 
15280 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
15290 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
152a0 54 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a  TITHREAD   2  /*
152b0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
152c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
152d0 52 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f  RIALIZED    3  /
152e0 2a 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65  * nil */.#define
152f0 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15300 41 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20  ALLOC        4  
15310 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  /* sqlite3_mem_m
15320 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69  ethods* */.#defi
15330 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
15340 5f 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35  _GETMALLOC     5
15350 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d    /* sqlite3_mem
15360 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65  _methods* */.#de
15370 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15380 49 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20  IG_SCRATCH      
15390 20 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e   6  /* void*, in
153a0 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23  t sz, int N */.#
153b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
153c0 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20  NFIG_PAGECACHE  
153d0 20 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20     7  /* void*, 
153e0 69 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f  int sz, int N */
153f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15400 43 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20  CONFIG_HEAP     
15410 20 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a       8  /* void*
15420 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74  , int nByte, int
15430 20 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20   min */.#define 
15440 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
15450 4d 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f  MSTATUS     9  /
15460 2a 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65  * boolean */.#de
15470 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15480 49 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20  IG_MUTEX        
15490 31 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d  10  /* sqlite3_m
154a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  utex_methods* */
154b0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
154c0 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20  CONFIG_GETMUTEX 
154d0 20 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74      11  /* sqlit
154e0 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73  e3_mutex_methods
154f0 2a 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73  * */./* previous
15500 6c 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ly SQLITE_CONFIG
15510 5f 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77  _CHUNKALLOC 12 w
15520 68 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73  hich is now unus
15530 65 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20  ed. */ .#define 
15540 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
15550 4f 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f  OKASIDE    13  /
15560 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65  * int int */.#de
15570 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15580 49 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20  IG_PCACHE       
15590 31 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a  14  /* no-op */.
155a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
155b0 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20  ONFIG_GETPCACHE 
155c0 20 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20     15  /* no-op 
155d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
155e0 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20  E_CONFIG_LOG    
155f0 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75        16  /* xFu
15600 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65  nc, void* */.#de
15610 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15620 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20  IG_URI          
15630 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64  17  /* int */.#d
15640 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15650 46 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20  FIG_PCACHE2     
15660 20 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   18  /* sqlite3_
15670 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a  pcache_methods2*
15680 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15690 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41  TE_CONFIG_GETPCA
156a0 43 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71  CHE2   19  /* sq
156b0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
156c0 68 6f 64 73 32 2a 20 2a 2f 0a 23 64 65 66 69 6e  hods2* */.#defin
156d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
156e0 43 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53  COVERING_INDEX_S
156f0 43 41 4e 20 32 30 20 20 2f 2a 20 69 6e 74 20 2a  CAN 20  /* int *
15700 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
15710 5f 43 4f 4e 46 49 47 5f 53 51 4c 4c 4f 47 20 20  _CONFIG_SQLLOG  
15720 20 20 20 20 20 32 31 20 20 2f 2a 20 78 53 71 6c       21  /* xSql
15730 6c 6f 67 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  log, void* */.#d
15740 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15750 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20 20 20  FIG_MMAP_SIZE   
15760 20 32 32 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   22  /* sqlite3_
15770 69 6e 74 36 34 2c 20 73 71 6c 69 74 65 33 5f 69  int64, sqlite3_i
15780 6e 74 36 34 20 2a 2f 0a 23 64 65 66 69 6e 65 20  nt64 */.#define 
15790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49  SQLITE_CONFIG_WI
157a0 4e 33 32 5f 48 45 41 50 53 49 5a 45 20 20 20 20  N32_HEAPSIZE    
157b0 20 20 32 33 20 20 2f 2a 20 69 6e 74 20 6e 42 79    23  /* int nBy
157c0 74 65 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  te */../*.** CAP
157d0 49 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20  I3REF: Database 
157e0 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f 6e 66 69  Connection Confi
157f0 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
15800 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
15810 73 74 61 6e 74 73 20 61 72 65 20 74 68 65 20 61  stants are the a
15820 76 61 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72  vailable integer
15830 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15840 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63  ptions that.** c
15850 61 6e 20 62 65 20 70 61 73 73 65 64 20 61 73 20  an be passed as 
15860 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
15870 65 6e 74 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ent to the [sqli
15880 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
15890 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
158a0 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
158b0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
158c0 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
158d0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
158e0 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
158f0 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
15900 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
15910 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
15920 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
15930 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
15940 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
15950 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  om [sqlite3_db_c
15960 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
15970 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
15980 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
15990 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62  ^The [sqlite3_db
159a0 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
159b0 66 61 63 65 20 77 69 6c 6c 20 72 65 74 75 72 6e  face will return
159c0 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b   a.** non-zero [
159d0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
159e0 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 20 6f 72   discontinued or
159f0 20 75 6e 73 75 70 70 6f 72 74 65 64 20 63 6f 6e   unsupported con
15a00 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
15a10 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b 65 64 2e  n.** is invoked.
15a20 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c  .**.** <dl>.** <
15a30 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  dt>SQLITE_DBCONF
15a40 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
15a50 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
15a60 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 68 72  option takes thr
15a70 65 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72  ee additional ar
15a80 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65 74  guments that det
15a90 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a 2a 20 5b  ermine the .** [
15aa0 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79  lookaside memory
15ab0 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63 6f 6e 66   allocator] conf
15ac0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 74 68  iguration for th
15ad0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
15ae0 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e 54 68 65  ection]..** ^The
15af0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15b00 28 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d  (the third param
15b10 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
15b20 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 73  _db_config()] is
15b30 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 74 6f   a.** pointer to
15b40 20 61 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72   a memory buffer
15b50 20 74 6f 20 75 73 65 20 66 6f 72 20 6c 6f 6f 6b   to use for look
15b60 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  aside memory..**
15b70 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
15b80 6d 65 6e 74 20 61 66 74 65 72 20 74 68 65 20 53  ment after the S
15b90 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c  QLITE_DBCONFIG_L
15ba0 4f 4f 4b 41 53 49 44 45 20 76 65 72 62 0a 2a 2a  OOKASIDE verb.**
15bb0 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20 69 6e 20   may be NULL in 
15bc0 77 68 69 63 68 20 63 61 73 65 20 53 51 4c 69 74  which case SQLit
15bd0 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61 74 65 20  e will allocate 
15be0 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73 69 64 65  the.** lookaside
15bf0 20 62 75 66 66 65 72 20 69 74 73 65 6c 66 20 75   buffer itself u
15c00 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 61  sing [sqlite3_ma
15c10 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65 20 73 65  lloc()]. ^The se
15c20 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73  cond argument is
15c30 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20 6f 66 20   the.** size of 
15c40 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64 65 20 62  each lookaside b
15c50 75 66 66 65 72 20 73 6c 6f 74 2e 20 20 5e 54 68  uffer slot.  ^Th
15c60 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
15c70 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
15c80 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20 54 68 65  f.** slots.  The
15c90 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
15ca0 66 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  fer in the first
15cb0 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20 62   argument must b
15cc0 65 20 67 72 65 61 74 65 72 20 74 68 61 6e 0a 2a  e greater than.*
15cd0 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 74 68  * or equal to th
15ce0 65 20 70 72 6f 64 75 63 74 20 6f 66 20 74 68 65  e product of the
15cf0 20 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 69 72   second and thir
15d00 64 20 61 72 67 75 6d 65 6e 74 73 2e 20 20 54 68  d arguments.  Th
15d10 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d 75 73 74  e buffer.** must
15d20 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61   be aligned to a
15d30 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72  n 8-byte boundar
15d40 79 2e 20 20 5e 49 66 20 74 68 65 20 73 65 63 6f  y.  ^If the seco
15d50 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
15d60 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  * SQLITE_DBCONFI
15d70 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69 73 20 6e  G_LOOKASIDE is n
15d80 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  ot a multiple of
15d90 20 38 2c 20 69 74 20 69 73 20 69 6e 74 65 72 6e   8, it is intern
15da0 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64 65 64 20  ally.** rounded 
15db0 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e 65 78 74  down to the next
15dc0 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74 69 70 6c   smaller multipl
15dd0 65 20 6f 66 20 38 2e 20 20 5e 28 54 68 65 20 6c  e of 8.  ^(The l
15de0 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 0a  ookaside memory.
15df0 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
15e00 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
15e10 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61 6e 20 6f  connection can o
15e20 6e 6c 79 20 62 65 20 63 68 61 6e 67 65 64 20 77  nly be changed w
15e30 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63 6f 6e 6e  hen that.** conn
15e40 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74 20 63 75  ection is not cu
15e50 72 72 65 6e 74 6c 79 20 75 73 69 6e 67 20 6c 6f  rrently using lo
15e60 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2c 20  okaside memory, 
15e70 6f 72 20 69 6e 20 6f 74 68 65 72 20 77 6f 72 64  or in other word
15e80 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65 20 22 63  s.** when the "c
15e90 75 72 72 65 6e 74 20 76 61 6c 75 65 22 20 72 65  urrent value" re
15ea0 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71  turned by.** [sq
15eb0 6c 69 74 65 33 5f 64 62 5f 73 74 61 74 75 73 5d  lite3_db_status]
15ec0 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  (D,[SQLITE_CONFI
15ed0 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c 2e 2e 2e  G_LOOKASIDE],...
15ee0 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a 20 41 6e  ) is zero..** An
15ef0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 63 68 61  y attempt to cha
15f00 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64  nge the lookasid
15f10 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66 69 67 75  e memory configu
15f20 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c 6f 6f 6b  ration when look
15f30 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20  aside.** memory 
15f40 69 73 20 69 6e 20 75 73 65 20 6c 65 61 76 65 73  is in use leaves
15f50 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61 74 69   the configurati
15f60 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20 61 6e 64  on unchanged and
15f70 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20 5b 53 51   returns .** [SQ
15f80 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e 3c 2f 64  LITE_BUSY].)^</d
15f90 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
15fa0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41  ITE_DBCONFIG_ENA
15fb0 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e 0a 2a 2a  BLE_FKEY</dt>.**
15fc0 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
15fd0 6f 6e 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e  on is used to en
15fe0 61 62 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20  able or disable 
15ff0 74 68 65 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20  the enforcement 
16000 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b  of.** [foreign k
16010 65 79 20 63 6f 6e 73 74 72 61 69 6e 74 73 5d 2e  ey constraints].
16020 20 20 54 68 65 72 65 20 73 68 6f 75 6c 64 20 62    There should b
16030 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e 61 6c  e two additional
16040 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54   arguments..** T
16050 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
16060 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20  t is an integer 
16070 77 68 69 63 68 20 69 73 20 30 20 74 6f 20 64 69  which is 0 to di
16080 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65  sable FK enforce
16090 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69 74 69 76  ment,.** positiv
160a0 65 20 74 6f 20 65 6e 61 62 6c 65 20 46 4b 20 65  e to enable FK e
160b0 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72 20 6e 65  nforcement or ne
160c0 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
160d0 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 0a 2a  FK enforcement.*
160e0 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20 20 54 68  * unchanged.  Th
160f0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
16100 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  er is a pointer 
16110 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 69 6e  to an integer in
16120 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73 20 77  to which.** is w
16130 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20 74 6f  ritten 0 or 1 to
16140 20 69 6e 64 69 63 61 74 65 20 77 68 65 74 68 65   indicate whethe
16150 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74  r FK enforcement
16160 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e 0a 2a 2a   is off or on.**
16170 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20   following this 
16180 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e  call.  The secon
16190 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  d parameter may 
161a0 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  be a NULL pointe
161b0 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63  r, in.** which c
161c0 61 73 65 20 74 68 65 20 46 4b 20 65 6e 66 6f 72  ase the FK enfor
161d0 63 65 6d 65 6e 74 20 73 65 74 74 69 6e 67 20 69  cement setting i
161e0 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
161f0 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
16200 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43 4f   <dt>SQLITE_DBCO
16210 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47  NFIG_ENABLE_TRIG
16220 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  GER</dt>.** <dd>
16230 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16240 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16250 6f 72 20 64 69 73 61 62 6c 65 20 5b 43 52 45 41  or disable [CREA
16260 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69  TE TRIGGER | tri
16270 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68 65 72 65  ggers]..** There
16280 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
16290 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
162a0 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
162b0 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
162c0 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
162d0 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 74  s 0 to disable t
162e0 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70 6f 73 69  riggers,.** posi
162f0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 74  tive to enable t
16300 72 69 67 67 65 72 73 20 6f 72 20 6e 65 67 61 74  riggers or negat
16310 69 76 65 20 74 6f 20 6c 65 61 76 65 20 74 68 65  ive to leave the
16320 20 73 65 74 74 69 6e 67 20 75 6e 63 68 61 6e 67   setting unchang
16330 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e  ed..** The secon
16340 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
16350 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
16360 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
16370 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
16380 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
16390 74 65 20 77 68 65 74 68 65 72 20 74 72 69 67 67  te whether trigg
163a0 65 72 73 20 61 72 65 20 64 69 73 61 62 6c 65 64  ers are disabled
163b0 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a 2a 20 66   or enabled.** f
163c0 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73 20 63 61  ollowing this ca
163d0 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ll.  The second 
163e0 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62 65  parameter may be
163f0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
16400 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20 63 61 73   in.** which cas
16410 65 20 74 68 65 20 74 72 69 67 67 65 72 20 73 65  e the trigger se
16420 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72 65 70  tting is not rep
16430 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f 64 64  orted back. </dd
16440 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  >.**.** </dl>.*/
16450 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
16460 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
16470 44 45 20 20 20 20 20 20 20 31 30 30 31 20 20 2f  DE       1001  /
16480 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69 6e 74 20  * void* int int 
16490 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
164a0 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
164b0 45 5f 46 4b 45 59 20 20 20 20 20 31 30 30 32 20  E_FKEY     1002 
164c0 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
164d0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
164e0 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
164f0 52 49 47 47 45 52 20 20 31 30 30 33 20 20 2f 2a  RIGGER  1003  /*
16500 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f   int int* */.../
16510 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45  *.** CAPI3REF: E
16520 6e 61 62 6c 65 20 4f 72 20 44 69 73 61 62 6c 65  nable Or Disable
16530 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
16540 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68   Codes.**.** ^Th
16550 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
16560 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28  ed_result_codes(
16570 29 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  ) routine enable
16580 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
16590 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72  e.** [extended r
165a0 65 73 75 6c 74 20 63 6f 64 65 73 5d 20 66 65 61  esult codes] fea
165b0 74 75 72 65 20 6f 66 20 53 51 4c 69 74 65 2e 20  ture of SQLite. 
165c0 5e 54 68 65 20 65 78 74 65 6e 64 65 64 20 72 65  ^The extended re
165d0 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73 20 61 72  sult.** codes ar
165e0 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64 65  e disabled by de
165f0 66 61 75 6c 74 20 66 6f 72 20 68 69 73 74 6f 72  fault for histor
16600 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
16610 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ty..*/.int sqlit
16620 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
16630 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69 74 65 33  lt_codes(sqlite3
16640 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a  *, int onoff);..
16650 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16660 4c 61 73 74 20 49 6e 73 65 72 74 20 52 6f 77 69  Last Insert Rowi
16670 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68 20 65 6e  d.**.** ^Each en
16680 74 72 79 20 69 6e 20 6d 6f 73 74 20 53 51 4c 69  try in most SQLi
16690 74 65 20 74 61 62 6c 65 73 20 28 65 78 63 65 70  te tables (excep
166a0 74 20 66 6f 72 20 5b 57 49 54 48 4f 55 54 20 52  t for [WITHOUT R
166b0 4f 57 49 44 5d 20 74 61 62 6c 65 73 29 0a 2a 2a  OWID] tables).**
166c0 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34   has a unique 64
166d0 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69  -bit signed.** i
166e0 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65  nteger key calle
166f0 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22  d the [ROWID | "
16700 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f  rowid"]. ^The ro
16710 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76  wid is always av
16720 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e  ailable.** as an
16730 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75   undeclared colu
16740 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20  mn named ROWID, 
16750 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20  OID, or _ROWID_ 
16760 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65  as long as those
16770 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f  .** names are no
16780 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65  t also used by e
16790 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
167a0 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a  ed columns. ^If.
167b0 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73  ** the table has
167c0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70   a column of typ
167d0 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41  e [INTEGER PRIMA
167e0 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61  RY KEY] then tha
167f0 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61  t column.** is a
16800 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72  nother alias for
16810 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a   the rowid..**.*
16820 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6c  * ^The sqlite3_l
16830 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
16840 28 44 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (D) interface re
16850 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69 64  turns the [rowid
16860 5d 20 6f 66 20 74 68 65 20 0a 2a 2a 20 6d 6f 73  ] of the .** mos
16870 74 20 72 65 63 65 6e 74 20 73 75 63 63 65 73 73  t recent success
16880 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
16890 6f 20 61 20 72 6f 77 69 64 20 74 61 62 6c 65 20  o a rowid table 
168a0 6f 72 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  or [virtual tabl
168b0 65 5d 0a 2a 2a 20 6f 6e 20 64 61 74 61 62 61 73  e].** on databas
168c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 0a  e connection D..
168d0 2a 2a 20 5e 49 6e 73 65 72 74 73 20 69 6e 74 6f  ** ^Inserts into
168e0 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
168f0 20 74 61 62 6c 65 73 20 61 72 65 20 6e 6f 74 20   tables are not 
16900 72 65 63 6f 72 64 65 64 2e 0a 2a 2a 20 5e 49 66  recorded..** ^If
16910 20 6e 6f 20 73 75 63 63 65 73 73 66 75 6c 20 5b   no successful [
16920 49 4e 53 45 52 54 5d 73 20 69 6e 74 6f 20 72 6f  INSERT]s into ro
16930 77 69 64 20 74 61 62 6c 65 73 0a 2a 2a 20 68 61  wid tables.** ha
16940 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65 64  ve ever occurred
16950 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73 65   on the database
16960 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2c 20 0a   connection D, .
16970 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f  ** then sqlite3_
16980 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
16990 64 28 44 29 20 72 65 74 75 72 6e 73 20 7a 65 72  d(D) returns zer
169a0 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e  o..**.** ^(If an
169b0 20 5b 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73   [INSERT] occurs
169c0 20 77 69 74 68 69 6e 20 61 20 74 72 69 67 67 65   within a trigge
169d0 72 20 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76  r or within a [v
169e0 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
169f0 20 6d 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68   method, then th
16a00 69 73 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20  is routine will 
16a10 72 65 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69  return the [rowi
16a20 64 5d 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74  d] of the insert
16a30 65 64 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e  ed.** row as lon
16a40 67 20 61 73 20 74 68 65 20 74 72 69 67 67 65 72  g as the trigger
16a50 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c   or virtual tabl
16a60 65 20 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e  e method is runn
16a70 69 6e 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65  ing..** But once
16a80 20 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20   the trigger or 
16a90 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65  virtual table me
16aa0 74 68 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76  thod ends, the v
16ab0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a  alue returned .*
16ac0 2a 20 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e  * by this routin
16ad0 65 20 72 65 76 65 72 74 73 20 74 6f 20 77 68 61  e reverts to wha
16ae0 74 20 69 74 20 77 61 73 20 62 65 66 6f 72 65 20  t it was before 
16af0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
16b00 69 72 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20  irtual.** table 
16b10 6d 65 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a  method began.)^.
16b20 2a 2a 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52  **.** ^An [INSER
16b30 54 5d 20 74 68 61 74 20 66 61 69 6c 73 20 64 75  T] that fails du
16b40 65 20 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e  e to a constrain
16b50 74 20 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e  t violation is n
16b60 6f 74 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66  ot a.** successf
16b70 75 6c 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20  ul [INSERT] and 
16b80 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
16b90 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
16ba0 65 64 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f  ed by this.** ro
16bb0 75 74 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e  utine.  ^Thus IN
16bc0 53 45 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e  SERT OR FAIL, IN
16bd0 53 45 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20  SERT OR IGNORE, 
16be0 49 4e 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41  INSERT OR ROLLBA
16bf0 43 4b 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52  CK,.** and INSER
16c00 54 20 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20  T OR ABORT make 
16c10 6e 6f 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68  no changes to th
16c20 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
16c30 66 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e  f this.** routin
16c40 65 20 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73  e when their ins
16c50 65 72 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e  ertion fails.  ^
16c60 28 57 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20  (When INSERT OR 
16c70 52 45 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75  REPLACE.** encou
16c80 6e 74 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69  nters a constrai
16c90 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74  nt violation, it
16ca0 20 64 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20   does not fail. 
16cb0 20 54 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63   The.** INSERT c
16cc0 6f 6e 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70  ontinues to comp
16cd0 6c 65 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c  letion after del
16ce0 65 74 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20  eting rows that 
16cf0 63 61 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f  caused.** the co
16d00 6e 73 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d  nstraint problem
16d10 20 73 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45   so INSERT OR RE
16d20 50 4c 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79  PLACE will alway
16d30 73 20 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20  s change.** the 
16d40 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
16d50 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29  this interface.)
16d60 5e 0a 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65  ^.**.** ^For the
16d70 20 70 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69   purposes of thi
16d80 73 20 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49  s routine, an [I
16d90 4e 53 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64  NSERT] is consid
16da0 65 72 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75  ered to.** be su
16db0 63 63 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66  ccessful even if
16dc0 20 69 74 20 69 73 20 73 75 62 73 65 71 75 65 6e   it is subsequen
16dd0 74 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e  tly rolled back.
16de0 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63  .**.** This func
16df0 74 69 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62  tion is accessib
16e00 6c 65 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d  le to SQL statem
16e10 65 6e 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20  ents via the.** 
16e20 5b 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77  [last_insert_row
16e30 69 64 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  id() SQL functio
16e40 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
16e50 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 70  eparate thread p
16e60 65 72 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49  erforms a new [I
16e70 4e 53 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61  NSERT] on the sa
16e80 6d 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  me.** database c
16e90 6f 6e 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20  onnection while 
16ea0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73  the [sqlite3_las
16eb0 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29  t_insert_rowid()
16ec0 5d 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73  ].** function is
16ed0 20 72 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75   running and thu
16ee0 73 20 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61  s changes the la
16ef0 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
16f00 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76  ],.** then the v
16f10 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
16f20 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69   [sqlite3_last_i
16f30 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69  nsert_rowid()] i
16f40 73 0a 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62  s.** unpredictab
16f50 6c 65 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74  le and might not
16f60 20 65 71 75 61 6c 20 65 69 74 68 65 72 20 74 68   equal either th
16f70 65 20 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77  e old or the new
16f80 0a 2a 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20  .** last insert 
16f90 5b 72 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69  [rowid]..*/.sqli
16fa0 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
16fb0 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f  3_last_insert_ro
16fc0 77 69 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a  wid(sqlite3*);..
16fd0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
16fe0 43 6f 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72  Count The Number
16ff0 20 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65   Of Rows Modifie
17000 64 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75  d.**.** ^This fu
17010 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74  nction returns t
17020 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74  he number of dat
17030 61 62 61 73 65 20 72 6f 77 73 20 74 68 61 74 20  abase rows that 
17040 77 65 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20  were changed.** 
17050 6f 72 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64  or inserted or d
17060 65 6c 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f  eleted by the mo
17070 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70  st recently comp
17080 6c 65 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  leted SQL statem
17090 65 6e 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64  ent.** on the [d
170a0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
170b0 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 62 79  on] specified by
170c0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
170d0 65 74 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  eter..** ^(Only 
170e0 63 68 61 6e 67 65 73 20 74 68 61 74 20 61 72 65  changes that are
170f0 20 64 69 72 65 63 74 6c 79 20 73 70 65 63 69 66   directly specif
17100 69 65 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45  ied by the [INSE
17110 52 54 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a  RT], [UPDATE],.*
17120 2a 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  * or [DELETE] st
17130 61 74 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e  atement are coun
17140 74 65 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20  ted.  Auxiliary 
17150 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
17160 79 0a 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72  y.** triggers or
17170 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63   [foreign key ac
17180 74 69 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63  tions] are not c
17190 6f 75 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68  ounted.)^ Use th
171a0 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f  e.** [sqlite3_to
171b0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66  tal_changes()] f
171c0 75 6e 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20  unction to find 
171d0 74 68 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72  the total number
171e0 20 6f 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69   of changes.** i
171f0 6e 63 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73  ncluding changes
17200 20 63 61 75 73 65 64 20 62 79 20 74 72 69 67 67   caused by trigg
17210 65 72 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20  ers and foreign 
17220 6b 65 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a  key actions..**.
17230 2a 2a 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61  ** ^Changes to a
17240 20 76 69 65 77 20 74 68 61 74 20 61 72 65 20 73   view that are s
17250 69 6d 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b  imulated by an [
17260 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17270 65 72 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63  er].** are not c
17280 6f 75 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65  ounted.  Only re
17290 61 6c 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73  al table changes
172a0 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a   are counted..**
172b0 0a 2a 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61  .** ^(A "row cha
172c0 6e 67 65 22 20 69 73 20 61 20 63 68 61 6e 67 65  nge" is a change
172d0 20 74 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77   to a single row
172e0 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62   of a single tab
172f0 6c 65 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20  le.** caused by 
17300 61 6e 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54  an INSERT, DELET
17310 45 2c 20 6f 72 20 55 50 44 41 54 45 20 73 74 61  E, or UPDATE sta
17320 74 65 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68  tement.  Rows th
17330 61 74 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65  at.** are change
17340 64 20 61 73 20 73 69 64 65 20 65 66 66 65 63 74  d as side effect
17350 73 20 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63  s of [REPLACE] c
17360 6f 6e 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75  onstraint resolu
17370 74 69 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63  tion,.** rollbac
17380 6b 2c 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73  k, ABORT process
17390 69 6e 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45  ing, [DROP TABLE
173a0 5d 2c 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68  ], or by any oth
173b0 65 72 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73  er.** mechanisms
173c0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
173d0 20 64 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e   direct row chan
173e0 67 65 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22  ges.)^.**.** A "
173f0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22  trigger context"
17400 20 69 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65   is a scope of e
17410 78 65 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65  xecution that be
17420 67 69 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73  gins and.** ends
17430 20 77 69 74 68 20 74 68 65 20 73 63 72 69 70 74   with the script
17440 20 6f 66 20 61 20 5b 43 52 45 41 54 45 20 54 52   of a [CREATE TR
17450 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d  IGGER | trigger]
17460 2e 20 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73  . .** Most SQL s
17470 74 61 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a  tatements are.**
17480 20 65 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69   evaluated outsi
17490 64 65 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65  de of any trigge
174a0 72 2e 20 20 54 68 69 73 20 69 73 20 74 68 65 20  r.  This is the 
174b0 22 74 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74  "top level".** t
174c0 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20  rigger context. 
174d0 20 49 66 20 61 20 74 72 69 67 67 65 72 20 66 69   If a trigger fi
174e0 72 65 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70  res from the top
174f0 20 6c 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77   level, a.** new
17500 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74   trigger context
17510 20 69 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20   is entered for 
17520 74 68 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20  the duration of 
17530 74 68 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67  that one.** trig
17540 67 65 72 2e 20 20 53 75 62 74 72 69 67 67 65 72  ger.  Subtrigger
17550 73 20 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74  s create subcont
17560 65 78 74 73 20 66 6f 72 20 74 68 65 69 72 20 64  exts for their d
17570 75 72 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  uration..**.** ^
17580 43 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  Calling [sqlite3
17590 5f 65 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c  _exec()] or [sql
175a0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63  ite3_step()] rec
175b0 75 72 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a  ursively does.**
175c0 20 6e 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65   not create a ne
175d0 77 20 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78  w trigger contex
175e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  t..**.** ^This f
175f0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
17600 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69  the number of di
17610 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73  rect row changes
17620 20 69 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20   in the.** most 
17630 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55  recent INSERT, U
17640 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45  PDATE, or DELETE
17650 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
17660 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72  n the same.** tr
17670 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a  igger context..*
17680 2a 0a 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e  *.** ^Thus, when
17690 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
176a0 20 74 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73   top level, this
176b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e   function return
176c0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
176d0 6f 66 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  of changes in th
176e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e  e most recent IN
176f0 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
17700 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
17710 61 6c 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74  also occurred at
17720 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20   the top level. 
17730 20 5e 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f   ^(Within the bo
17740 64 79 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c  dy of a trigger,
17750 0a 2a 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f  .** the sqlite3_
17760 63 68 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66  changes() interf
17770 61 63 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65  ace can be calle
17780 64 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75  d to find the nu
17790 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67  mber of.** chang
177a0 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72  es in the most r
177b0 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65  ecently complete
177c0 64 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  d INSERT, UPDATE
177d0 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73  , or DELETE.** s
177e0 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
177f0 74 68 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20  the body of the 
17800 73 61 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a  same trigger..**
17810 20 48 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75   However, the nu
17820 6d 62 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f  mber returned do
17830 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63  es not include c
17840 68 61 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64  hanges.** caused
17850 20 62 79 20 73 75 62 74 72 69 67 67 65 72 73 20   by subtriggers 
17860 73 69 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65  since those have
17870 20 74 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65   their own conte
17880 78 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  xt.)^.**.** See 
17890 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
178a0 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
178b0 29 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68  )] interface, th
178c0 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e  e.** [count_chan
178d0 67 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64  ges pragma], and
178e0 20 74 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20   the [changes() 
178f0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
17900 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
17910 74 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20  te thread makes 
17920 63 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73  changes on the s
17930 61 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ame database con
17940 6e 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65  nection.** while
17950 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65   [sqlite3_change
17960 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
17970 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
17980 65 74 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e  eturned.** is un
17990 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
179a0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
179b0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
179c0 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29  hanges(sqlite3*)
179d0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
179e0 46 3a 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20  F: Total Number 
179f0 4f 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64  Of Rows Modified
17a00 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
17a10 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
17a20 65 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20  e number of row 
17a30 63 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62  changes caused b
17a40 79 20 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b  y [INSERT],.** [
17a50 55 50 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45  UPDATE] or [DELE
17a60 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73  TE] statements s
17a70 69 6e 63 65 20 74 68 65 20 5b 64 61 74 61 62 61  ince the [databa
17a80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
17a90 61 73 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28  as opened..** ^(
17aa0 54 68 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e  The count return
17ab0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f  ed by sqlite3_to
17ac0 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e  tal_changes() in
17ad0 63 6c 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67  cludes all chang
17ae0 65 73 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b  es.** from all [
17af0 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c  CREATE TRIGGER |
17b00 20 74 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78   trigger] contex
17b10 74 73 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d  ts and changes m
17b20 61 64 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69  ade by.** [forei
17b30 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e  gn key actions].
17b40 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65   However,.** the
17b50 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20   count does not 
17b60 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20  include changes 
17b70 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e  used to implemen
17b80 74 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73  t [REPLACE] cons
17b90 74 72 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72  traints,.** do r
17ba0 6f 6c 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52  ollbacks or ABOR
17bb0 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72  T processing, or
17bc0 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72   [DROP TABLE] pr
17bd0 6f 63 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a  ocessing.  The.*
17be0 2a 20 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74  * count does not
17bf0 20 69 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66   include rows of
17c00 20 76 69 65 77 73 20 74 68 61 74 20 66 69 72 65   views that fire
17c10 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20   an [INSTEAD OF 
17c20 74 72 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f  trigger],.** tho
17c30 75 67 68 20 69 66 20 74 68 65 20 49 4e 53 54 45  ugh if the INSTE
17c40 41 44 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61  AD OF trigger ma
17c50 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69  kes changes of i
17c60 74 73 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68  ts own, those ch
17c70 61 6e 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f  anges .** are co
17c80 75 6e 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65  unted.)^.** ^The
17c90 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17ca0 68 61 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f  hanges() functio
17cb0 6e 20 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61  n counts the cha
17cc0 6e 67 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a  nges as soon as.
17cd0 2a 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  ** the statement
17ce0 20 74 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d   that makes them
17cf0 20 69 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77   is completed (w
17d00 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
17d10 74 20 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70  t handle.** is p
17d20 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
17d30 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
17d40 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
17d50 29 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  )])..**.** See a
17d60 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
17d70 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65  _changes()] inte
17d80 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63  rface, the.** [c
17d90 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61  ount_changes pra
17da0 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74  gma], and the [t
17db0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53  otal_changes() S
17dc0 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
17dd0 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
17de0 65 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63  e thread makes c
17df0 68 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61  hanges on the sa
17e00 6d 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  me database conn
17e10 65 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20  ection.** while 
17e20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
17e30 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e  hanges()] is run
17e40 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61  ning then the va
17e50 6c 75 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20  lue.** returned 
17e60 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  is unpredictable
17e70 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67   and not meaning
17e80 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
17e90 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17ea0 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17eb0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e  .** CAPI3REF: In
17ec0 74 65 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52  terrupt A Long-R
17ed0 75 6e 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a  unning Query.**.
17ee0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17ef0 6e 20 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e  n causes any pen
17f00 64 69 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70  ding database op
17f10 65 72 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74  eration to abort
17f20 20 61 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61   and.** return a
17f30 74 20 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f  t its earliest o
17f40 70 70 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73  pportunity. This
17f50 20 72 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69   routine is typi
17f60 63 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  cally.** called 
17f70 69 6e 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61  in response to a
17f80 20 75 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63   user action suc
17f90 68 20 61 73 20 70 72 65 73 73 69 6e 67 20 22 43  h as pressing "C
17fa0 61 6e 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72  ancel".** or Ctr
17fb0 6c 2d 43 20 77 68 65 72 65 20 74 68 65 20 75 73  l-C where the us
17fc0 65 72 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20  er wants a long 
17fd0 71 75 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20  query operation 
17fe0 74 6f 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64  to halt.** immed
17ff0 69 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49  iately..**.** ^I
18000 74 20 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c  t is safe to cal
18010 6c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66  l this routine f
18020 72 6f 6d 20 61 20 74 68 72 65 61 64 20 64 69 66  rom a thread dif
18030 66 65 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a  ferent from the.
18040 2a 2a 20 74 68 72 65 61 64 20 74 68 61 74 20 69  ** thread that i
18050 73 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  s currently runn
18060 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
18070 20 6f 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74   operation.  But
18080 20 69 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61   it.** is not sa
18090 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20  fe to call this 
180a0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b  routine with a [
180b0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
180c0 69 6f 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20  ion] that.** is 
180d0 63 6c 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20  closed or might 
180e0 63 6c 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c  close before sql
180f0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
18100 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20   returns..**.** 
18110 5e 49 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61  ^If an SQL opera
18120 74 69 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61  tion is very nea
18130 72 6c 79 20 66 69 6e 69 73 68 65 64 20 61 74 20  rly finished at 
18140 74 68 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a  the time when.**
18150 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18160 70 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20  pt() is called, 
18170 74 68 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f  then it might no
18180 74 20 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74  t have an opport
18190 75 6e 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69  unity.** to be i
181a0 6e 74 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d  nterrupted and m
181b0 69 67 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f  ight continue to
181c0 20 63 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a   completion..**.
181d0 2a 2a 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61  ** ^An SQL opera
181e0 74 69 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74  tion that is int
181f0 65 72 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65  errupted will re
18200 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54  turn [SQLITE_INT
18210 45 52 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20  ERRUPT]..** ^If 
18220 74 68 65 20 69 6e 74 65 72 72 75 70 74 65 64 20  the interrupted 
18230 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73  SQL operation is
18240 20 61 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41   an INSERT, UPDA
18250 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
18260 20 74 68 61 74 20 69 73 20 69 6e 73 69 64 65 20   that is inside 
18270 61 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e  an explicit tran
18280 73 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  saction, then th
18290 65 20 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63  e entire transac
182a0 74 69 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20  tion.** will be 
182b0 72 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f  rolled back auto
182c0 6d 61 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a  matically..**.**
182d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
182e0 74 65 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20  terrupt(D) call 
182f0 69 73 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74  is in effect unt
18300 69 6c 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79  il all currently
18310 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20   running.** SQL 
18320 73 74 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64  statements on [d
18330 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
18340 6f 6e 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20  on] D complete. 
18350 20 5e 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74   ^Any new SQL st
18360 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
18370 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
18380 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
18390 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
183a0 61 6e 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a  and before the .
183b0 2a 2a 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65  ** running state
183c0 6d 65 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65  ments reaches ze
183d0 72 6f 20 61 72 65 20 69 6e 74 65 72 72 75 70 74  ro are interrupt
183e0 65 64 20 61 73 20 69 66 20 74 68 65 79 20 68 61  ed as if they ha
183f0 64 20 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e  d been.** runnin
18400 67 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73  g prior to the s
18410 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
18420 28 29 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53  () call.  ^New S
18430 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
18440 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74 65   that are starte
18450 64 20 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e  d after the runn
18460 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f  ing statement co
18470 75 6e 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f  unt reaches zero
18480 20 61 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65   are.** not effe
18490 63 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69  cted by the sqli
184a0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e  te3_interrupt().
184b0 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73  .** ^A call to s
184c0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
184d0 28 44 29 20 74 68 61 74 20 6f 63 63 75 72 73 20  (D) that occurs 
184e0 77 68 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e  when there are n
184f0 6f 20 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c  o running.** SQL
18500 20 73 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61   statements is a
18510 20 6e 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e   no-op and has n
18520 6f 20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20  o effect on SQL 
18530 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68  statements.** th
18540 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20 61  at are started a
18550 66 74 65 72 20 74 68 65 20 73 71 6c 69 74 65 33  fter the sqlite3
18560 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
18570 6c 20 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a  l returns..**.**
18580 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
18590 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73   connection clos
185a0 65 73 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65  es while [sqlite
185b0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a  3_interrupt()].*
185c0 2a 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65  * is running the
185d0 6e 20 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c  n bad things wil
185e0 6c 20 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e  l likely happen.
185f0 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
18600 5f 69 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74  _interrupt(sqlit
18610 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
18620 49 33 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65  I3REF: Determine
18630 20 49 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65   If An SQL State
18640 6d 65 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65  ment Is Complete
18650 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
18660 74 69 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c  tines are useful
18670 20 64 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d   during command-
18680 6c 69 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65  line input to de
18690 74 65 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a  termine if the.*
186a0 2a 20 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65  * currently ente
186b0 72 65 64 20 74 65 78 74 20 73 65 65 6d 73 20 74  red text seems t
186c0 6f 20 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74  o form a complet
186d0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
186e0 6f 72 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f  or.** if additio
186f0 6e 61 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65  nal input is nee
18700 64 65 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69  ded before sendi
18710 6e 67 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f  ng the text into
18720 0a 2a 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70  .** SQLite for p
18730 61 72 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20  arsing.  ^These 
18740 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18750 31 20 69 66 20 74 68 65 20 69 6e 70 75 74 20 73  1 if the input s
18760 74 72 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73  tring.** appears
18770 20 74 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74   to be a complet
18780 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  e SQL statement.
18790 20 20 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69    ^A statement i
187a0 73 20 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a  s judged to be.*
187b0 2a 20 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74  * complete if it
187c0 20 65 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d   ends with a sem
187d0 69 63 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64  icolon token and
187e0 20 69 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78   is not a prefix
187f0 20 6f 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f   of a.** well-fo
18800 72 6d 65 64 20 43 52 45 41 54 45 20 54 52 49 47  rmed CREATE TRIG
18810 47 45 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  GER statement.  
18820 5e 53 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74  ^Semicolons that
18830 20 61 72 65 20 65 6d 62 65 64 64 65 64 20 77 69   are embedded wi
18840 74 68 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c  thin.** string l
18850 69 74 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65  iterals or quote
18860 64 20 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d  d identifier nam
18870 65 73 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61  es or comments a
18880 72 65 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65  re not.** indepe
18890 6e 64 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68  ndent tokens (th
188a0 65 79 20 61 72 65 20 70 61 72 74 20 6f 66 20 74  ey are part of t
188b0 68 65 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63  he token in whic
188c0 68 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d  h they are.** em
188d0 62 65 64 64 65 64 29 20 61 6e 64 20 74 68 75 73  bedded) and thus
188e0 20 64 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73   do not count as
188f0 20 61 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72   a statement ter
18900 6d 69 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65  minator.  ^White
18910 73 70 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d  space.** and com
18920 6d 65 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f  ments that follo
18930 77 20 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69  w the final semi
18940 63 6f 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65  colon are ignore
18950 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  d..**.** ^These 
18960 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
18970 30 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  0 if the stateme
18980 6e 74 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65  nt is incomplete
18990 2e 20 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f  .  ^If a.** memo
189a0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61  ry allocation fa
189b0 69 6c 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45  ils, then SQLITE
189c0 5f 4e 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e  _NOMEM is return
189d0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ed..**.** ^These
189e0 20 72 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74   routines do not
189f0 20 70 61 72 73 65 20 74 68 65 20 53 51 4c 20 73   parse the SQL s
18a00 74 61 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a  tatements thus.*
18a10 2a 20 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63  * will not detec
18a20 74 20 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20  t syntactically 
18a30 69 6e 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a  incorrect SQL..*
18a40 2a 0a 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65  *.** ^(If SQLite
18a50 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e   has not been in
18a60 69 74 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20  itialized using 
18a70 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c  [sqlite3_initial
18a80 69 7a 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a  ize()] prior .**
18a90 20 74 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c   to invoking sql
18aa0 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18ab0 29 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69  ) then sqlite3_i
18ac0 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69  nitialize() is i
18ad0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61  nvoked.** automa
18ae0 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74  tically by sqlit
18af0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e  e3_complete16().
18b00 20 20 49 66 20 74 68 61 74 20 69 6e 69 74 69 61    If that initia
18b10 6c 69 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a  lization fails,.
18b20 2a 2a 20 74 68 65 6e 20 74 68 65 20 72 65 74 75  ** then the retu
18b30 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  rn value from sq
18b40 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
18b50 28 29 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a  () will be non-z
18b60 65 72 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73  ero.** regardles
18b70 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
18b80 6e 6f 74 20 74 68 65 20 69 6e 70 75 74 20 53 51  not the input SQ
18b90 4c 20 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e  L is complete.)^
18ba0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74  .**.** The input
18bb0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d   to [sqlite3_com
18bc0 70 6c 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65  plete()] must be
18bd0 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
18be0 65 64 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69  ed.** UTF-8 stri
18bf0 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e  ng..**.** The in
18c00 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
18c10 63 6f 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75  complete16()] mu
18c20 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72  st be a zero-ter
18c30 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31  minated.** UTF-1
18c40 36 20 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69  6 string in nati
18c50 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a  ve byte order..*
18c60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
18c70 6d 70 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61  mplete(const cha
18c80 72 20 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c  r *sql);.int sql
18c90 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28  ite3_complete16(
18ca0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29  const void *sql)
18cb0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
18cc0 46 3a 20 52 65 67 69 73 74 65 72 20 41 20 43 61  F: Register A Ca
18cd0 6c 6c 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65  llback To Handle
18ce0 20 53 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72   SQLITE_BUSY Err
18cf0 6f 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ors.**.** ^The s
18d00 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
18d10 6c 65 72 28 44 2c 58 2c 50 29 20 72 6f 75 74 69  ler(D,X,P) routi
18d20 6e 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61  ne sets a callba
18d30 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 0a 2a 2a  ck function X.**
18d40 20 74 68 61 74 20 6d 69 67 68 74 20 62 65 20 69   that might be i
18d50 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 72 67 75  nvoked with argu
18d60 6d 65 6e 74 20 50 20 77 68 65 6e 65 76 65 72 0a  ment P whenever.
18d70 2a 2a 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73  ** an attempt is
18d80 20 6d 61 64 65 20 74 6f 20 61 63 63 65 73 73 20   made to access 
18d90 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
18da0 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
18db0 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
18dc0 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 77 68 65 6e  nnection] D when
18dd0 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64 0a   another thread.
18de0 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68 61  ** or process ha
18df0 73 20 74 68 65 20 74 61 62 6c 65 20 6c 6f 63 6b  s the table lock
18e00 65 64 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  ed..** The sqlit
18e10 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28  e3_busy_handler(
18e20 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75  ) interface is u
18e30 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
18e40 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  .** [sqlite3_bus
18e50 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 61 6e 64  y_timeout()] and
18e60 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74 69   [PRAGMA busy_ti
18e70 6d 65 6f 75 74 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49  meout]..**.** ^I
18e80 66 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62  f the busy callb
18e90 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65  ack is NULL, the
18ea0 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  n [SQLITE_BUSY] 
18eb0 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  or [SQLITE_IOERR
18ec0 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20  _BLOCKED].** is 
18ed0 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
18ee0 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e  tely upon encoun
18ef0 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e  tering the lock.
18f00 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63    ^If the busy c
18f10 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f  allback.** is no
18f20 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65  t NULL, then the
18f30 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20   callback might 
18f40 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  be invoked with 
18f50 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  two arguments..*
18f60 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
18f70 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
18f80 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20  busy handler is 
18f90 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f  a copy of the vo
18fa0 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  id* pointer whic
18fb0 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72  h.** is the thir
18fc0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71  d argument to sq
18fd0 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c  lite3_busy_handl
18fe0 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f  er().  ^The seco
18ff0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  nd argument to.*
19000 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  * the busy handl
19010 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74  er callback is t
19020 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d  he number of tim
19030 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79  es that the busy
19040 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20   handler has.** 
19050 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72  been invoked for
19060 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69 6e   the same lockin
19070 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68  g event.  ^If th
19080 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61  e.** busy callba
19090 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68  ck returns 0, th
190a0 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c  en no additional
190b0 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61   attempts are ma
190c0 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20  de to.** access 
190d0 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  the database and
190e0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
190f0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
19100 42 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75  BLOCKED] is retu
19110 72 6e 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 61  rned.** to the a
19120 70 70 6c 69 63 61 74 69 6f 6e 2e 0a 2a 2a 20 5e  pplication..** ^
19130 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
19140 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
19150 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20 61  , then another a
19160 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61 64  ttempt.** is mad
19170 65 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  e to access the 
19180 64 61 74 61 62 61 73 65 20 61 6e 64 20 74 68 65  database and the
19190 20 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a   cycle repeats..
191a0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e  **.** The presen
191b0 63 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e  ce of a busy han
191c0 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75  dler does not gu
191d0 61 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20  arantee that it 
191e0 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a  will be invoked.
191f0 2a 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73  ** when there is
19200 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e   lock contention
19210 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74  . ^If SQLite det
19220 65 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76  ermines that inv
19230 6f 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a  oking the busy.*
19240 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20  * handler could 
19250 72 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64  result in a dead
19260 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f  lock, it will go
19270 20 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72   ahead and retur
19280 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a  n [SQLITE_BUSY].
19290 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  ** or [SQLITE_IO
192a0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 74 6f 20  ERR_BLOCKED] to 
192b0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
192c0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
192d0 69 6e 67 20 74 68 65 20 0a 2a 2a 20 62 75 73 79  ing the .** busy
192e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e   handler..** Con
192f0 73 69 64 65 72 20 61 20 73 63 65 6e 61 72 69 6f  sider a scenario
19300 20 77 68 65 72 65 20 6f 6e 65 20 70 72 6f 63 65   where one proce
19310 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20  ss is holding a 
19320 72 65 61 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a  read lock that.*
19330 2a 20 69 74 20 69 73 20 74 72 79 69 6e 67 20 74  * it is trying t
19340 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72  o promote to a r
19350 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64  eserved lock and
19360 0a 2a 2a 20 61 20 73 65 63 6f 6e 64 20 70 72 6f  .** a second pro
19370 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e 67 20  cess is holding 
19380 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b 20  a reserved lock 
19390 74 68 61 74 20 69 74 20 69 73 20 74 72 79 69 6e  that it is tryin
193a0 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20  g.** to promote 
193b0 74 6f 20 61 6e 20 65 78 63 6c 75 73 69 76 65 20  to an exclusive 
193c0 6c 6f 63 6b 2e 20 20 54 68 65 20 66 69 72 73 74  lock.  The first
193d0 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20   process cannot 
193e0 70 72 6f 63 65 65 64 0a 2a 2a 20 62 65 63 61 75  proceed.** becau
193f0 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65 64  se it is blocked
19400 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 20 61   by the second a
19410 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  nd the second pr
19420 6f 63 65 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20  ocess cannot.** 
19430 70 72 6f 63 65 65 64 20 62 65 63 61 75 73 65 20  proceed because 
19440 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
19450 20 74 68 65 20 66 69 72 73 74 2e 20 20 49 66 20   the first.  If 
19460 62 6f 74 68 20 70 72 6f 63 65 73 73 65 73 0a 2a  both processes.*
19470 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20 62 75 73  * invoke the bus
19480 79 20 68 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74  y handlers, neit
19490 68 65 72 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e  her will make an
194a0 79 20 70 72 6f 67 72 65 73 73 2e 20 20 54 68 65  y progress.  The
194b0 72 65 66 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74  refore,.** SQLit
194c0 65 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54  e returns [SQLIT
194d0 45 5f 42 55 53 59 5d 20 66 6f 72 20 74 68 65 20  E_BUSY] for the 
194e0 66 69 72 73 74 20 70 72 6f 63 65 73 73 2c 20 68  first process, h
194f0 6f 70 69 6e 67 20 74 68 61 74 20 74 68 69 73 0a  oping that this.
19500 2a 2a 20 77 69 6c 6c 20 69 6e 64 75 63 65 20 74  ** will induce t
19510 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
19520 20 74 6f 20 72 65 6c 65 61 73 65 20 69 74 73 20   to release its 
19530 72 65 61 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c  read lock and al
19540 6c 6f 77 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e  low.** the secon
19550 64 20 70 72 6f 63 65 73 73 20 74 6f 20 70 72 6f  d process to pro
19560 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ceed..**.** ^The
19570 20 64 65 66 61 75 6c 74 20 62 75 73 79 20 63 61   default busy ca
19580 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a  llback is NULL..
19590 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49  **.** ^The [SQLI
195a0 54 45 5f 42 55 53 59 5d 20 65 72 72 6f 72 20 69  TE_BUSY] error i
195b0 73 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 5b  s converted to [
195c0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f  SQLITE_IOERR_BLO
195d0 43 4b 45 44 5d 0a 2a 2a 20 77 68 65 6e 20 53 51  CKED].** when SQ
195e0 4c 69 74 65 20 69 73 20 69 6e 20 74 68 65 20 6d  Lite is in the m
195f0 69 64 64 6c 65 20 6f 66 20 61 20 6c 61 72 67 65  iddle of a large
19600 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 77 68 65   transaction whe
19610 72 65 20 61 6c 6c 20 74 68 65 0a 2a 2a 20 63 68  re all the.** ch
19620 61 6e 67 65 73 20 77 69 6c 6c 20 6e 6f 74 20 66  anges will not f
19630 69 74 20 69 6e 74 6f 20 74 68 65 20 69 6e 2d 6d  it into the in-m
19640 65 6d 6f 72 79 20 63 61 63 68 65 2e 20 20 53 51  emory cache.  SQ
19650 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72  Lite will.** alr
19660 65 61 64 79 20 68 6f 6c 64 20 61 20 52 45 53 45  eady hold a RESE
19670 52 56 45 44 20 6c 6f 63 6b 20 6f 6e 20 74 68 65  RVED lock on the
19680 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 2c 20   database file, 
19690 62 75 74 20 69 74 20 6e 65 65 64 73 0a 2a 2a 20  but it needs.** 
196a0 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 69 73 20  to promote this 
196b0 6c 6f 63 6b 20 74 6f 20 45 58 43 4c 55 53 49 56  lock to EXCLUSIV
196c0 45 20 73 6f 20 74 68 61 74 20 69 74 20 63 61 6e  E so that it can
196d0 20 73 70 69 6c 6c 20 63 61 63 68 65 0a 2a 2a 20   spill cache.** 
196e0 70 61 67 65 73 20 69 6e 74 6f 20 74 68 65 20 64  pages into the d
196f0 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 69 74  atabase file wit
19700 68 6f 75 74 20 68 61 72 6d 20 74 6f 20 63 6f 6e  hout harm to con
19710 63 75 72 72 65 6e 74 0a 2a 2a 20 72 65 61 64 65  current.** reade
19720 72 73 2e 20 20 5e 49 66 20 69 74 20 69 73 20 75  rs.  ^If it is u
19730 6e 61 62 6c 65 20 74 6f 20 70 72 6f 6d 6f 74 65  nable to promote
19740 20 74 68 65 20 6c 6f 63 6b 2c 20 74 68 65 6e 20   the lock, then 
19750 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a  the in-memory.**
19760 20 63 61 63 68 65 20 77 69 6c 6c 20 62 65 20 6c   cache will be l
19770 65 66 74 20 69 6e 20 61 6e 20 69 6e 63 6f 6e 73  eft in an incons
19780 69 73 74 65 6e 74 20 73 74 61 74 65 20 61 6e 64  istent state and
19790 20 73 6f 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a   so the error.**
197a0 20 63 6f 64 65 20 69 73 20 70 72 6f 6d 6f 74 65   code is promote
197b0 64 20 66 72 6f 6d 20 74 68 65 20 72 65 6c 61 74  d from the relat
197c0 69 76 65 6c 79 20 62 65 6e 69 67 6e 20 5b 53 51  ively benign [SQ
197d0 4c 49 54 45 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a  LITE_BUSY] to.**
197e0 20 74 68 65 20 6d 6f 72 65 20 73 65 76 65 72 65   the more severe
197f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
19800 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54 68 69 73 20  LOCKED].  ^This 
19810 65 72 72 6f 72 20 63 6f 64 65 20 70 72 6f 6d 6f  error code promo
19820 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63 65 73 20 61  tion.** forces a
19830 6e 20 61 75 74 6f 6d 61 74 69 63 20 72 6f 6c 6c  n automatic roll
19840 62 61 63 6b 20 6f 66 20 74 68 65 20 63 68 61 6e  back of the chan
19850 67 65 73 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a  ges.  See the.**
19860 20 3c 61 20 68 72 65 66 3d 22 2f 63 76 73 74 72   <a href="/cvstr
19870 61 63 2f 77 69 6b 69 3f 70 3d 43 6f 72 72 75 70  ac/wiki?p=Corrup
19880 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73  tionFollowingBus
19890 79 45 72 72 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72  yError">.** Corr
198a0 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42  uptionFollowingB
198b0 75 73 79 45 72 72 6f 72 3c 2f 61 3e 20 77 69 6b  usyError</a> wik
198c0 69 20 70 61 67 65 20 66 6f 72 20 61 20 64 69 73  i page for a dis
198d0 63 75 73 73 69 6f 6e 20 6f 66 20 77 68 79 0a 2a  cussion of why.*
198e0 2a 20 74 68 69 73 20 69 73 20 69 6d 70 6f 72 74  * this is import
198f0 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ant..**.** ^(The
19900 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61  re can only be a
19910 20 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e   single busy han
19920 64 6c 65 72 20 64 65 66 69 6e 65 64 20 66 6f 72  dler defined for
19930 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61   each.** [databa
19940 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
19950 20 53 65 74 74 69 6e 67 20 61 20 6e 65 77 20 62   Setting a new b
19960 75 73 79 20 68 61 6e 64 6c 65 72 20 63 6c 65 61  usy handler clea
19970 72 73 20 61 6e 79 0a 2a 2a 20 70 72 65 76 69 6f  rs any.** previo
19980 75 73 6c 79 20 73 65 74 20 68 61 6e 64 6c 65 72  usly set handler
19990 2e 29 5e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  .)^  ^Note that 
199a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
199b0 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
199c0 0a 2a 2a 20 6f 72 20 65 76 61 6c 75 61 74 69 6e  .** or evaluatin
199d0 67 20 5b 50 52 41 47 4d 41 20 62 75 73 79 5f 74  g [PRAGMA busy_t
199e0 69 6d 65 6f 75 74 3d 4e 5d 20 77 69 6c 6c 20 63  imeout=N] will c
199f0 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 62 75 73  hange the.** bus
19a00 79 20 68 61 6e 64 6c 65 72 20 61 6e 64 20 74 68  y handler and th
19a10 75 73 20 63 6c 65 61 72 20 61 6e 79 20 70 72 65  us clear any pre
19a20 76 69 6f 75 73 6c 79 20 73 65 74 20 62 75 73 79  viously set busy
19a30 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20   handler..**.** 
19a40 54 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63  The busy callbac
19a50 6b 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b  k should not tak
19a60 65 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68  e any actions wh
19a70 69 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a  ich modify the.*
19a80 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
19a90 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b  ction that invok
19aa0 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ed the busy hand
19ab0 6c 65 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ler.  In other w
19ac0 6f 72 64 73 2c 0a 2a 2a 20 74 68 65 20 62 75 73  ords,.** the bus
19ad0 79 20 68 61 6e 64 6c 65 72 20 69 73 20 6e 6f 74  y handler is not
19ae0 20 72 65 65 6e 74 72 61 6e 74 2e 20 20 41 6e 79   reentrant.  Any
19af0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
19b00 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
19b10 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
19b20 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
19b30 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
19b40 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
19b50 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
19b60 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
19b70 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
19b80 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
19b90 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
19ba0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
19bb0 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
19bc0 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
19bd0 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
19be0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
19bf0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
19c00 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
19c10 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
19c20 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
19c30 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
19c40 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
19c50 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
19c60 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
19c70 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
19c80 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
19c90 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
19ca0 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
19cb0 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
19cc0 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
19cd0 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
19ce0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
19cf0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
19d00 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
19d10 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
19d20 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
19d30 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
19d40 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
19d50 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
19d60 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
19d70 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
19d80 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
19d90 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
19da0 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
19db0 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
19dc0 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
19dd0 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
19de0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
19df0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
19e00 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
19e10 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
19e20 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
19e30 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
19e40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
19e50 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
19e60 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
19e70 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
19e80 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
19e90 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
19ea0 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
19eb0 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
19ec0 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
19ed0 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
19ee0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
19ef0 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  ed.)^.**.** See 
19f00 61 6c 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62  also:  [PRAGMA b
19f10 75 73 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a  usy_timeout].*/.
19f20 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79  int sqlite3_busy
19f30 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33  _timeout(sqlite3
19f40 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a  *, int ms);../*.
19f50 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
19f60 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65  venience Routine
19f70 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75  s For Running Qu
19f80 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73  eries.**.** This
19f90 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74   is a legacy int
19fa0 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20 70  erface that is p
19fb0 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61 63  reserved for bac
19fc0 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
19fd0 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20  lity..** Use of 
19fe0 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 69  this interface i
19ff0 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65  s not recommende
1a000 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74  d..**.** Definit
1a010 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74  ion: A <b>result
1a020 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65   table</b> is me
1a030 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63 74  mory data struct
1a040 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20 74  ure created by t
1a050 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67  he.** [sqlite3_g
1a060 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65  et_table()] inte
1a070 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74  rface.  A result
1a080 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74   table records t
1a090 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71  he.** complete q
1a0a0 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f  uery results fro
1a0b0 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75  m one or more qu
1a0c0 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  eries..**.** The
1a0d0 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61   table conceptua
1a0e0 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72  lly has a number
1a0f0 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c   of rows and col
1a100 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68  umns.  But.** th
1a110 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20  ese numbers are 
1a120 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65 20  not part of the 
1a130 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73  result table its
1a140 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e  elf.  These.** n
1a150 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61 69  umbers are obtai
1a160 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20  ned separately. 
1a170 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75   Let N be the nu
1a180 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20  mber of rows.** 
1a190 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d  and M be the num
1a1a0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a  ber of columns..
1a1b0 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74  **.** A result t
1a1c0 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79  able is an array
1a1d0 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
1a1e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
1a1f0 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a  UTF-8 strings..*
1a200 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31  * There are (N+1
1a210 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20  )*M elements in 
1a220 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65 20  the array.  The 
1a230 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73  first M pointers
1a240 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72   point.** to zer
1a250 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72  o-terminated str
1a260 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61  ings that  conta
1a270 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20  in the names of 
1a280 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20  the columns..** 
1a290 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e  The remaining en
1a2a0 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20  tries all point 
1a2b0 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74 73  to query results
1a2c0 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72  .  NULL values r
1a2d0 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c  esult.** in NULL
1a2e0 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20   pointers.  All 
1a2f0 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72 65  other values are
1a300 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20   in their UTF-8 
1a310 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
1a320 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65 73  ** string repres
1a330 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75  entation as retu
1a340 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  rned by [sqlite3
1a350 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e  _column_text()].
1a360 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
1a370 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73  table might cons
1a380 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f  ist of one or mo
1a390 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  re memory alloca
1a3a0 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20  tions..** It is 
1a3b0 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73 73  not safe to pass
1a3c0 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   a result table 
1a3d0 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c  directly to [sql
1a3e0 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
1a3f0 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
1a400 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f  should be deallo
1a410 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  cated using [sql
1a420 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
1a430 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61  )]..**.** ^(As a
1a440 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65  n example of the
1a450 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f   result table fo
1a460 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20  rmat, suppose a 
1a470 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20  query result.** 
1a480 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1a490 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1a4a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20  ><pre>.**       
1a4b0 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41   Name        | A
1a4c0 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d  ge.**        ---
1a4d0 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a4e0 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41  ----.**        A
1a4f0 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a  lice       | 43.
1a500 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20 20  **        Bob   
1a510 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20        | 28.**   
1a520 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20 20       Cindy      
1a530 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c   | 21.** </pre><
1a540 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1a550 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77 6f  ** There are two
1a560 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61   column (M==2) a
1a570 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e  nd three rows (N
1a580 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a  ==3).  Thus the.
1a590 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20  ** result table 
1a5a0 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20  has 8 entries.  
1a5b0 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73 75  Suppose the resu
1a5c0 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72  lt table is stor
1a5d0 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61  ed.** in an arra
1a5e0 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74  y names azResult
1a5f0 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74  .  Then azResult
1a600 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74   holds this cont
1a610 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63  ent:.**.** <bloc
1a620 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20  kquote><pre>.** 
1a630 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
1a640 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b  #91;0] = "Name";
1a650 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
1a660 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67  ult&#91;1] = "Ag
1a670 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  e";.**        az
1a680 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20  Result&#91;2] = 
1a690 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20  "Alice";.**     
1a6a0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a6b0 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20  3] = "43";.**   
1a6c0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a6d0 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a  1;4] = "Bob";.**
1a6e0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a6f0 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a  &#91;5] = "28";.
1a700 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75  **        azResu
1a710 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e  lt&#91;6] = "Cin
1a720 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  dy";.**        a
1a730 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d  zResult&#91;7] =
1a740 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e   "21";.** </pre>
1a750 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a  </blockquote>)^.
1a760 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1a770 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66  e3_get_table() f
1a780 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65  unction evaluate
1a790 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  s one or more.**
1a7a0 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72   semicolon-separ
1a7b0 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
1a7c0 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d  nts in the zero-
1a7d0 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38  terminated UTF-8
1a7e0 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74  .** string of it
1a7f0 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  s 2nd parameter 
1a800 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72 65  and returns a re
1a810 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68  sult table to th
1a820 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76  e.** pointer giv
1a830 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70 61  en in its 3rd pa
1a840 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41  rameter..**.** A
1a850 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63 61  fter the applica
1a860 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65  tion has finishe
1a870 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75 6c  d with the resul
1a880 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67  t from sqlite3_g
1a890 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69  et_table(),.** i
1a8a0 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65 20  t must pass the 
1a8b0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69  result table poi
1a8c0 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
1a8d0 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20  free_table() in 
1a8e0 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65  order to.** rele
1a8f0 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74  ase the memory t
1a900 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64  hat was malloced
1a910 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74 68  .  Because of th
1a920 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71  e way the.** [sq
1a930 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a940 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73  happens within s
1a950 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1a960 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a  (), the calling.
1a970 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ** function must
1a980 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c   not try to call
1a990 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a9a0 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c  ] directly.  Onl
1a9b0 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  y.** [sqlite3_fr
1a9c0 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61  ee_table()] is a
1a9d0 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74  ble to release t
1a9e0 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72  he memory proper
1a9f0 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a  ly and safely..*
1aa00 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
1aa10 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74  _get_table() int
1aa20 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d  erface is implem
1aa30 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70 70  ented as a wrapp
1aa40 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
1aa50 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20  lite3_exec()].  
1aa60 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
1aa70 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20  table() routine 
1aa80 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63  does not have ac
1aa90 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69  cess.** to any i
1aaa0 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72  nternal data str
1aab0 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74  uctures of SQLit
1aac0 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79  e.  It uses only
1aad0 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69   the public.** i
1aae0 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65 64  nterface defined
1aaf0 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e   here.  As a con
1ab00 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73  sequence, errors
1ab10 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74   that occur in t
1ab20 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61  he.** wrapper la
1ab30 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74  yer outside of t
1ab40 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c  he internal [sql
1ab50 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c  ite3_exec()] cal
1ab60 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66  l are not.** ref
1ab70 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65 71  lected in subseq
1ab80 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73  uent calls to [s
1ab90 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
1aba0 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ] or.** [sqlite3
1abb0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69  _errmsg()]..*/.i
1abc0 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74  nt sqlite3_get_t
1abd0 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20  able(.  sqlite3 
1abe0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
1abf0 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73   An open databas
1ac00 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
1ac10 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20  r *zSql,     /* 
1ac20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61  SQL to be evalua
1ac30 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  ted */.  char **
1ac40 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f  *pazResult,    /
1ac50 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65  * Results of the
1ac60 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20   query */.  int 
1ac70 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20  *pnRow,         
1ac80 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72    /* Number of r
1ac90 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74  esult rows writt
1aca0 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74  en here */.  int
1acb0 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20   *pnColumn,     
1acc0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
1acd0 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77  result columns w
1ace0 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20  ritten here */. 
1acf0 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67   char **pzErrmsg
1ad00 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20         /* Error 
1ad10 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72 65  msg written here
1ad20 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69   */.);.void sqli
1ad30 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63  te3_free_table(c
1ad40 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a  har **result);..
1ad50 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ad60 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67  Formatted String
1ad70 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69   Printing Functi
1ad80 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
1ad90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72  routines are wor
1ada0 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20  k-alikes of the 
1adb0 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c  "printf()" famil
1adc0 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a  y of functions.*
1add0 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  * from the stand
1ade0 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
1adf0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
1ae00 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20  3_mprintf() and 
1ae10 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66  sqlite3_vmprintf
1ae20 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74  () routines writ
1ae30 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c  e their.** resul
1ae40 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  ts into memory o
1ae50 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71  btained from [sq
1ae60 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e  lite3_malloc()].
1ae70 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20  .** The strings 
1ae80 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 73  returned by thes
1ae90 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73  e two routines s
1aea0 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65  hould be.** rele
1aeb0 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  ased by [sqlite3
1aec0 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68  _free()].  ^Both
1aed0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
1aee0 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74   a.** NULL point
1aef0 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d  er if [sqlite3_m
1af00 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62  alloc()] is unab
1af10 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65  le to allocate e
1af20 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20  nough.** memory 
1af30 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75  to hold the resu
1af40 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a  lting string..**
1af50 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65  .** ^(The sqlite
1af60 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75  3_snprintf() rou
1af70 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20  tine is similar 
1af80 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20  to "snprintf()" 
1af90 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e  from.** the stan
1afa0 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20  dard C library. 
1afb0 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20 77   The result is w
1afc0 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a  ritten into the.
1afd0 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c 69  ** buffer suppli
1afe0 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
1aff0 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65   parameter whose
1b000 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62   size is given b
1b010 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70  y.** the first p
1b020 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74  arameter. Note t
1b030 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66  hat the order of
1b040 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77   the.** first tw
1b050 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20  o parameters is 
1b060 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e  reversed from sn
1b070 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69  printf().)^  Thi
1b080 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f  s is an.** histo
1b090 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74  rical accident t
1b0a0 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69  hat cannot be fi
1b0b0 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65 61  xed without brea
1b0c0 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64  king.** backward
1b0d0 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  s compatibility.
1b0e0 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68    ^(Note also th
1b0f0 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  at sqlite3_snpri
1b100 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73  ntf().** returns
1b110 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74   a pointer to it
1b120 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61 64  s buffer instead
1b130 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   of the number o
1b140 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  f.** characters 
1b150 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e  actually written
1b160 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72   into the buffer
1b170 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68  .)^  We admit th
1b180 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  at.** the number
1b190 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20 77   of characters w
1b1a0 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20  ritten would be 
1b1b0 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65  a more useful re
1b1c0 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75  turn.** value bu
1b1d0 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e  t we cannot chan
1b1e0 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ge the implement
1b1f0 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33  ation of sqlite3
1b200 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e  _snprintf().** n
1b210 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b  ow without break
1b220 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  ing compatibilit
1b230 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e  y..**.** ^As lon
1b240 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72 20  g as the buffer 
1b250 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72 20  size is greater 
1b260 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74  than zero, sqlit
1b270 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a  e3_snprintf().**
1b280 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74   guarantees that
1b290 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20 61   the buffer is a
1b2a0 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69  lways zero-termi
1b2b0 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72  nated.  ^The fir
1b2c0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  st.** parameter 
1b2d0 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c  "n" is the total
1b2e0 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66   size of the buf
1b2f0 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73  fer, including s
1b300 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  pace for.** the 
1b310 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
1b320 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74    So the longest
1b330 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e   string that can
1b340 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a   be completely.*
1b350 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62  * written will b
1b360 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73  e n-1 characters
1b370 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
1b380 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29  ite3_vsnprintf()
1b390 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61   routine is a va
1b3a0 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66  rargs version of
1b3b0 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1b3c0 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  f()..**.** These
1b3d0 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d   routines all im
1b3e0 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64  plement some add
1b3f0 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69  itional formatti
1b400 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68  ng.** options th
1b410 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f  at are useful fo
1b420 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53  r constructing S
1b430 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  QL statements..*
1b440 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75  * All of the usu
1b450 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d  al printf() form
1b460 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61  atting options a
1b470 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69  pply.  In additi
1b480 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20  on, there.** is 
1b490 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20  are "%q", "%Q", 
1b4a0 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73  and "%z" options
1b4b0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71  ..**.** ^(The %q
1b4c0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1b4d0 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69 74  ke %s in that it
1b4e0 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20 6e   substitutes a n
1b4f0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ul-terminated.**
1b500 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65   string from the
1b510 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20   argument list. 
1b520 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75   But %q also dou
1b530 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27 20  bles every '\'' 
1b540 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71  character..** %q
1b550 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72   is designed for
1b560 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73 74   use inside a st
1b570 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20  ring literal.)^ 
1b580 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63   By doubling eac
1b590 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63  h '\''.** charac
1b5a0 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20 74  ter it escapes t
1b5b0 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61 6e  hat character an
1b5c0 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62  d allows it to b
1b5d0 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a  e inserted into.
1b5e0 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a  ** the string..*
1b5f0 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65  *.** For example
1b600 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74 72  , assume the str
1b610 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65  ing variable zTe
1b620 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74  xt contains text
1b630 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b640 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b650 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b660 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20 68  Text = "It's a h
1b670 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c  appy day!";.** <
1b680 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1b690 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e  e>.**.** One can
1b6a0 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20 69   use this text i
1b6b0 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1b6c0 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  nt as follows:.*
1b6d0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b6e0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20  ><pre>.**  char 
1b6f0 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f  *zSQL = sqlite3_
1b700 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20  mprintf("INSERT 
1b710 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45  INTO table VALUE
1b720 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29  S('%q')", zText)
1b730 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1b740 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1b750 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1b760 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1b770 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1b780 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61  uote>.**.** Beca
1b790 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61  use the %q forma
1b7a0 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65 64  t string is used
1b7b0 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72 61  , the '\'' chara
1b7c0 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a  cter in zText.**
1b7d0 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64 20   is escaped and 
1b7e0 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65  the SQL generate
1b7f0 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  d is as follows:
1b800 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b810 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53  te><pre>.**  INS
1b820 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20  ERT INTO table1 
1b830 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61 20  VALUES('It''s a 
1b840 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20  happy day!').** 
1b850 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b860 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  te>.**.** This i
1b870 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20  s correct.  Had 
1b880 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74 65  we used %s inste
1b890 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65  ad of %q, the ge
1b8a0 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77  nerated SQL.** w
1b8b0 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64  ould have looked
1b8c0 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
1b8d0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
1b8e0 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49  re>.**  INSERT I
1b8f0 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45  NTO table1 VALUE
1b900 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79 20  S('It's a happy 
1b910 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65  day!');.** </pre
1b920 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
1b930 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64  *.** This second
1b940 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53   example is an S
1b950 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e  QL syntax error.
1b960 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72    As a general r
1b970 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a  ule you should.*
1b980 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71 20  * always use %q 
1b990 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77 68  instead of %s wh
1b9a0 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78  en inserting tex
1b9b0 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20  t into a string 
1b9c0 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  literal..**.** ^
1b9d0 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77  (The %Q option w
1b9e0 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63  orks like %q exc
1b9f0 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73  ept it also adds
1ba00 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61   single quotes a
1ba10 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74  round.** the out
1ba20 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61  side of the tota
1ba30 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74  l string.  Addit
1ba40 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20  ionally, if the 
1ba50 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65  parameter in the
1ba60 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73  .** argument lis
1ba70 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  t is a NULL poin
1ba80 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74 75  ter, %Q substitu
1ba90 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e 55  tes the text "NU
1baa0 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20  LL" (without.** 
1bab0 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29  single quotes).)
1bac0 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70  ^  So, for examp
1bad0 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61  le, one could sa
1bae0 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  y:.**.** <blockq
1baf0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63  uote><pre>.**  c
1bb00 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69  har *zSQL = sqli
1bb10 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53  te3_mprintf("INS
1bb20 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56  ERT INTO table V
1bb30 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78  ALUES(%Q)", zTex
1bb40 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f  t);.**  sqlite3_
1bb50 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30  exec(db, zSQL, 0
1bb60 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c  , 0, 0);.**  sql
1bb70 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b  ite3_free(zSQL);
1bb80 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63  .** </pre></bloc
1bb90 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68  kquote>.**.** Th
1bba0 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c  e code above wil
1bbb0 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65  l render a corre
1bbc0 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ct SQL statement
1bbd0 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20   in the zSQL.** 
1bbe0 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66  variable even if
1bbf0 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69 61   the zText varia
1bc00 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  ble is a NULL po
1bc10 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  inter..**.** ^(T
1bc20 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69  he "%z" formatti
1bc30 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20  ng option works 
1bc40 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77 69  like "%s" but wi
1bc50 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69  th the.** additi
1bc60 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74 68  on that after th
1bc70 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65 65  e string has bee
1bc80 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65  n read and copie
1bc90 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65  d into.** the re
1bca0 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66  sult, [sqlite3_f
1bcb0 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64  ree()] is called
1bcc0 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   on the input st
1bcd0 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20  ring.)^.*/.char 
1bce0 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66  *sqlite3_mprintf
1bcf0 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e  (const char*,...
1bd00 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1bd10 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20  _vmprintf(const 
1bd20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b  char*, va_list);
1bd30 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73  .char *sqlite3_s
1bd40 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72  nprintf(int,char
1bd50 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e  *,const char*, .
1bd60 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74  ..);.char *sqlit
1bd70 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74  e3_vsnprintf(int
1bd80 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61  ,char*,const cha
1bd90 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f  r*, va_list);../
1bda0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1bdb0 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e  emory Allocation
1bdc0 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a   Subsystem.**.**
1bdd0 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65   The SQLite core
1bde0 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72 65   uses these thre
1bdf0 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61  e routines for a
1be00 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a  ll of its own.**
1be10 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79   internal memory
1be20 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64   allocation need
1be30 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65  s. "Core" in the
1be40 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e   previous senten
1be50 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69  ce.** does not i
1be60 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67  nclude operating
1be70 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69 63  -system specific
1be80 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
1be90 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e  ion.  The.** Win
1bea0 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e 61  dows VFS uses na
1beb0 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  tive malloc() an
1bec0 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d  d free() for som
1bed0 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a  e operations..**
1bee0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1bef0 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e  _malloc() routin
1bf00 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
1bf10 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a  ter to a block.*
1bf20 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c  * of memory at l
1bf30 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20  east N bytes in 
1bf40 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20  length, where N 
1bf50 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  is the parameter
1bf60 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1bf70 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61  _malloc() is una
1bf80 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75  ble to obtain su
1bf90 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a  fficient free.**
1bfa0 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75   memory, it retu
1bfb0 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
1bfc0 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72  er.  ^If the par
1bfd0 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73  ameter N to.** s
1bfe0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20  qlite3_malloc() 
1bff0 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74  is zero or negat
1c000 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ive then sqlite3
1c010 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e  _malloc() return
1c020 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  s.** a NULL poin
1c030 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  ter..**.** ^Call
1c040 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65  ing sqlite3_free
1c050 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65  () with a pointe
1c060 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74  r previously ret
1c070 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69  urned.** by sqli
1c080 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20  te3_malloc() or 
1c090 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c0a0 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74 20  ) releases that 
1c0b0 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61  memory so.** tha
1c0c0 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72 65  t it might be re
1c0d0 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69  used.  ^The sqli
1c0e0 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69  te3_free() routi
1c0f0 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70  ne is.** a no-op
1c100 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69   if is called wi
1c110 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  th a NULL pointe
1c120 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55  r.  Passing a NU
1c130 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f  LL pointer.** to
1c140 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20   sqlite3_free() 
1c150 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66  is harmless.  Af
1c160 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c  ter being freed,
1c170 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c   memory.** shoul
1c180 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65 61  d neither be rea
1c190 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20  d nor written.  
1c1a0 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65  Even reading pre
1c1b0 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a  viously freed.**
1c1c0 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65   memory might re
1c1d0 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e  sult in a segmen
1c1e0 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20  tation fault or 
1c1f0 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72 72  other severe err
1c200 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f  or..** Memory co
1c210 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d  rruption, a segm
1c220 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20  entation fault, 
1c230 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65 20  or other severe 
1c240 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72  error.** might r
1c250 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33  esult if sqlite3
1c260 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65  _free() is calle
1c270 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c  d with a non-NUL
1c280 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a  L pointer that.*
1c290 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e  * was not obtain
1c2a0 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ed from sqlite3_
1c2b0 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69  malloc() or sqli
1c2c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
1c2d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
1c2e0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74  e3_realloc() int
1c2f0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
1c300 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70  to resize a.** p
1c310 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  rior memory allo
1c320 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20  cation to be at 
1c330 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77  least N bytes, w
1c340 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a  here N is the.**
1c350 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1c360 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61  r.  The memory a
1c370 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20  llocation to be 
1c380 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20 66  resized is the f
1c390 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65  irst.** paramete
1c3a0 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69  r.)^ ^ If the fi
1c3b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
1c3c0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
1c3d0 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  ().** is a NULL 
1c3e0 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73  pointer then its
1c3f0 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64 65   behavior is ide
1c400 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e  ntical to callin
1c410 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c  g.** sqlite3_mal
1c420 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69  loc(N) where N i
1c430 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  s the second par
1c440 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c450 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20  3_realloc()..** 
1c460 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70  ^If the second p
1c470 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c480 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73  te3_realloc() is
1c490 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61   zero or.** nega
1c4a0 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62 65  tive then the be
1c4b0 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c  havior is exactl
1c4c0 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63 61  y the same as ca
1c4d0 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33  lling.** sqlite3
1c4e0 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20 50  _free(P) where P
1c4f0 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61   is the first pa
1c500 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1c510 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
1c520 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   ^sqlite3_reallo
1c530 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f  c() returns a po
1c540 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72  inter to a memor
1c550 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  y allocation.** 
1c560 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79  of at least N by
1c570 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e  tes in size or N
1c580 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e  ULL if sufficien
1c590 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76  t memory is unav
1c5a0 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20  ailable..** ^If 
1c5b0 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66  M is the size of
1c5c0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c5d0 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28  ation, then min(
1c5e0 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66  N,M) bytes.** of
1c5f0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c600 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64  ation are copied
1c610 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e   into the beginn
1c620 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72 65  ing of buffer re
1c630 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
1c640 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61  ite3_realloc() a
1c650 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c  nd the prior all
1c660 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64  ocation is freed
1c670 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33  ..** ^If sqlite3
1c680 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  _realloc() retur
1c690 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ns NULL, then th
1c6a0 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69  e prior allocati
1c6b0 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65  on.** is not fre
1c6c0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ed..**.** ^The m
1c6d0 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62  emory returned b
1c6e0 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  y sqlite3_malloc
1c6f0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  () and sqlite3_r
1c700 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61  ealloc().** is a
1c710 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f  lways aligned to
1c720 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62   at least an 8 b
1c730 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72  yte boundary, or
1c740 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20   to a.** 4 byte 
1c750 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65 20  boundary if the 
1c760 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41  [SQLITE_4_BYTE_A
1c770 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63  LIGNED_MALLOC] c
1c780 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f  ompile-time.** o
1c790 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a  ption is used..*
1c7a0 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76  *.** In SQLite v
1c7b0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64  ersion 3.5.0 and
1c7c0 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70   3.5.1, it was p
1c7d0 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e  ossible to defin
1c7e0 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f  e.** the SQLITE_
1c7f0 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f  OMIT_MEMORY_ALLO
1c800 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75  CATION which wou
1c810 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75 69  ld cause the bui
1c820 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  lt-in.** impleme
1c830 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65  ntation of these
1c840 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
1c850 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20 63  omitted.  That c
1c860 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20  apability.** is 
1c870 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64  no longer provid
1c880 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d  ed.  Only built-
1c890 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  in memory alloca
1c8a0 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65 64  tors can be used
1c8b0 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f  ..**.** Prior to
1c8c0 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
1c8d0 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64  3.7.10, the Wind
1c8e0 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65  ows OS interface
1c8f0 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a   layer called.**
1c900 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c   the system mall
1c910 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29 20  oc() and free() 
1c920 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f  directly when co
1c930 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65  nverting.** file
1c940 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68  names between th
1c950 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67  e UTF-8 encoding
1c960 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a   used by SQLite.
1c970 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72 20  ** and whatever 
1c980 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e  filename encodin
1c990 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68 65  g is used by the
1c9a0 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64   particular Wind
1c9b0 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74  ows.** installat
1c9c0 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c  ion.  Memory all
1c9d0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77  ocation errors w
1c9e0 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62 75  ere detected, bu
1c9f0 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72  t.** they were r
1ca00 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20  eported back as 
1ca10 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
1ca20 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ] or.** [SQLITE_
1ca30 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74 68  IOERR] rather th
1ca40 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  an [SQLITE_NOMEM
1ca50 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69  ]..**.** The poi
1ca60 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74  nter arguments t
1ca70 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  o [sqlite3_free(
1ca80 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1ca90 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75  realloc()].** mu
1caa0 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c  st be either NUL
1cab0 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65  L or else pointe
1cac0 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d  rs obtained from
1cad0 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f   a prior.** invo
1cae0 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74  cation of [sqlit
1caf0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20  e3_malloc()] or 
1cb00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
1cb10 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a  ()] that have.**
1cb20 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65   not yet been re
1cb30 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  leased..**.** Th
1cb40 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
1cb50 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77  st not read or w
1cb60 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66  rite any part of
1cb70 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d  .** a block of m
1cb80 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20 68  emory after it h
1cb90 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64  as been released
1cba0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
1cbb0 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73  e3_free()] or [s
1cbc0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1cbd0 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  ]..*/.void *sqli
1cbe0 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b  te3_malloc(int);
1cbf0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
1cc00 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e  ealloc(void*, in
1cc10 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  t);.void sqlite3
1cc20 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f  _free(void*);../
1cc30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
1cc40 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20  emory Allocator 
1cc50 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a  Statistics.**.**
1cc60 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73   SQLite provides
1cc70 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72   these two inter
1cc80 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74  faces for report
1cc90 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75  ing on the statu
1cca0 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c  s.** of the [sql
1ccb0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20  ite3_malloc()], 
1ccc0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1ccd0 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72  , and [sqlite3_r
1cce0 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75  ealloc()].** rou
1ccf0 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72  tines, which for
1cd00 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d  m the built-in m
1cd10 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
1cd20 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a   subsystem..**.*
1cd30 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  * ^The [sqlite3_
1cd40 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72  memory_used()] r
1cd50 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
1cd60 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
1cd70 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20  es.** of memory 
1cd80 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61  currently outsta
1cd90 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20  nding (malloced 
1cda0 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a  but not freed)..
1cdb0 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1cdc0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cdd0 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74  r()] routine ret
1cde0 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  urns the maximum
1cdf0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71  .** value of [sq
1ce00 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ce10 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68  d()] since the h
1ce20 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a  igh-water mark.*
1ce30 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65 74  * was last reset
1ce40 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  .  ^The values r
1ce50 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
1ce60 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1ce70 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1ce80 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1ce90 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61  ter()] include a
1cea0 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61  ny overhead.** a
1ceb0 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20 69  dded by SQLite i
1cec0 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61  n its implementa
1ced0 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1cee0 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62  _malloc()],.** b
1cef0 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20  ut not overhead 
1cf00 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e 79  added by the any
1cf10 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74   underlying syst
1cf20 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f  em library.** ro
1cf30 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c  utines that [sql
1cf40 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d  ite3_malloc()] m
1cf50 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ay call..**.** ^
1cf60 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d  The memory high-
1cf70 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65  water mark is re
1cf80 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72 65  set to the curre
1cf90 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b  nt value of.** [
1cfa0 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75  sqlite3_memory_u
1cfb0 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e  sed()] if and on
1cfc0 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ly if the parame
1cfd0 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  ter to.** [sqlit
1cfe0 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61  e3_memory_highwa
1cff0 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20  ter()] is true. 
1d000 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74 75   ^The value retu
1d010 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69  rned.** by [sqli
1d020 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1d030 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65 20  ater(1)] is the 
1d040 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1d050 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20  ** prior to the 
1d060 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65  reset..*/.sqlite
1d070 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
1d080 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64  memory_used(void
1d090 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  );.sqlite3_int64
1d0a0 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f   sqlite3_memory_
1d0b0 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72 65  highwater(int re
1d0c0 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a  setFlag);../*.**
1d0d0 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75 64   CAPI3REF: Pseud
1d0e0 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20  o-Random Number 
1d0f0 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20  Generator.**.** 
1d100 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20  SQLite contains 
1d110 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70  a high-quality p
1d120 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d  seudo-random num
1d130 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50  ber generator (P
1d140 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20  RNG) used to.** 
1d150 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52  select random [R
1d160 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77  OWID | ROWIDs] w
1d170 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65  hen inserting ne
1d180 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61  w records into a
1d190 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61   table that.** a
1d1a0 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65 20  lready uses the 
1d1b0 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65  largest possible
1d1c0 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50   [ROWID].  The P
1d1d0 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64  RNG is also used
1d1e0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c   for.** the buil
1d1f0 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e  d-in random() an
1d200 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53  d randomblob() S
1d210 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54  QL functions.  T
1d220 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1d230 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74  lows.** applicat
1d240 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74  ions to access t
1d250 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72  he same PRNG for
1d260 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e   other purposes.
1d270 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74  .**.** ^A call t
1d280 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73  o this routine s
1d290 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66  tores N bytes of
1d2a0 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f   randomness into
1d2b0 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49   buffer P..** ^I
1d2c0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
1d2d0 20 6f 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e   one, then P can
1d2e0 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
1d2f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  er..**.** ^If th
1d300 69 73 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e  is routine has n
1d310 6f 74 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73  ot been previous
1d320 6c 79 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20  ly called or if 
1d330 74 68 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20  the previous.** 
1d340 63 61 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20  call had N less 
1d350 74 68 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74  than one, then t
1d360 68 65 20 50 52 4e 47 20 69 73 20 73 65 65 64 65  he PRNG is seede
1d370 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65  d using randomne
1d380 73 73 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66  ss.** obtained f
1d390 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e  rom the xRandomn
1d3a0 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68  ess method of th
1d3b0 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74  e default [sqlit
1d3c0 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a  e3_vfs] object..
1d3d0 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 65 76 69  ** ^If the previ
1d3e0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
1d3f0 20 72 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20   routine had an 
1d400 4e 20 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74  N of 1 or more t
1d410 68 65 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64  hen.** the pseud
1d420 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20  o-randomness is 
1d430 67 65 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74  generated.** int
1d440 65 72 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68  ernally and with
1d450 6f 75 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20  out recourse to 
1d460 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
1d470 5d 20 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a  ] xRandomness.**
1d480 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64   method..*/.void
1d490 20 73 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e   sqlite3_randomn
1d4a0 65 73 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20  ess(int N, void 
1d4b0 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  *P);../*.** CAPI
1d4c0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69  3REF: Compile-Ti
1d4d0 6d 65 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e  me Authorization
1d4e0 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
1d4f0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
1d500 65 67 69 73 74 65 72 73 20 61 6e 20 61 75 74 68  egisters an auth
1d510 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1d520 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c 61  with a particula
1d530 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
1d540 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70  onnection], supp
1d550 6c 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73  lied in the firs
1d560 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  t argument..** ^
1d570 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  The authorizer c
1d580 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
1d590 65 64 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d  ed as SQL statem
1d5a0 65 6e 74 73 20 61 72 65 20 62 65 69 6e 67 20 63  ents are being c
1d5b0 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73  ompiled.** by [s
1d5c0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
1d5d0 5d 20 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74  ] or its variant
1d5e0 73 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  s [sqlite3_prepa
1d5f0 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71  re_v2()],.** [sq
1d600 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
1d610 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1d620 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e  prepare16_v2()].
1d630 20 20 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a    ^At various.**
1d640 20 70 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74   points during t
1d650 68 65 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70  he compilation p
1d660 72 6f 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63  rocess, as logic
1d670 20 69 73 20 62 65 69 6e 67 20 63 72 65 61 74 65   is being create
1d680 64 0a 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20  d.** to perform 
1d690 76 61 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c  various actions,
1d6a0 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   the authorizer 
1d6b0 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f  callback is invo
1d6c0 6b 65 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66  ked to.** see if
1d6d0 20 74 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61   those actions a
1d6e0 72 65 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68  re allowed.  ^Th
1d6f0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d700 6c 62 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20  lback should.** 
1d710 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
1d720 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20  K] to allow the 
1d730 61 63 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f  action, [SQLITE_
1d740 49 47 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c  IGNORE] to disal
1d750 6c 6f 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69  low the.** speci
1d760 66 69 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61  fic action but a
1d770 6c 6c 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61  llow the SQL sta
1d780 74 65 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e  tement to contin
1d790 75 65 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ue to be.** comp
1d7a0 69 6c 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45  iled, or [SQLITE
1d7b0 5f 44 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20  _DENY] to cause 
1d7c0 74 68 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73  the entire SQL s
1d7d0 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a  tatement to be.*
1d7e0 2a 20 72 65 6a 65 63 74 65 64 20 77 69 74 68 20  * rejected with 
1d7f0 61 6e 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  an error.  ^If t
1d800 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d810 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1d820 2a 20 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65  * any value othe
1d830 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49  r than [SQLITE_I
1d840 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f  GNORE], [SQLITE_
1d850 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OK], or [SQLITE_
1d860 44 45 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  DENY].** then th
1d870 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  e [sqlite3_prepa
1d880 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69  re_v2()] or equi
1d890 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74  valent call that
1d8a0 20 74 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68   triggered.** th
1d8b0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c  e authorizer wil
1d8c0 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65  l fail with an e
1d8d0 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a  rror message..**
1d8e0 0a 2a 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c  .** When the cal
1d8f0 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
1d900 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20  QLITE_OK], that 
1d910 6d 65 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74  means the operat
1d920 69 6f 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64  ion.** requested
1d930 20 69 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74   is ok.  ^When t
1d940 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75  he callback retu
1d950 72 6e 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59  rns [SQLITE_DENY
1d960 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ], the.** [sqlit
1d970 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1d980 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63   or equivalent c
1d990 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67 65 72  all that trigger
1d9a0 65 64 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  ed the.** author
1d9b0 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77  izer will fail w
1d9c0 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73  ith an error mes
1d9d0 73 61 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20  sage explaining 
1d9e0 74 68 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69  that.** access i
1d9f0 73 20 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a  s denied. .**.**
1da00 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
1da10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74  meter to the aut
1da20 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1da30 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
1da40 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
1da50 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69  eter to the sqli
1da60 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a  te3_set_authoriz
1da70 65 72 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20  er() interface. 
1da80 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
1da90 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  meter.** to the 
1daa0 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69  callback is an i
1dab0 6e 74 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43  nteger [SQLITE_C
1dac0 4f 50 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64  OPY | action cod
1dad0 65 5d 20 74 68 61 74 20 73 70 65 63 69 66 69 65  e] that specifie
1dae0 73 0a 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75  s.** the particu
1daf0 6c 61 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65  lar action to be
1db00 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68   authorized. ^Th
1db10 65 20 74 68 69 72 64 20 74 68 72 6f 75 67 68 20  e third through 
1db20 73 69 78 74 68 20 70 61 72 61 6d 65 74 65 72 73  sixth parameters
1db30 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  .** to the callb
1db40 61 63 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72  ack are zero-ter
1db50 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20  minated strings 
1db60 74 68 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64  that contain add
1db70 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69  itional.** detai
1db80 6c 73 20 61 62 6f 75 74 20 74 68 65 20 61 63 74  ls about the act
1db90 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72  ion to be author
1dba0 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ized..**.** ^If 
1dbb0 74 68 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20  the action code 
1dbc0 69 73 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d  is [SQLITE_READ]
1dbd0 0a 2a 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c  .** and the call
1dbe0 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51  back returns [SQ
1dbf0 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65  LITE_IGNORE] the
1dc00 6e 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  n the.** [prepar
1dc10 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74  ed statement] st
1dc20 61 74 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74  atement is const
1dc30 72 75 63 74 65 64 20 74 6f 20 73 75 62 73 74 69  ructed to substi
1dc40 74 75 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76  tute.** a NULL v
1dc50 61 6c 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66  alue in place of
1dc60 20 74 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d   the table colum
1dc70 6e 20 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76  n that would hav
1dc80 65 0a 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69  e.** been read i
1dc90 66 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61  f [SQLITE_OK] ha
1dca0 64 20 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e  d been returned.
1dcb0 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47    The [SQLITE_IG
1dcc0 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20  NORE].** return 
1dcd0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64  can be used to d
1dce0 65 6e 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64  eny an untrusted
1dcf0 20 75 73 65 72 20 61 63 63 65 73 73 20 74 6f 20   user access to 
1dd00 69 6e 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f  individual.** co
1dd10 6c 75 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65  lumns of a table
1dd20 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74  ..** ^If the act
1dd30 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c  ion code is [SQL
1dd40 49 54 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20  ITE_DELETE] and 
1dd50 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  the callback ret
1dd60 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  urns.** [SQLITE_
1dd70 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65  IGNORE] then the
1dd80 20 5b 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74   [DELETE] operat
1dd90 69 6f 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74  ion proceeds but
1dda0 20 74 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74   the.** [truncat
1ddb0 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20  e optimization] 
1ddc0 69 73 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20  is disabled and 
1ddd0 61 6c 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c  all rows are del
1dde0 65 74 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c  eted individuall
1ddf0 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68  y..**.** An auth
1de00 6f 72 69 7a 65 72 20 69 73 20 75 73 65 64 20 77  orizer is used w
1de10 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hen [sqlite3_pre
1de20 70 61 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67  pare | preparing
1de30 5d 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  ].** SQL stateme
1de40 6e 74 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72  nts from an untr
1de50 75 73 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f  usted source, to
1de60 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1de70 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a   SQL statements.
1de80 2a 2a 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f  ** do not try to
1de90 20 61 63 63 65 73 73 20 64 61 74 61 20 74 68 65   access data the
1dea0 79 20 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65  y are not allowe
1deb0 64 20 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61  d to see, or tha
1dec0 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a  t they do not.**
1ded0 20 74 72 79 20 74 6f 20 65 78 65 63 75 74 65 20   try to execute 
1dee0 6d 61 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d  malicious statem
1def0 65 6e 74 73 20 74 68 61 74 20 64 61 6d 61 67 65  ents that damage
1df00 20 74 68 65 20 64 61 74 61 62 61 73 65 2e 20 20   the database.  
1df10 46 6f 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20  For.** example, 
1df20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  an application m
1df30 61 79 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20  ay allow a user 
1df40 74 6f 20 65 6e 74 65 72 20 61 72 62 69 74 72 61  to enter arbitra
1df50 72 79 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65  ry.** SQL querie
1df60 73 20 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e  s for evaluation
1df70 20 62 79 20 61 20 64 61 74 61 62 61 73 65 2e 20   by a database. 
1df80 20 42 75 74 20 74 68 65 20 61 70 70 6c 69 63 61   But the applica
1df90 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74  tion does.** not
1dfa0 20 77 61 6e 74 20 74 68 65 20 75 73 65 72 20 74   want the user t
1dfb0 6f 20 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b  o be able to mak
1dfc0 65 20 61 72 62 69 74 72 61 72 79 20 63 68 61 6e  e arbitrary chan
1dfd0 67 65 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61  ges to the.** da
1dfe0 74 61 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68  tabase.  An auth
1dff0 6f 72 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65  orizer could the
1e000 6e 20 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63  n be put in plac
1e010 65 20 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75  e while the.** u
1e020 73 65 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20  ser-entered SQL 
1e030 69 73 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65  is being [sqlite
1e040 33 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70  3_prepare | prep
1e050 61 72 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69  ared] that.** di
1e060 73 61 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69  sallows everythi
1e070 6e 67 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43  ng except [SELEC
1e080 54 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  T] statements..*
1e090 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  *.** Application
1e0a0 73 20 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70  s that need to p
1e0b0 72 6f 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20  rocess SQL from 
1e0c0 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1e0d0 73 0a 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20  s.** might also 
1e0e0 63 6f 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e  consider lowerin
1e0f0 67 20 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74  g resource limit
1e100 73 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  s using [sqlite3
1e110 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64  _limit()].** and
1e120 20 6c 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61   limiting databa
1e130 73 65 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68  se size using th
1e140 65 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e  e [max_page_coun
1e150 74 5d 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69  t] [PRAGMA].** i
1e160 6e 20 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73  n addition to us
1e170 69 6e 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65  ing an authorize
1e180 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20  r..**.** ^(Only 
1e190 61 20 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69  a single authori
1e1a0 7a 65 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c  zer can be in pl
1e1b0 61 63 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73  ace on a databas
1e1c0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
1e1d0 61 74 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68  at a time.  Each
1e1e0 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
1e1f0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20  _set_authorizer 
1e200 6f 76 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a  overrides the.**
1e210 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29   previous call.)
1e220 5e 20 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20  ^  ^Disable the 
1e230 61 75 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e  authorizer by in
1e240 73 74 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20  stalling a NULL 
1e250 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65  callback..** The
1e260 20 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64   authorizer is d
1e270 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61 75  isabled by defau
1e280 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75  lt..**.** The au
1e290 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1e2a0 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e  k must not do an
1e2b0 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c  ything that will
1e2c0 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64   modify.** the d
1e2d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1e2e0 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20  on that invoked 
1e2f0 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63  the authorizer c
1e300 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65  allback..** Note
1e310 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
1e320 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
1e330 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
1e340 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
1e350 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
1e360 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
1e370 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
1e380 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
1e390 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
1e3a0 20 5e 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f   ^When [sqlite3_
1e3b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73  prepare_v2()] is
1e3c0 20 75 73 65 64 20 74 6f 20 70 72 65 70 61 72 65   used to prepare
1e3d0 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68   a statement, th
1e3e0 65 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d  e.** statement m
1e3f0 69 67 68 74 20 62 65 20 72 65 2d 70 72 65 70 61  ight be re-prepa
1e400 72 65 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69  red during [sqli
1e410 74 65 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20  te3_step()] due 
1e420 74 6f 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20  to a .** schema 
1e430 63 68 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20  change.  Hence, 
1e440 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
1e450 73 68 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68  should ensure th
1e460 61 74 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63  at the.** correc
1e470 74 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  t authorizer cal
1e480 6c 62 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e  lback remains in
1e490 20 70 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68   place during th
1e4a0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
1e4b0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20  )]..**.** ^Note 
1e4c0 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72 69  that the authori
1e4d0 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1e4e0 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72  invoked only dur
1e4f0 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  ing.** [sqlite3_
1e500 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74  prepare()] or it
1e510 73 20 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74  s variants.  Aut
1e520 68 6f 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f  horization is no
1e530 74 0a 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64  t.** performed d
1e540 75 72 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  uring statement 
1e550 65 76 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73  evaluation in [s
1e560 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
1e570 75 6e 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61  unless.** as sta
1e580 74 65 64 20 69 6e 20 74 68 65 20 70 72 65 76 69  ted in the previ
1e590 6f 75 73 20 70 61 72 61 67 72 61 70 68 2c 20 73  ous paragraph, s
1e5a0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
1e5b0 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33  vokes.** sqlite3
1e5c0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f  _prepare_v2() to
1e5d0 20 72 65 70 72 65 70 61 72 65 20 61 20 73 74 61   reprepare a sta
1e5e0 74 65 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73  tement after a s
1e5f0 63 68 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f  chema change..*/
1e600 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74  .int sqlite3_set
1e610 5f 61 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73  _authorizer(.  s
1e620 71 6c 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28  qlite3*,.  int (
1e630 2a 78 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e  *xAuth)(void*,in
1e640 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  t,const char*,co
1e650 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1e660 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72  char*,const char
1e670 2a 29 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65  *),.  void *pUse
1e680 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  rData.);../*.** 
1e690 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e6a0 69 7a 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65  izer Return Code
1e6b0 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e6c0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e6d0 7a 65 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72  zer | authorizer
1e6e0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1e6f0 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75  on] must.** retu
1e700 72 6e 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54  rn either [SQLIT
1e710 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  E_OK] or one of 
1e720 74 68 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61  these two consta
1e730 6e 74 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20  nts in order.** 
1e740 74 6f 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65  to signal SQLite
1e750 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e760 74 68 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65  the action is pe
1e770 72 6d 69 74 74 65 64 2e 20 20 53 65 65 20 74 68  rmitted.  See th
1e780 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65  e.** [sqlite3_se
1e790 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61  t_authorizer | a
1e7a0 75 74 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65  uthorizer docume
1e7b0 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64  ntation] for add
1e7c0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
1e7d0 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f  mation..**.** No
1e7e0 74 65 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49  te that SQLITE_I
1e7f0 47 4e 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73  GNORE is also us
1e800 65 64 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63  ed as a [conflic
1e810 74 20 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64  t resolution mod
1e820 65 5d 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66  e].** returned f
1e830 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1e840 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1e850 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1e860 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1e870 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1e880 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1e890 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1e8a0 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1e8b0 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1e8c0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1e8d0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1e8e0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1e8f0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1e900 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1e910 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1e920 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1e930 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1e940 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1e950 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1e960 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1e970 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1e980 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1e990 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1e9a0 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1e9b0 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1e9c0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1e9d0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1e9e0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1e9f0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1ea00 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1ea10 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1ea20 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1ea30 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1ea40 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1ea50 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1ea60 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1ea70 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1ea80 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1ea90 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1eaa0 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1eab0 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1eac0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1ead0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1eae0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1eaf0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1eb00 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1eb10 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1eb20 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1eb30 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1eb40 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1eb50 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1eb60 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1eb70 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1eb80 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1eb90 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1eba0 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1ebb0 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1ebc0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1ebd0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1ebe0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1ebf0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1ec00 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1ec10 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1ec20 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1ec30 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1ec40 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1ec50 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1ec60 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1ec70 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1ec80 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1ec90 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1eca0 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1ecb0 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1ecc0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ecd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1ece0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1ecf0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1ed00 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1ed10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1ed20 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1ed30 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1ed40 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1ed50 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1ed60 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1ed70 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1ed80 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1ed90 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1eda0 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1edb0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1edc0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1edd0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1ede0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1edf0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ee00 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ee10 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1ee20 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1ee30 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ee40 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ee50 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ee60 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1ee70 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1ee80 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1ee90 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1eea0 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1eeb0 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1eec0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1eed0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1eee0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1eef0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1ef00 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1ef10 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ef20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ef30 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ef40 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1ef50 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1ef60 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ef70 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ef80 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ef90 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1efa0 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1efb0 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1efc0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1efd0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1efe0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1eff0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1f000 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1f010 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f020 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f030 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1f040 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1f050 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1f060 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f070 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f080 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1f090 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1f0a0 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1f0b0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f0c0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f0d0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1f0e0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1f0f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1f100 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f110 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f120 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1f130 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1f140 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1f150 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1f160 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1f170 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1f180 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1f190 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1f1a0 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1f1b0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f1c0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1f1d0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1f1e0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1f1f0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1f200 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f210 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1f220 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1f230 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f240 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f250 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1f260 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1f270 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1f280 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1f290 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1f2a0 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1f2b0 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1f2c0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1f2d0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1f2e0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1f2f0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1f300 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1f310 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1f320 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1f330 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1f340 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1f350 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1f360 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f370 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f380 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1f390 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1f3a0 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1f3b0 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1f3c0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1f3d0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f3e0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1f3f0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1f400 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1f410 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1f420 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f430 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1f440 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1f450 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1f460 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f470 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f480 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1f490 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1f4a0 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1f4b0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1f4c0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f4d0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1f4e0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1f4f0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1f500 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1f510 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f520 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1f530 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1f540 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1f550 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f560 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f570 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1f580 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1f590 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1f5a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1f5b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f5c0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1f5d0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1f5e0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1f5f0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1f600 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f610 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1f620 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1f630 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1f640 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1f650 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1f660 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1f670 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1f680 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1f690 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1f6a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1f6b0 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1f6c0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1f6d0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1f6e0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1f6f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1f700 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1f710 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1f720 67 65 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66  ger used */.#def
1f730 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52  ine SQLITE_RECUR
1f740 53 49 56 45 20 20 20 20 20 20 20 20 20 20 20 20  SIVE            
1f750 33 33 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20  33   /* NULL    
1f760 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20          NULL    
1f770 20 20 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a          */../*.*
1f780 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61 63  * CAPI3REF: Trac
1f790 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e  ing And Profilin
1f7a0 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  g Functions.**.*
1f7b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
1f7c0 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61   register callba
1f7d0 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61  ck functions tha
1f7e0 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f  t can be used fo
1f7f0 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64  r.** tracing and
1f800 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65   profiling the e
1f810 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20  xecution of SQL 
1f820 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
1f830 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20  * ^The callback 
1f840 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65  function registe
1f850 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74  red by sqlite3_t
1f860 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  race() is invoke
1f870 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20  d at.** various 
1f880 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51  times when an SQ
1f890 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62  L statement is b
1f8a0 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c  eing run by [sql
1f8b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1f8c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72   ^The sqlite3_tr
1f8d0 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69  ace() callback i
1f8e0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
1f8f0 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67   UTF-8 rendering
1f900 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73   of the.** SQL s
1f910 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73  tatement text as
1f920 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66   the statement f
1f930 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65 63  irst begins exec
1f940 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69  uting..** ^(Addi
1f950 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74  tional sqlite3_t
1f960 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73  race() callbacks
1f970 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
1f980 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72 65  as each triggere
1f990 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20  d subprogram is 
1f9a0 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63 61  entered.  The ca
1f9b0 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67  llbacks for trig
1f9c0 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20  gers.** contain 
1f9d0 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d  a UTF-8 SQL comm
1f9e0 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69 66  ent that identif
1f9f0 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72 2e  ies the trigger.
1fa00 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  )^.**.** The [SQ
1fa10 4c 49 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f  LITE_TRACE_SIZE_
1fa20 4c 49 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  LIMIT] compile-t
1fa30 69 6d 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62  ime option can b
1fa40 65 20 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a  e used to limit.
1fa50 2a 2a 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66  ** the length of
1fa60 20 5b 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65   [bound paramete
1fa70 72 5d 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20  r] expansion in 
1fa80 74 68 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71  the output of sq
1fa90 6c 69 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a  lite3_trace()..*
1faa0 2a 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61  *.** ^The callba
1fab0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69  ck function regi
1fac0 73 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65  stered by sqlite
1fad0 33 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69  3_profile() is i
1fae0 6e 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63  nvoked.** as eac
1faf0 68 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  h SQL statement 
1fb00 66 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20  finishes.  ^The 
1fb10 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b  profile callback
1fb20 20 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65   contains.** the
1fb30 20 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d   original statem
1fb40 65 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20  ent text and an 
1fb50 65 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c  estimate of wall
1fb60 2d 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f  -clock time.** o
1fb70 66 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20  f how long that 
1fb80 73 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74  statement took t
1fb90 6f 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f  o run.  ^The pro
1fba0 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a  file callback.**
1fbb0 20 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74   time is in unit
1fbc0 73 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73  s of nanoseconds
1fbd0 2c 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75  , however the cu
1fbe0 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
1fbf0 74 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20  tion.** is only 
1fc00 63 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69  capable of milli
1fc10 73 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f  second resolutio
1fc20 6e 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61  n so the six lea
1fc30 73 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a  st significant.*
1fc40 2a 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20  * digits in the 
1fc50 74 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67  time are meaning
1fc60 6c 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65  less.  Future ve
1fc70 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1fc80 0a 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64  .** might provid
1fc90 65 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75  e greater resolu
1fca0 74 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66  tion on the prof
1fcb0 69 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20  iler callback.  
1fcc0 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  The.** sqlite3_p
1fcd0 72 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f  rofile() functio
1fce0 6e 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  n is considered 
1fcf0 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64  experimental and
1fd00 20 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74   is.** subject t
1fd10 6f 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75  o change in futu
1fd20 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1fd30 51 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  QLite..*/.void *
1fd40 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71  sqlite3_trace(sq
1fd50 6c 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54  lite3*, void(*xT
1fd60 72 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73  race)(void*,cons
1fd70 74 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29  t char*), void*)
1fd80 3b 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d  ;.SQLITE_EXPERIM
1fd90 45 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69  ENTAL void *sqli
1fda0 74 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69  te3_profile(sqli
1fdb0 74 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78  te3*,.   void(*x
1fdc0 50 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63  Profile)(void*,c
1fdd0 6f 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74  onst char*,sqlit
1fde0 65 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64  e3_uint64), void
1fdf0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1fe00 52 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72  REF: Query Progr
1fe10 65 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a  ess Callbacks.**
1fe20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1fe30 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65  _progress_handle
1fe40 72 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72  r(D,N,X,P) inter
1fe50 66 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20  face causes the 
1fe60 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
1fe70 74 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76  tion X to be inv
1fe80 6f 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c  oked periodicall
1fe90 79 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75  y during long ru
1fea0 6e 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a  nning calls to.*
1feb0 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  * [sqlite3_exec(
1fec0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  )], [sqlite3_ste
1fed0 70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  p()] and [sqlite
1fee0 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66  3_get_table()] f
1fef0 6f 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  or.** database c
1ff00 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e  onnection D.  An
1ff10 20 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72   example use for
1ff20 20 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61   this.** interfa
1ff30 63 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20  ce is to keep a 
1ff40 47 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69  GUI updated duri
1ff50 6e 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79  ng a large query
1ff60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72  ..**.** ^The par
1ff70 61 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73  ameter P is pass
1ff80 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
1ff90 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
1ffa0 20 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c   to the .** call
1ffb0 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e  back function X.
1ffc0 20 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72    ^The parameter
1ffd0 20 4e 20 69 73 20 74 68 65 20 61 70 70 72 6f 78   N is the approx
1ffe0 69 6d 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20  imate number of 
1fff0 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63  .** [virtual mac
20000 68 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e  hine instruction
20010 73 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c  s] that are eval
20020 75 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75  uated between su
20030 63 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f  ccessive.** invo
20040 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63  cations of the c
20050 61 6c 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20  allback X.  ^If 
20060 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
20070 6e 65 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67  ne then the prog
20080 72 65 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20  ress.** handler 
20090 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
200a0 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c  ** ^Only a singl
200b0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
200c0 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65  er may be define
200d0 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65  d at one time pe
200e0 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  r.** [database c
200f0 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74  onnection]; sett
20100 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65  ing a new progre
20110 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65  ss handler cance
20120 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e  ls the.** old on
20130 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72  e.  ^Setting par
20140 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c  ameter X to NULL
20150 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70 72   disables the pr
20160 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a  ogress handler..
20170 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73  ** ^The progress
20180 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f   handler is also
20190 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65 74   disabled by set
201a0 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75  ting N to a valu
201b0 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31  e less.** than 1
201c0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
201d0 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63  progress callbac
201e0 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  k returns non-ze
201f0 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ro, the operatio
20200 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70  n is.** interrup
20210 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74 75  ted.  This featu
20220 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  re can be used t
20230 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a  o implement a.**
20240 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e   "Cancel" button
20250 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65   on a GUI progre
20260 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a  ss dialog box..*
20270 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73  *.** The progres
20280 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61  s handler callba
20290 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61  ck must not do a
202a0 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c  nything that wil
202b0 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20  l modify.** the 
202c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
202d0 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64  ion that invoked
202e0 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
202f0 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74  ndler..** Note t
20300 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
20310 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
20320 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
20330 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
20340 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
20350 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
20360 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
20370 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
20380 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76  ragraph..**.*/.v
20390 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  oid sqlite3_prog
203a0 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c  ress_handler(sql
203b0 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28  ite3*, int, int(
203c0 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a  *)(void*), void*
203d0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
203e0 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65  EF: Opening A Ne
203f0 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  w Database Conne
20400 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
20410 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e  se routines open
20420 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62   an SQLite datab
20430 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65 63  ase file as spec
20440 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a  ified by the .**
20450 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
20460 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d  nt. ^The filenam
20470 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e  e argument is in
20480 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54 46  terpreted as UTF
20490 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  -8 for.** sqlite
204a0 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c  3_open() and sql
204b0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61  ite3_open_v2() a
204c0 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  nd as UTF-16 in 
204d0 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a  the native byte.
204e0 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  ** order for sql
204f0 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e  ite3_open16(). ^
20500 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  (A [database con
20510 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20  nection] handle 
20520 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65  is usually.** re
20530 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c  turned in *ppDb,
20540 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f   even if an erro
20550 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f  r occurs.  The o
20560 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73  nly exception is
20570 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69   that.** if SQLi
20580 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
20590 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20  allocate memory 
205a0 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c  to hold the [sql
205b0 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a  ite3] object,.**
205c0 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20   a NULL will be 
205d0 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70  written into *pp
205e0 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20  Db instead of a 
205f0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
20600 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65  sqlite3].** obje
20610 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64  ct.)^ ^(If the d
20620 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20630 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65  d (and/or create
20640 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c  d) successfully,
20650 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45   then.** [SQLITE
20660 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64  _OK] is returned
20670 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20  .  Otherwise an 
20680 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
20690 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65  returned.)^ ^The
206a0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72  .** [sqlite3_err
206b0 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  msg()] or [sqlit
206c0 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72  e3_errmsg16()] r
206d0 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75  outines can be u
206e0 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a  sed to obtain.**
206f0 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67   an English lang
20700 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e  uage description
20710 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f   of the error fo
20720 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72  llowing a failur
20730 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  e of any.** of t
20740 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  he sqlite3_open(
20750 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  ) routines..**.*
20760 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65  * ^The default e
20770 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20  ncoding for the 
20780 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
20790 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c   UTF-8 if.** sql
207a0 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
207b0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
207c0 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a   is called and.*
207d0 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20  * UTF-16 in the 
207e0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
207f0 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  r if sqlite3_ope
20800 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a  n16() is used..*
20810 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20  *.** Whether or 
20820 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  not an error occ
20830 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f  urs when it is o
20840 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73  pened, resources
20850 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
20860 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
20870 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61  e connection] ha
20880 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72  ndle should be r
20890 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61  eleased by.** pa
208a0 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c  ssing it to [sql
208b0 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68  ite3_close()] wh
208c0 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67  en it is no long
208d0 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a  er required..**.
208e0 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  ** The sqlite3_o
208f0 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61  pen_v2() interfa
20900 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71  ce works like sq
20910 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20  lite3_open().** 
20920 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20 61  except that it a
20930 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69 74  ccepts two addit
20940 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73  ional parameters
20950 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
20960 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20  control.** over 
20970 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73 65  the new database
20980 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28   connection.  ^(
20990 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65  The flags parame
209a0 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ter to.** sqlite
209b0 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20  3_open_v2() can 
209c0 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74  take one of.** t
209d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
209e0 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f  ee values, optio
209f0 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
20a00 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c  ith the .** [SQL
20a10 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58  ITE_OPEN_NOMUTEX
20a20 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
20a30 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c  FULLMUTEX], [SQL
20a40 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
20a50 41 43 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54  ACHE],.** [SQLIT
20a60 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
20a70 43 48 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51  CHE], and/or [SQ
20a80 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
20a90 6c 61 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64  lags:)^.**.** <d
20aa0 6c 3e 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  l>.** ^(<dt>[SQL
20ab0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
20ac0 59 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  Y]</dt>.** <dd>T
20ad0 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
20ae0 70 65 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e  pened in read-on
20af0 6c 79 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65  ly mode.  If the
20b00 20 64 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e   database does n
20b10 6f 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78  ot.** already ex
20b20 69 73 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73  ist, an error is
20b30 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
20b40 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
20b50 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20b60 52 49 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  RITE]</dt>.** <d
20b70 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
20b80 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
20b90 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
20ba0 20 69 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72   if possible, or
20bb0 20 72 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79   reading.** only
20bc0 20 69 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   if the file is 
20bd0 77 72 69 74 65 20 70 72 6f 74 65 63 74 65 64 20  write protected 
20be0 62 79 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  by the operating
20bf0 20 73 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74   system.  In eit
20c00 68 65 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20  her.** case the 
20c10 64 61 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c  database must al
20c20 72 65 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68  ready exist, oth
20c30 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
20c40 69 73 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64  is returned.</dd
20c50 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e  >)^.**.** ^(<dt>
20c60 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20c70 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54  DWRITE] | [SQLIT
20c80 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f  E_OPEN_CREATE]</
20c90 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64  dt>.** <dd>The d
20ca0 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65  atabase is opene
20cb0 64 20 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e  d for reading an
20cc0 64 20 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69  d writing, and i
20cd0 73 20 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20  s created if.** 
20ce0 69 74 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65  it does not alre
20cf0 61 64 79 20 65 78 69 73 74 2e 20 54 68 69 73 20  ady exist. This 
20d00 69 73 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  is the behavior 
20d10 74 68 61 74 20 69 73 20 61 6c 77 61 79 73 20 75  that is always u
20d20 73 65 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  sed for.** sqlit
20d30 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20d40 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c  lite3_open16().<
20d50 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  /dd>)^.** </dl>.
20d60 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64  **.** If the 3rd
20d70 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
20d80 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20d90 69 73 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68  is not one of th
20da0 65 0a 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  e.** combination
20db0 73 20 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70  s shown above op
20dc0 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65  tionally combine
20dd0 64 20 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20  d with other.** 
20de0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41  [SQLITE_OPEN_REA
20df0 44 4f 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f  DONLY | SQLITE_O
20e00 50 45 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74  PEN_* bits].** t
20e10 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
20e20 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
20e30 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51  *.** ^If the [SQ
20e40 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
20e50 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20  X] flag is set, 
20e60 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20e70 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
20e80 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c  opens in the mul
20e90 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61  ti-thread [threa
20ea0 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f  ding mode] as lo
20eb0 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65  ng as the single
20ec0 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20  -thread.** mode 
20ed0 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74  has not been set
20ee0 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65   at compile-time
20ef0 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20   or start-time. 
20f00 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c   ^If the.** [SQL
20f10 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54  ITE_OPEN_FULLMUT
20f20 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20  EX] flag is set 
20f30 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
20f40 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65  e connection ope
20f50 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72  ns.** in the ser
20f60 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69  ialized [threadi
20f70 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20  ng mode] unless 
20f80 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61  single-thread wa
20f90 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  s.** previously 
20fa0 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70  selected at comp
20fb0 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72  ile-time or star
20fc0 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  t-time..** ^The 
20fd0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41  [SQLITE_OPEN_SHA
20fe0 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63  REDCACHE] flag c
20ff0 61 75 73 65 73 20 74 68 65 20 64 61 74 61 62 61  auses the databa
21000 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  se connection to
21010 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20   be.** eligible 
21020 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64 20 63  to use [shared c
21030 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61  ache mode], rega
21040 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65  rdless of whethe
21050 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a  r or not shared.
21060 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e 61 62  ** cache is enab
21070 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  led using [sqlit
21080 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64  e3_enable_shared
21090 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65  _cache()].  ^The
210a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  .** [SQLITE_OPEN
210b0 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d 20 66  _PRIVATECACHE] f
210c0 6c 61 67 20 63 61 75 73 65 73 20 74 68 65 20 64  lag causes the d
210d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
210e0 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72  on to not.** par
210f0 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61  ticipate in [sha
21100 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20  red cache mode] 
21110 65 76 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e  even if it is en
21120 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
21130 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
21140 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70  er to sqlite3_op
21150 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e  en_v2() is the n
21160 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  ame of the.** [s
21170 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
21180 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
21190 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
211a0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
211b0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64  hat.** the new d
211c0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
211d0 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20  on should use.  
211e0 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
211f0 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61  arameter is.** a
21200 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68   NULL pointer th
21210 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b  en the default [
21220 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a  sqlite3_vfs] obj
21230 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ect is used..**.
21240 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e  ** ^If the filen
21250 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a  ame is ":memory:
21260 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74  ", then a privat
21270 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d  e, temporary in-
21280 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a  memory database.
21290 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20 66 6f  ** is created fo
212a0 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  r the connection
212b0 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f  .  ^This in-memo
212c0 72 79 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  ry database will
212d0 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20   vanish when.** 
212e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
212f0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
21300 64 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69  d.  Future versi
21310 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69  ons of SQLite mi
21320 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20  ght.** make use 
21330 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70  of additional sp
21340 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20  ecial filenames 
21350 74 68 61 74 20 62 65 67 69 6e 20 77 69 74 68 20  that begin with 
21360 74 68 65 20 22 3a 22 20 63 68 61 72 61 63 74 65  the ":" characte
21370 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f  r..** It is reco
21380 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77 68 65  mmended that whe
21390 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c  n a database fil
213a0 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64  ename actually d
213b0 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a  oes begin with.*
213c0 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63 74 65  * a ":" characte
213d0 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65  r you should pre
213e0 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  fix the filename
213f0 20 77 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65   with a pathname
21400 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22   such as.** "./"
21410 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75   to avoid ambigu
21420 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ity..**.** ^If t
21430 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61  he filename is a
21440 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20  n empty string, 
21450 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
21460 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d  temporary.** on-
21470 64 69 73 6b 20 64 61 74 61 62 61 73 65 20 77 69  disk database wi
21480 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e 20 20  ll be created.  
21490 5e 54 68 69 73 20 70 72 69 76 61 74 65 20 64 61  ^This private da
214a0 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a  tabase will be.*
214b0 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20  * automatically 
214c0 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20  deleted as soon 
214d0 61 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  as the database 
214e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c  connection is cl
214f0 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  osed..**.** [[UR
21500 49 20 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73  I filenames in s
21510 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20  qlite3_open()]] 
21520 3c 68 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65  <h3>URI Filename
21530 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66  s</h3>.**.** ^If
21540 20 5b 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20   [URI filename] 
21550 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
21560 73 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74  s enabled, and t
21570 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
21580 6d 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77  ment.** begins w
21590 69 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65  ith "file:", the
215a0 6e 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69  n the filename i
215b0 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
215c0 20 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20   a URI. ^URI.** 
215d0 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72  filename interpr
215e0 65 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c  etation is enabl
215f0 65 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ed if the [SQLIT
21600 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
21610 20 69 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68   is.** set in th
21620 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
21630 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
21640 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
21650 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
21660 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
21670 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
21680 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
21690 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
216a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
216b0 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
216c0 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
216d0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
216e0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
216f0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
21700 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
21710 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
21720 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
21730 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
21740 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
21750 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
21760 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
21770 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
21780 72 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65  rpretation by de
21790 66 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52  fault.  See "[UR
217a0 49 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f  I filenames]" fo
217b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
217c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
217d0 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
217e0 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
217f0 72 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38  rding to RFC 398
21800 36 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63  6. ^If the URI c
21810 6f 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75  ontains an.** au
21820 74 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74  thority, then it
21830 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20   must be either 
21840 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
21850 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a  or the string .*
21860 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e  * "localhost". ^
21870 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79  If the authority
21880 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79   is not an empty
21890 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61   string or "loca
218a0 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65  lhost", an .** e
218b0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
218c0 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20   to the caller. 
218d0 5e 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f  ^The fragment co
218e0 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49  mponent of a URI
218f0 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74  , if .** present
21900 2c 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a  , is ignored..**
21910 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73  .** ^SQLite uses
21920 20 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e   the path compon
21930 65 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61  ent of the URI a
21940 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
21950 65 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77  e disk file.** w
21960 68 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68  hich contains th
21970 65 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20  e database. ^If 
21980 74 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20  the path begins 
21990 77 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61  with a '/' chara
219a0 63 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69  cter, .** then i
219b0 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
219c0 20 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20   as an absolute 
219d0 70 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61  path. ^If the pa
219e0 74 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69  th does not begi
219f0 6e 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27  n .** with a '/'
21a00 20 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74   (meaning that t
21a10 68 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63  he authority sec
21a20 74 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20  tion is omitted 
21a30 66 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a  from the URI).**
21a40 20 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69   then the path i
21a50 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  s interpreted as
21a60 20 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68   a relative path
21a70 2e 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77  . .** ^On window
21a80 73 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d  s, the first com
21a90 70 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73  ponent of an abs
21aa0 6f 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69  olute path .** i
21ab0 73 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66  s a drive specif
21ac0 69 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43  ication (e.g. "C
21ad0 3a 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72  :")..**.** [[cor
21ae0 65 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61  e URI query para
21af0 6d 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20  meters]].** The 
21b00 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20  query component 
21b10 6f 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e  of a URI may con
21b20 74 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20  tain parameters 
21b30 74 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72  that are interpr
21b40 65 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62  eted.** either b
21b50 79 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c  y SQLite itself,
21b60 20 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20   or by a [VFS | 
21b70 63 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65  custom VFS imple
21b80 6d 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53  mentation]..** S
21b90 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73  QLite interprets
21ba0 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   the following t
21bb0 68 72 65 65 20 71 75 65 72 79 20 70 61 72 61 6d  hree query param
21bc0 65 74 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  eters:.**.** <ul
21bd0 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76  >.**   <li> <b>v
21be0 66 73 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66  fs</b>: ^The "vf
21bf0 73 22 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  s" parameter may
21c00 20 62 65 20 75 73 65 64 20 74 6f 20 73 70 65 63   be used to spec
21c10 69 66 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a  ify the name of.
21c20 2a 2a 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a  **     a VFS obj
21c30 65 63 74 20 74 68 61 74 20 70 72 6f 76 69 64 65  ect that provide
21c40 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
21c50 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
21c60 20 74 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20   that should.** 
21c70 20 20 20 20 62 65 20 75 73 65 64 20 74 6f 20 61      be used to a
21c80 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62 61  ccess the databa
21c90 73 65 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e  se file on disk.
21ca0 20 5e 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e   ^If this option
21cb0 20 69 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20   is set to.**   
21cc0 20 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e    an empty strin
21cd0 67 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  g the default VF
21ce0 53 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64  S object is used
21cf0 2e 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e  . ^Specifying an
21d00 20 75 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20   unknown.**     
21d10 56 46 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e  VFS is an error.
21d20 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65   ^If sqlite3_ope
21d30 6e 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61  n_v2() is used a
21d40 6e 64 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f  nd the vfs optio
21d50 6e 20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73  n is.**     pres
21d60 65 6e 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46  ent, then the VF
21d70 53 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  S specified by t
21d80 68 65 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  he option takes 
21d90 70 72 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a  precedence over.
21da0 2a 2a 20 20 20 20 20 74 68 65 20 76 61 6c 75 65  **     the value
21db0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 66   passed as the f
21dc0 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
21dd0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
21de0 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c  v2()..**.**   <l
21df0 69 3e 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20  i> <b>mode</b>: 
21e00 5e 28 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d  ^(The mode param
21e10 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
21e20 74 6f 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20  to either "ro", 
21e30 22 72 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77  "rw",.**     "rw
21e40 63 22 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e  c", or "memory".
21e50 20 41 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73   Attempting to s
21e60 65 74 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68  et it to any oth
21e70 65 72 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20  er value is.**  
21e80 20 20 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a     an error)^. .
21e90 2a 2a 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20  **     ^If "ro" 
21ea0 69 73 20 73 70 65 63 69 66 69 65 64 2c 20 74 68  is specified, th
21eb0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21ec0 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21ed0 61 64 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20  ad-only .**     
21ee0 61 63 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20  access, just as 
21ef0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
21f00 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c  PEN_READONLY] fl
21f10 61 67 20 68 61 64 20 62 65 65 6e 20 73 65 74 20  ag had been set 
21f20 69 6e 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74  in the .**     t
21f30 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
21f40 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21f50 28 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65  (). ^If the mode
21f60 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
21f70 6f 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20  o .**     "rw", 
21f80 74 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  then the databas
21f90 65 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20  e is opened for 
21fa0 72 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20  read-write (but 
21fb0 6e 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20  not create) .** 
21fc0 20 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69      access, as i
21fd0 66 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45  f SQLITE_OPEN_RE
21fe0 41 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74  ADWRITE (but not
21ff0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45   SQLITE_OPEN_CRE
22000 41 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20  ATE) had .**    
22010 20 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75   been set. ^Valu
22020 65 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76  e "rwc" is equiv
22030 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
22040 20 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51   both .**     SQ
22050 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
22060 49 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f  ITE and SQLITE_O
22070 50 45 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66  PEN_CREATE.  ^If
22080 20 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e   the mode option
22090 20 69 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74   is.**     set t
220a0 6f 20 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20  o "memory" then 
220b0 61 20 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72  a pure [in-memor
220c0 79 20 64 61 74 61 62 61 73 65 5d 20 74 68 61 74  y database] that
220d0 20 6e 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20   never reads.** 
220e0 20 20 20 20 6f 72 20 77 72 69 74 65 73 20 66 72      or writes fr
220f0 6f 6d 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e  om disk is used.
22100 20 5e 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72   ^It is an error
22110 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
22120 6c 75 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74  lue for.**     t
22130 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65  he mode paramete
22140 72 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 72  r that is less r
22150 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e 20  estrictive than 
22160 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20 62  that specified b
22170 79 0a 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61  y.**     the fla
22180 67 73 20 70 61 73 73 65 64 20 69 6e 20 74 68 65  gs passed in the
22190 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
221a0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
221b0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c  _v2()..**.**   <
221c0 6c 69 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e  li> <b>cache</b>
221d0 3a 20 5e 54 68 65 20 63 61 63 68 65 20 70 61 72  : ^The cache par
221e0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 73 65  ameter may be se
221f0 74 20 74 6f 20 65 69 74 68 65 72 20 22 73 68 61  t to either "sha
22200 72 65 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22  red" or.**     "
22210 70 72 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69  private". ^Setti
22220 6e 67 20 69 74 20 74 6f 20 22 73 68 61 72 65 64  ng it to "shared
22230 22 20 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20  " is equivalent 
22240 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a  to setting the.*
22250 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
22260 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 62 69  N_SHAREDCACHE bi
22270 74 20 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61  t in the flags a
22280 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74  rgument passed t
22290 6f 0a 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33  o.**     sqlite3
222a0 5f 6f 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74  _open_v2(). ^Set
222b0 74 69 6e 67 20 74 68 65 20 63 61 63 68 65 20 70  ting the cache p
222c0 61 72 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69  arameter to "pri
222d0 76 61 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20  vate" is .**    
222e0 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73   equivalent to s
222f0 65 74 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54  etting the SQLIT
22300 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
22310 43 48 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20  CHE bit..**     
22320 5e 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ^If sqlite3_open
22330 5f 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e  _v2() is used an
22340 64 20 74 68 65 20 22 63 61 63 68 65 22 20 70 61  d the "cache" pa
22350 72 61 6d 65 74 65 72 20 69 73 20 70 72 65 73 65  rameter is prese
22360 6e 74 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55  nt in.**     a U
22370 52 49 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73  RI filename, its
22380 20 76 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73   value overrides
22390 20 61 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65   any behavior re
223a0 71 75 65 73 74 65 64 20 62 79 20 73 65 74 74 69  quested by setti
223b0 6e 67 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45  ng.**     SQLITE
223c0 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
223d0 48 45 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45  HE or SQLITE_OPE
223e0 4e 5f 53 48 41 52 45 44 43 41 43 48 45 20 66 6c  N_SHAREDCACHE fl
223f0 61 67 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20  ag..**.**  <li> 
22400 3c 62 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68  <b>psow</b>: ^Th
22410 65 20 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72  e psow parameter
22420 20 6d 61 79 20 62 65 20 22 74 72 75 65 22 20 28   may be "true" (
22430 6f 72 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22  or "on" or "yes"
22440 20 6f 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20   or.**     "1") 
22450 6f 72 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22  or "false" (or "
22460 6f 66 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20  off" or "no" or 
22470 22 30 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65  "0") to indicate
22480 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20   that the.**    
22490 20 5b 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72   [powersafe over
224a0 77 72 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20  write] property 
224b0 64 6f 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74  does or does not
224c0 20 61 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a   apply to the.**
224d0 20 20 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64       storage med
224e0 69 61 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20  ia on which the 
224f0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 72 65  database file re
22500 73 69 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f  sides.  ^The pso
22510 77 20 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70  w query.**     p
22520 61 72 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f  arameter only wo
22530 72 6b 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c  rks for the buil
22540 74 2d 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69  t-in unix and Wi
22550 6e 64 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a  ndows VFSes..**.
22560 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f  **  <li> <b>nolo
22570 63 6b 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c  ck</b>: ^The nol
22580 6f 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73  ock parameter is
22590 20 61 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79   a boolean query
225a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20   parameter.**   
225b0 20 20 77 68 69 63 68 20 69 66 20 73 65 74 20 64    which if set d
225c0 69 73 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63  isables file loc
225d0 6b 69 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b  king in rollback
225e0 20 6a 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20   journal modes. 
225f0 20 54 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20   This.**     is 
22600 75 73 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73  useful for acces
22610 73 69 6e 67 20 61 20 64 61 74 61 62 61 73 65 20  sing a database 
22620 6f 6e 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20  on a filesystem 
22630 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a  that does not.**
22640 20 20 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63       support loc
22650 6b 69 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20  king.  Caution: 
22660 20 44 61 74 61 62 61 73 65 20 63 6f 72 72 75 70   Database corrup
22670 74 69 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c  tion might resul
22680 74 20 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20  t if two.**     
22690 6f 72 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65  or more processe
226a0 73 20 77 72 69 74 65 20 74 6f 20 74 68 65 20 73  s write to the s
226b0 61 6d 65 20 64 61 74 61 62 61 73 65 20 61 6e 64  ame database and
226c0 20 61 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73   any one of thos
226d0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73  e.**     process
226e0 65 73 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31  es uses nolock=1
226f0 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
22700 3e 69 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20  >immutable</b>: 
22710 5e 54 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70  ^The immutable p
22720 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f  arameter is a bo
22730 6f 6c 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20  olean query.**  
22740 20 20 20 70 61 72 61 6d 65 74 65 72 20 74 68 61     parameter tha
22750 74 20 69 6e 64 69 63 61 74 65 73 20 74 68 61 74  t indicates that
22760 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
22770 6c 65 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a  le is stored on.
22780 2a 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79  **     read-only
22790 20 6d 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69   media.  ^When i
227a0 6d 6d 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c  mmutable is set,
227b0 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
227c0 74 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20  that the.**     
227d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 63 61  database file ca
227e0 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c  nnot be changed,
227f0 20 65 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65   even by a proce
22800 73 73 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a  ss with higher.*
22810 2a 20 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c  *     privilege,
22820 20 61 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61   and so the data
22830 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72  base is opened r
22840 65 61 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c  ead-only and all
22850 20 6c 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20   locking.**     
22860 61 6e 64 20 63 68 61 6e 67 65 20 64 65 74 65 63  and change detec
22870 74 69 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64  tion is disabled
22880 2e 20 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74  .  Caution: Sett
22890 69 6e 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c  ing the immutabl
228a0 65 0a 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74  e.**     propert
228b0 79 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  y on a database 
228c0 66 69 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69  file that does i
228d0 6e 20 66 61 63 74 20 63 68 61 6e 67 65 20 63 61  n fact change ca
228e0 6e 20 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20  n result.**     
228f0 69 6e 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65  in incorrect que
22900 72 79 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f  ry results and/o
22910 72 20 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50  r [SQLITE_CORRUP
22920 54 5d 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20  T] errors..**   
22930 20 20 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c    See also: [SQL
22940 49 54 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41  ITE_IOCAP_IMMUTA
22950 42 4c 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a  BLE]..**       .
22960 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
22970 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
22980 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
22990 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
229a0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
229b0 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
229c0 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
229d0 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
229e0 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
229f0 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
22a00 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
22a10 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
22a20 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
22a30 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
22a40 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
22a50 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
22a60 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
22a70 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
22a80 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
22a90 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
22aa0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
22ab0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
22ac0 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
22ad0 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
22ae0 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
22af0 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
22b00 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
22b10 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
22b20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
22b30 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
22b40 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
22b50 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
22b60 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22b70 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
22b80 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
22b90 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
22ba0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
22bb0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
22bc0 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
22bd0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22be0 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
22bf0 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
22c00 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
22c10 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
22c20 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
22c30 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
22c40 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
22c50 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
22c60 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
22c70 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
22c80 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
22c90 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
22ca0 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
22cb0 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
22cc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
22cd0 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
22ce0 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
22cf0 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
22d00 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
22d10 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
22d20 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
22d30 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
22d40 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
22d50 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
22d60 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
22d70 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
22d80 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
22d90 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
22da0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
22db0 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
22dc0 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
22dd0 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
22de0 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
22df0 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
22e00 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
22e10 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
22e20 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
22e30 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
22e40 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
22e50 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
22e60 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
22e70 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
22e80 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
22e90 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
22ea0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
22eb0 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
22ec0 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
22ed0 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
22ee0 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
22ef0 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
22f00 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
22f10 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
22f20 69 78 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a  ix-dotfile <td>.
22f30 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
22f40 20 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65   file "/home/fre
22f50 64 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20  d/data.db". Use 
22f60 74 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20  the special VFS 
22f70 22 75 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a  "unix-dotfile".*
22f80 2a 20 20 20 20 20 20 20 20 20 20 74 68 61 74 20  *          that 
22f90 75 73 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69  uses dot-files i
22fa0 6e 20 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78  n place of posix
22fb0 20 61 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e   advisory lockin
22fc0 67 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66  g..** <tr><td> f
22fd0 69 6c 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65  ile:data.db?mode
22fe0 3d 72 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a  =readonly <td> .
22ff0 2a 2a 20 20 20 20 20 20 20 20 20 20 41 6e 20 65  **          An e
23000 72 72 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22  rror. "readonly"
23010 20 69 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20   is not a valid 
23020 6f 70 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22  option for the "
23030 6d 6f 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e  mode" parameter.
23040 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a  .** </table>.**.
23050 2a 2a 20 5e 55 52 49 20 68 65 78 61 64 65 63 69  ** ^URI hexadeci
23060 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
23070 6e 63 65 73 20 28 25 48 48 29 20 61 72 65 20 73  nces (%HH) are s
23080 75 70 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20  upported within 
23090 74 68 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20  the path and.** 
230a0 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73  query components
230b0 20 6f 66 20 61 20 55 52 49 2e 20 41 20 68 65 78   of a URI. A hex
230c0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
230d0 73 65 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74  sequence consist
230e0 73 20 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e  s of a.** percen
230f0 74 20 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66  t sign - "%" - f
23100 6f 6c 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74  ollowed by exact
23110 6c 79 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d  ly two hexadecim
23120 61 6c 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70  al digits .** sp
23130 65 63 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65  ecifying an octe
23140 74 20 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65  t value. ^Before
23150 20 74 68 65 20 70 61 74 68 20 6f 72 20 71 75 65   the path or que
23160 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66  ry components of
23170 20 61 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61   a.** URI filena
23180 6d 65 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  me are interpret
23190 65 64 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63  ed, they are enc
231a0 6f 64 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38  oded using UTF-8
231b0 20 61 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78   and all .** hex
231c0 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20  adecimal escape 
231d0 73 65 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63  sequences replac
231e0 65 64 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62  ed by a single b
231f0 79 74 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  yte containing t
23200 68 65 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64  he.** correspond
23210 69 6e 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68  ing octet. If th
23220 69 73 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72  is process gener
23230 61 74 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20  ates an invalid 
23240 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a  UTF-8 encoding,.
23250 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 73 20 61  ** the results a
23260 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  re undefined..**
23270 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57  .** <b>Note to W
23280 69 6e 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62  indows users:</b
23290 3e 20 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20  >  The encoding 
232a0 75 73 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c  used for the fil
232b0 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a  ename argument.*
232c0 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65  * of sqlite3_ope
232d0 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
232e0 6f 70 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62  open_v2() must b
232f0 65 20 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61  e UTF-8, not wha
23300 74 65 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67  tever.** codepag
23310 65 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64  e is currently d
23320 65 66 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d  efined.  Filenam
23330 65 73 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e  es containing in
23340 74 65 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63  ternational.** c
23350 68 61 72 61 63 74 65 72 73 20 6d 75 73 74 20 62  haracters must b
23360 65 20 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55  e converted to U
23370 54 46 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61  TF-8 prior to pa
23380 73 73 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a  ssing them into.
23390 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  ** sqlite3_open(
233a0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65  ) or sqlite3_ope
233b0 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62  n_v2()..**.** <b
233c0 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73  >Note to Windows
233d0 20 52 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c   Runtime users:<
233e0 2f 62 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61  /b>  The tempora
233f0 72 79 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73  ry directory mus
23400 74 20 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f  t be set.** prio
23410 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c  r to calling sql
23420 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73  ite3_open() or s
23430 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
23440 2e 20 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61  .  Otherwise, va
23450 72 69 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65  rious.** feature
23460 73 20 74 68 61 74 20 72 65 71 75 69 72 65 20 74  s that require t
23470 68 65 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72  he use of tempor
23480 61 72 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61  ary files may fa
23490 69 6c 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  il..**.** See al
234a0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d  so: [sqlite3_tem
234b0 70 5f 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a  p_directory].*/.
234c0 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  int sqlite3_open
234d0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
234e0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
234f0 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23500 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
23510 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20  lite3 **ppDb    
23520 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23530 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23540 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
23550 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74  _open16(.  const
23560 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c   void *filename,
23570 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66     /* Database f
23580 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29  ilename (UTF-16)
23590 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a   */.  sqlite3 **
235a0 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a  ppDb          /*
235b0 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20   OUT: SQLite db 
235c0 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74  handle */.);.int
235d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
235e0 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
235f0 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44  filename,   /* D
23600 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65  atabase filename
23610 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71   (UTF-8) */.  sq
23620 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20  lite3 **ppDb,   
23630 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51        /* OUT: SQ
23640 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a  Lite db handle *
23650 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20  /.  int flags,  
23660 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46              /* F
23670 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  lags */.  const 
23680 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20  char *zVfs      
23690 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53    /* Name of VFS
236a0 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a   module to use *
236b0 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  /.);../*.** CAPI
236c0 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c  3REF: Obtain Val
236d0 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72 61  ues For URI Para
236e0 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65  meters.**.** The
236f0 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20 72  se are utility r
23700 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20  outines, useful 
23710 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74  to VFS implement
23720 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65  ations, that che
23730 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20  ck.** to see if 
23740 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  a database file 
23750 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20 63  was a URI that c
23760 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63 69  ontained a speci
23770 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61  fic query .** pa
23780 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20  rameter, and if 
23790 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76  so obtains the v
237a0 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75 65  alue of that que
237b0 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  ry parameter..**
237c0 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65 20  .** If F is the 
237d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  database filenam
237e0 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64  e pointer passed
237f0 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28   into the xOpen(
23800 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20  ) method of .** 
23810 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  a VFS implementa
23820 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c  tion when the fl
23830 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ags parameter to
23840 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65   xOpen() has one
23850 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20   or .** more of 
23860 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
23870 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _URI] or [SQLITE
23880 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62  _OPEN_MAIN_DB] b
23890 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50  its set and.** P
238a0 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20   is the name of 
238b0 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d 65  the query parame
238c0 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c  ter, then.** sql
238d0 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74  ite3_uri_paramet
238e0 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20  er(F,P) returns 
238f0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
23900 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20   P.** parameter 
23910 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72 20  if it exists or 
23920 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69  a NULL pointer i
23930 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70  f P does not app
23940 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65  ear as a .** que
23950 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20  ry parameter on 
23960 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71 75  F.  If P is a qu
23970 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66  ery parameter of
23980 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70   F.** has no exp
23990 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65  licit value, the
239a0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61  n sqlite3_uri_pa
239b0 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74  rameter(F,P) ret
239c0 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65  urns.** a pointe
239d0 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74  r to an empty st
239e0 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ring..**.** The 
239f0 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c  sqlite3_uri_bool
23a00 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69  ean(F,P,B) routi
23a10 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ne assumes that 
23a20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a  P is a boolean.*
23a30 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20  * parameter and 
23a40 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31 29  returns true (1)
23a50 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61 63   or false (0) ac
23a60 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76  cording to the v
23a70 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54  alue.** of P.  T
23a80 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62  he sqlite3_uri_b
23a90 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f  oolean(F,P,B) ro
23aa0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72  utine returns tr
23ab0 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a  ue (1) if the.**
23ac0 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20   value of query 
23ad0 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f  parameter P is o
23ae0 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72  ne of "yes", "tr
23af0 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20  ue", or "on" in 
23b00 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69  any.** case or i
23b10 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67 69  f the value begi
23b20 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65  ns with a non-ze
23b30 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20  ro number.  The 
23b40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  .** sqlite3_uri_
23b50 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23b60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20  outines returns 
23b70 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68 65  false (0) if the
23b80 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65   value of.** que
23b90 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20 69  ry parameter P i
23ba0 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22  s one of "no", "
23bb0 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22  false", or "off"
23bc0 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a   in any case or.
23bd0 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  ** if the value 
23be0 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75  begins with a nu
23bf0 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20  meric zero.  If 
23c00 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79  P is not a query
23c10 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  .** parameter on
23c20 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c   F or if the val
23c30 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20  ue of P is does 
23c40 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66  not match any of
23c50 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74   the.** above, t
23c60 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  hen sqlite3_uri_
23c70 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
23c80 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a  eturns (B!=0)..*
23c90 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
23ca0 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44  _uri_int64(F,P,D
23cb0 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72  ) routine conver
23cc0 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  ts the value of 
23cd0 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62  P into a.** 64-b
23ce0 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
23cf0 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68  r and returns th
23d00 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44  at integer, or D
23d10 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a   if P does not.*
23d20 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68 65  * exist.  If the
23d30 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73   value of P is s
23d40 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74  omething other t
23d50 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20  han an integer, 
23d60 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20  then.** zero is 
23d70 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a  returned..** .**
23d80 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20   If F is a NULL 
23d90 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71  pointer, then sq
23da0 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
23db0 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
23dc0 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c   NULL and.** sql
23dd0 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e  ite3_uri_boolean
23de0 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20  (F,P,B) returns 
23df0 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20  B.  If F is not 
23e00 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61  a NULL pointer a
23e10 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64  nd.** is not a d
23e20 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61 74  atabase file pat
23e30 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68  hname pointer th
23e40 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65 64  at SQLite passed
23e50 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a   into the xOpen.
23e60 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74  ** VFS method, t
23e70 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
23e80 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65   of this routine
23e90 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
23ea0 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e  d probably.** un
23eb0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f  desirable..*/.co
23ec0 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
23ed0 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28  3_uri_parameter(
23ee0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c  const char *zFil
23ef0 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61  ename, const cha
23f00 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20  r *zParam);.int 
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 63 6f 6e 73 74 20 63 68 61 72 20 2a  ean(const char *
23f30 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61  zFile, const cha
23f40 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62  r *zParam, int b
23f50 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65  Default);.sqlite
23f60 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
23f70 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20  uri_int64(const 
23f80 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61  char*, const cha
23f90 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  r*, sqlite3_int6
23fa0 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  4);.../*.** CAPI
23fb0 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65  3REF: Error Code
23fc0 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a  s And Messages.*
23fd0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23fe0 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65  3_errcode() inte
23ff0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24000 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c  e numeric [resul
24010 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  t code] or.** [e
24020 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24030 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73  ode] for the mos
24040 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20  t recent failed 
24050 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61  sqlite3_* API ca
24060 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ll.** associated
24070 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61 73   with a [databas
24080 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49  e connection]. I
24090 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61  f a prior API ca
240a0 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74  ll failed.** but
240b0 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
240c0 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65   API call succee
240d0 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ded, the return 
240e0 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71  value from.** sq
240f0 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20  lite3_errcode() 
24100 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e  is undefined.  ^
24110 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65  The sqlite3_exte
24120 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a  nded_errcode().*
24130 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  * interface is t
24140 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20 74  he same except t
24150 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72 65  hat it always re
24160 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65  turns the .** [e
24170 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
24180 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65  ode] even when e
24190 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
241a0 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61  odes are.** disa
241b0 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bled..**.** ^The
241c0 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28   sqlite3_errmsg(
241d0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72  ) and sqlite3_er
241e0 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e 20  rmsg16() return 
241f0 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65  English-language
24200 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64 65  .** text that de
24210 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72 6f  scribes the erro
24220 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54 46  r, as either UTF
24230 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73  -8 or UTF-16 res
24240 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28  pectively..** ^(
24250 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  Memory to hold t
24260 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  he error message
24270 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67   string is manag
24280 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a  ed internally..*
24290 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
242a0 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  n does not need 
242b0 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66  to worry about f
242c0 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c  reeing the resul
242d0 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74  t..** However, t
242e0 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20  he error string 
242f0 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72 69  might be overwri
24300 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61  tten or dealloca
24310 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71  ted by.** subseq
24320 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74  uent calls to ot
24330 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
24340 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29  face functions.)
24350 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ^.**.** ^The sql
24360 69 74 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e  ite3_errstr() in
24370 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
24380 74 68 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67  the English-lang
24390 75 61 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61  uage text.** tha
243a0 74 20 64 65 73 63 72 69 62 65 73 20 74 68 65 20  t describes the 
243b0 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61  [result code], a
243c0 73 20 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65  s UTF-8..** ^(Me
243d0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
243e0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
243f0 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
24400 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61   internally.** a
24410 6e 64 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66  nd must not be f
24420 72 65 65 64 20 62 79 20 74 68 65 20 61 70 70 6c  reed by the appl
24430 69 63 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a  ication)^..**.**
24440 20 57 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c   When the serial
24450 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
24460 6d 6f 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c  mode] is in use,
24470 20 69 74 20 6d 69 67 68 74 20 62 65 20 74 68 65   it might be the
24480 0a 2a 2a 20 63 61 73 65 20 74 68 61 74 20 61 20  .** case that a 
24490 73 65 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63  second error occ
244a0 75 72 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74  urs on a separat
244b0 65 20 74 68 72 65 61 64 20 69 6e 20 62 65 74 77  e thread in betw
244c0 65 65 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20  een.** the time 
244d0 6f 66 20 74 68 65 20 66 69 72 73 74 20 65 72 72  of the first err
244e0 6f 72 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20  or and the call 
244f0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
24500 63 65 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61  ces..** When tha
24510 74 20 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73  t happens, the s
24520 65 63 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c  econd error will
24530 20 62 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e   be reported sin
24540 63 65 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65  ce these.** inte
24550 72 66 61 63 65 73 20 61 6c 77 61 79 73 20 72 65  rfaces always re
24560 70 6f 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65  port the most re
24570 63 65 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f  cent result.  To
24580 20 61 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20   avoid.** this, 
24590 65 61 63 68 20 74 68 72 65 61 64 20 63 61 6e 20  each thread can 
245a0 6f 62 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65  obtain exclusive
245b0 20 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74   use of the [dat
245c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
245d0 5d 20 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69  ] D.** by invoki
245e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
245f0 78 5f 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65  x_enter]([sqlite
24600 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
24610 62 65 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67  before beginning
24620 0a 2a 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64  .** to use D and
24630 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74   invoking [sqlit
24640 65 33 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28  e3_mutex_leave](
24650 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65  [sqlite3_db_mute
24660 78 5d 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20  x](D)) after.** 
24670 61 6c 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65  all calls to the
24680 20 69 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74   interfaces list
24690 65 64 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70  ed here are comp
246a0 6c 65 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  leted..**.** If 
246b0 61 6e 20 69 6e 74 65 72 66 61 63 65 20 66 61 69  an interface fai
246c0 6c 73 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d  ls with SQLITE_M
246d0 49 53 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e  ISUSE, that mean
246e0 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a  s the interface.
246f0 2a 2a 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69  ** was invoked i
24700 6e 63 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68  ncorrectly by th
24710 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
24720 49 6e 20 74 68 61 74 20 63 61 73 65 2c 20 74 68  In that case, th
24730 65 0a 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20  e.** error code 
24740 61 6e 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20  and message may 
24750 6f 72 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65  or may not be se
24760 74 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  t..*/.int sqlite
24770 33 5f 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65  3_errcode(sqlite
24780 33 20 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69  3 *db);.int sqli
24790 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72  te3_extended_err
247a0 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62  code(sqlite3 *db
247b0 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  );.const char *s
247c0 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71  qlite3_errmsg(sq
247d0 6c 69 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76  lite3*);.const v
247e0 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72  oid *sqlite3_err
247f0 6d 73 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b  msg16(sqlite3*);
24800 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24810 69 74 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29  ite3_errstr(int)
24820 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
24830 46 3a 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  F: SQL Statement
24840 20 4f 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f   Object.** KEYWO
24850 52 44 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73  RDS: {prepared s
24860 74 61 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61  tatement} {prepa
24870 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a  red statements}.
24880 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63  **.** An instanc
24890 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74  e of this object
248a0 20 72 65 70 72 65 73 65 6e 74 73 20 61 20 73 69   represents a si
248b0 6e 67 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65  ngle SQL stateme
248c0 6e 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  nt..** This obje
248d0 63 74 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20  ct is variously 
248e0 6b 6e 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70  known as a "prep
248f0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20  ared statement" 
24900 6f 72 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65  or a.** "compile
24910 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22  d SQL statement"
24920 20 6f 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20   or simply as a 
24930 22 73 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a  "statement"..**.
24940 2a 2a 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61  ** The life of a
24950 20 73 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63   statement objec
24960 74 20 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67  t goes something
24970 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a   like this:.**.*
24980 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43  * <ol>.** <li> C
24990 72 65 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74  reate the object
249a0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
249b0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
249c0 20 61 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20   a related.**   
249d0 20 20 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20     function..** 
249e0 3c 6c 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73  <li> Bind values
249f0 20 74 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65   to [host parame
24a00 74 65 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20  ters] using the 
24a10 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29  sqlite3_bind_*()
24a20 0a 2a 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61  .**      interfa
24a30 63 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e  ces..** <li> Run
24a40 20 74 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c   the SQL by call
24a50 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
24a60 70 28 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  p()] one or more
24a70 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20   times..** <li> 
24a80 52 65 73 65 74 20 74 68 65 20 73 74 61 74 65 6d  Reset the statem
24a90 65 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ent using [sqlit
24aa0 65 33 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e  e3_reset()] then
24ab0 20 67 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20   go back.**     
24ac0 20 74 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20   to step 2.  Do 
24ad0 74 68 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  this zero or mor
24ae0 65 20 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e  e times..** <li>
24af0 20 44 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a   Destroy the obj
24b00 65 63 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ect using [sqlit
24b10 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a  e3_finalize()]..
24b20 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52  ** </ol>.**.** R
24b30 65 66 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74  efer to document
24b40 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
24b50 75 61 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  ual methods abov
24b60 65 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  e for additional
24b70 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e  .** information.
24b80 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
24b90 63 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  ct sqlite3_stmt 
24ba0 73 71 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f  sqlite3_stmt;../
24bb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
24bc0 75 6e 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a  un-time Limits.*
24bd0 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65  *.** ^(This inte
24be0 72 66 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65  rface allows the
24bf0 20 73 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73   size of various
24c00 20 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62   constructs to b
24c10 65 20 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20  e limited.** on 
24c20 61 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20  a connection by 
24c30 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73  connection basis
24c40 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 61 72  .  The first par
24c50 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
24c60 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
24c70 63 74 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d  ction] whose lim
24c80 69 74 20 69 73 20 74 6f 20 62 65 20 73 65 74 20  it is to be set 
24c90 6f 72 20 71 75 65 72 69 65 64 2e 20 20 54 68 65  or queried.  The
24ca0 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
24cb0 65 74 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74  eter is one of t
24cc0 68 65 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f  he [limit catego
24cd0 72 69 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e  ries] that defin
24ce0 65 20 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20  e a.** class of 
24cf0 63 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65  constructs to be
24d00 20 73 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20   size limited.  
24d10 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
24d20 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65  ter is the.** ne
24d30 77 20 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74  w limit for that
24d40 20 63 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a   construct.)^.**
24d50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20  .** ^If the new 
24d60 6c 69 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74  limit is a negat
24d70 69 76 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20  ive number, the 
24d80 6c 69 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67  limit is unchang
24d90 65 64 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63  ed..** ^(For eac
24da0 68 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79  h limit category
24db0 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69   SQLITE_LIMIT_<i
24dc0 3e 4e 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20  >NAME</i> there 
24dd0 69 73 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73  is a .** [limits
24de0 20 7c 20 68 61 72 64 20 75 70 70 65 72 20 62 6f   | hard upper bo
24df0 75 6e 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63  und].** set at c
24e00 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61  ompile-time by a
24e10 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C preprocessor 
24e20 6d 61 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20  macro called.** 
24e30 5b 6c 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45  [limits | SQLITE
24e40 5f 4d 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  _MAX_<i>NAME</i>
24e50 5d 2e 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d  ]..** (The "_LIM
24e60 49 54 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65  IT_" in the name
24e70 20 69 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22   is changed to "
24e80 5f 4d 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41  _MAX_".))^.** ^A
24e90 74 74 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65  ttempts to incre
24ea0 61 73 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76  ase a limit abov
24eb0 65 20 69 74 73 20 68 61 72 64 20 75 70 70 65 72  e its hard upper
24ec0 20 62 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69   bound are.** si
24ed0 6c 65 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64  lently truncated
24ee0 20 74 6f 20 74 68 65 20 68 61 72 64 20 75 70 70   to the hard upp
24ef0 65 72 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20  er bound..**.** 
24f00 5e 52 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77  ^Regardless of w
24f10 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
24f20 65 20 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e  e limit was chan
24f30 67 65 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71  ged, the .** [sq
24f40 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69  lite3_limit()] i
24f50 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
24f60 20 74 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65   the prior value
24f70 20 6f 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a   of the limit..*
24f80 2a 20 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e  * ^Hence, to fin
24f90 64 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  d the current va
24fa0 6c 75 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77  lue of a limit w
24fb0 69 74 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20  ithout changing 
24fc0 69 74 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e  it,.** simply in
24fd0 76 6f 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66  voke this interf
24fe0 61 63 65 20 77 69 74 68 20 74 68 65 20 74 68 69  ace with the thi
24ff0 72 64 20 70 61 72 61 6d 65 74 65 72 20 73 65 74  rd parameter set
25000 20 74 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75   to -1..**.** Ru
25010 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72  n-time limits ar
25020 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
25030 73 65 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f  se in applicatio
25040 6e 73 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a  ns that manage.*
25050 2a 20 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e  * both their own
25060 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61   internal databa
25070 73 65 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61  se and also data
25080 62 61 73 65 73 20 74 68 61 74 20 61 72 65 20 63  bases that are c
25090 6f 6e 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20  ontrolled.** by 
250a0 75 6e 74 72 75 73 74 65 64 20 65 78 74 65 72 6e  untrusted extern
250b0 61 6c 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20  al sources.  An 
250c0 65 78 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74  example applicat
250d0 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a  ion might be a.*
250e0 2a 20 77 65 62 20 62 72 6f 77 73 65 72 20 74 68  * web browser th
250f0 61 74 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64  at has its own d
25100 61 74 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f  atabases for sto
25110 72 69 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64  ring history and
25120 0a 2a 2a 20 73 65 70 61 72 61 74 65 20 64 61 74  .** separate dat
25130 61 62 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65  abases controlle
25140 64 20 62 79 20 4a 61 76 61 53 63 72 69 70 74 20  d by JavaScript 
25150 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77  applications dow
25160 6e 6c 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74  nloaded.** off t
25170 68 65 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68  he Internet.  Th
25180 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62  e internal datab
25190 61 73 65 73 20 63 61 6e 20 62 65 20 67 69 76 65  ases can be give
251a0 6e 20 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20  n the.** large, 
251b0 64 65 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20  default limits. 
251c0 20 44 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67   Databases manag
251d0 65 64 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73  ed by external s
251e0 6f 75 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65  ources can.** be
251f0 20 67 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c   given much smal
25200 6c 65 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67  ler limits desig
25210 6e 65 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61  ned to prevent a
25220 20 64 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69   denial of servi
25230 63 65 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44  ce.** attack.  D
25240 65 76 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20  evelopers might 
25250 61 6c 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65  also want to use
25260 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65   the [sqlite3_se
25270 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a  t_authorizer()].
25280 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20  ** interface to 
25290 66 75 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20  further control 
252a0 75 6e 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20  untrusted SQL.  
252b0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
252c0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61  database.** crea
252d0 74 65 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73  ted by an untrus
252e0 74 65 64 20 73 63 72 69 70 74 20 63 61 6e 20 62  ted script can b
252f0 65 20 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e  e contained usin
25300 67 20 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61  g the.** [max_pa
25310 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d  ge_count] [PRAGM
25320 41 5d 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75  A]..**.** New ru
25330 6e 2d 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74  n-time limit cat
25340 65 67 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61  egories may be a
25350 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
25360 65 6c 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20  eleases..*/.int 
25370 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71  sqlite3_limit(sq
25380 6c 69 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20  lite3*, int id, 
25390 69 6e 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a  int newVal);../*
253a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75  .** CAPI3REF: Ru
253b0 6e 2d 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74  n-Time Limit Cat
253c0 65 67 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f  egories.** KEYWO
253d0 52 44 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65  RDS: {limit cate
253e0 67 6f 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61  gory} {*limit ca
253f0 74 65 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20  tegories}.**.** 
25400 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
25410 64 65 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70  define various p
25420 65 72 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74  erformance limit
25430 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65  s.** that can be
25440 20 6c 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d   lowered at run-
25450 74 69 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69  time using [sqli
25460 74 65 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a  te3_limit()]..**
25470 20 54 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66   The synopsis of
25480 20 74 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66   the meanings of
25490 20 74 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d   the various lim
254a0 69 74 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c  its is shown bel
254b0 6f 77 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61  ow..** Additiona
254c0 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  l information is
254d0 20 61 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c   available at [l
254e0 69 6d 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69  imits | Limits i
254f0 6e 20 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a  n SQLite]..**.**
25500 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54   <dl>.** [[SQLIT
25510 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d  E_LIMIT_LENGTH]]
25520 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25530 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
25540 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25550 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
25560 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
25570 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
25580 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
25590 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
255a0 5f 53 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28  _SQL_LENGTH]] ^(
255b0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
255c0 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  _SQL_LENGTH</dt>
255d0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
255e0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e  mum length of an
255f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
25600 69 6e 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e  in bytes.</dd>)^
25610 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25620 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e  LIMIT_COLUMN]] ^
25630 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25640 54 5f 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a  T_COLUMN</dt>.**
25650 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25660 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
25670 6e 73 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65  ns in a table de
25680 66 69 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74  finition or in t
25690 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74  he.** result set
256a0 20 6f 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f   of a [SELECT] o
256b0 72 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  r the maximum nu
256c0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20  mber of columns 
256d0 69 6e 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f  in an index.** o
256e0 72 20 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59  r in an ORDER BY
256f0 20 6f 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61   or GROUP BY cla
25700 75 73 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  use.</dd>)^.**.*
25710 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25720 5f 45 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28  _EXPR_DEPTH]] ^(
25730 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25740 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
25750 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25760 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
25770 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
25780 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
25790 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
257a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f  LITE_LIMIT_COMPO
257b0 55 4e 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c  UND_SELECT]] ^(<
257c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
257d0 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c  COMPOUND_SELECT<
257e0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
257f0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
25800 66 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d  f terms in a com
25810 70 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61  pound SELECT sta
25820 74 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a  tement.</dd>)^.*
25830 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
25840 4d 49 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28  MIT_VDBE_OP]] ^(
25850 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
25860 5f 56 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a  _VDBE_OP</dt>.**
25870 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
25880 20 6e 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72   number of instr
25890 75 63 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72  uctions in a vir
258a0 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f  tual machine pro
258b0 67 72 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20  gram.** used to 
258c0 69 6d 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c  implement an SQL
258d0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69   statement.  Thi
258e0 73 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63  s limit is not c
258f0 75 72 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f  urrently.** enfo
25900 72 63 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61  rced, though tha
25910 74 20 6d 69 67 68 74 20 62 65 20 61 64 64 65 64  t might be added
25920 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
25930 72 65 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51  release of.** SQ
25940 4c 69 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  Lite.</dd>)^.**.
25950 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
25960 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d  T_FUNCTION_ARG]]
25970 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25980 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47  MIT_FUNCTION_ARG
25990 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
259a0 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20   maximum number 
259b0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20  of arguments on 
259c0 61 20 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e  a function.</dd>
259d0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
259e0 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
259f0 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ]] ^(<dt>SQLITE_
25a00 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f  LIMIT_ATTACHED</
25a10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25a20 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25a30 20 5b 41 54 54 41 43 48 20 7c 20 61 74 74 61 63   [ATTACH | attac
25a40 68 65 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29  hed databases].)
25a50 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  ^</dd>.**.** [[S
25a60 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45  QLITE_LIMIT_LIKE
25a70 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d  _PATTERN_LENGTH]
25a80 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54  ].** ^(<dt>SQLIT
25a90 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
25aa0 54 45 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e  TERN_LENGTH</dt>
25ab0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
25ac0 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68  mum length of th
25ad0 65 20 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65  e pattern argume
25ae0 6e 74 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d  nt to the [LIKE]
25af0 20 6f 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70   or.** [GLOB] op
25b00 65 72 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a  erators.</dd>)^.
25b10 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c  **.** [[SQLITE_L
25b20 49 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55  IMIT_VARIABLE_NU
25b30 4d 42 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e  MBER]].** ^(<dt>
25b40 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25b50 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74  IABLE_NUMBER</dt
25b60 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
25b70 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65  imum index numbe
25b80 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65  r of any [parame
25b90 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73  ter] in an SQL s
25ba0 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a  tatement.)^.**.*
25bb0 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
25bc0 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d  _TRIGGER_DEPTH]]
25bd0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25be0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
25bf0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
25c00 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20  e maximum depth 
25c10 6f 66 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72  of recursion for
25c20 20 74 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29   triggers.</dd>)
25c30 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64  ^.** </dl>.*/.#d
25c40 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25c50 49 54 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20  IT_LENGTH       
25c60 20 20 20 20 20 20 20 20 20 20 20 20 20 30 0a 23               0.#
25c70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25c80 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20  MIT_SQL_LENGTH  
25c90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a                1.
25ca0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25cb0 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20  IMIT_COLUMN     
25cc0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
25cd0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25ce0 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48  LIMIT_EXPR_DEPTH
25cf0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25d00 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  3.#define SQLITE
25d10 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
25d20 53 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20  SELECT          
25d30 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
25d40 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20  E_LIMIT_VDBE_OP 
25d50 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25d60 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    5.#define SQLI
25d70 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
25d80 4e 5f 41 52 47 20 20 20 20 20 20 20 20 20 20 20  N_ARG           
25d90 20 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c     6.#define SQL
25da0 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48  ITE_LIMIT_ATTACH
25db0 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
25dc0 20 20 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51      7.#define SQ
25dd0 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f  LITE_LIMIT_LIKE_
25de0 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20  PATTERN_LENGTH  
25df0 20 20 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53       8.#define S
25e00 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
25e10 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20  ABLE_NUMBER     
25e20 20 20 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20        9.#define 
25e30 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
25e40 47 47 45 52 5f 44 45 50 54 48 20 20 20 20 20 20  GGER_DEPTH      
25e50 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20        10../*.** 
25e60 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
25e70 69 6e 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65  ing An SQL State
25e80 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ment.** KEYWORDS
25e90 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  : {SQL statement
25ea0 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a   compiler}.**.**
25eb0 20 54 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53   To execute an S
25ec0 51 4c 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73  QL query, it mus
25ed0 74 20 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69  t first be compi
25ee0 6c 65 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d  led into a byte-
25ef0 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20  code.** program 
25f00 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65  using one of the
25f10 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  se routines..**.
25f20 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
25f30 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20  ument, "db", is 
25f40 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
25f50 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64  ection] obtained
25f60 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72   from a.** prior
25f70 20 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c   successful call
25f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
25f90 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
25fa0 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20  pen_v2()] or.** 
25fb0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
25fc0 29 5d 2e 20 20 54 68 65 20 64 61 74 61 62 61 73  )].  The databas
25fd0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73  e connection mus
25fe0 74 20 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20  t not have been 
25ff0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68  closed..**.** Th
26000 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e  e second argumen
26010 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68  t, "zSql", is th
26020 65 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62  e statement to b
26030 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f  e compiled, enco
26040 64 65 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72  ded.** as either
26050 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36   UTF-8 or UTF-16
26060 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70  .  The sqlite3_p
26070 72 65 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c  repare() and sql
26080 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
26090 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
260a0 75 73 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73  use UTF-8, and s
260b0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
260c0 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70  () and sqlite3_p
260d0 72 65 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a  repare16_v2().**
260e0 20 75 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a   use UTF-16..**.
260f0 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65  ** ^If the nByte
26100 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73   argument is les
26110 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65  s than zero, the
26120 6e 20 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75  n zSql is read u
26130 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73  p to the.** firs
26140 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
26150 72 2e 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20  r. ^If nByte is 
26160 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
26170 65 6e 20 69 74 20 69 73 20 74 68 65 20 6d 61 78  en it is the max
26180 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f  imum.** number o
26190 66 20 20 62 79 74 65 73 20 72 65 61 64 20 66 72  f  bytes read fr
261a0 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20  om zSql.  ^When 
261b0 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67  nByte is non-neg
261c0 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53  ative, the.** zS
261d0 71 6c 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61  ql string ends a
261e0 74 20 65 69 74 68 65 72 20 74 68 65 20 66 69 72  t either the fir
261f0 73 74 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75  st '\000' or '\u
26200 30 30 30 30 27 20 63 68 61 72 61 63 74 65 72 20  0000' character 
26210 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d  or.** the nByte-
26220 74 68 20 62 79 74 65 2c 20 77 68 69 63 68 65 76  th byte, whichev
26230 65 72 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20  er comes first. 
26240 49 66 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e  If the caller kn
26250 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ows.** that the 
26260 73 75 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20  supplied string 
26270 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65  is nul-terminate
26280 64 2c 20 74 68 65 6e 20 74 68 65 72 65 20 69 73  d, then there is
26290 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66   a small.** perf
262a0 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67  ormance advantag
262b0 65 20 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62  e to be gained b
262c0 79 20 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79  y passing an nBy
262d0 74 65 20 70 61 72 61 6d 65 74 65 72 20 74 68 61  te parameter tha
262e0 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f  t.** is equal to
262f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
26300 79 74 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75  ytes in the inpu
26310 74 20 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c  t string <i>incl
26320 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65  uding</i>.** the
26330 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20   nul-terminator 
26340 62 79 74 65 73 20 61 73 20 74 68 69 73 20 73 61  bytes as this sa
26350 76 65 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20  ves SQLite from 
26360 68 61 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b  having to.** mak
26370 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  e a copy of the 
26380 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a  input string..**
26390 0a 2a 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69  .** ^If pzTail i
263a0 73 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20  s not NULL then 
263b0 2a 70 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20  *pzTail is made 
263c0 74 6f 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20  to point to the 
263d0 66 69 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61  first byte.** pa
263e0 73 74 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68  st the end of th
263f0 65 20 66 69 72 73 74 20 53 51 4c 20 73 74 61 74  e first SQL stat
26400 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20  ement in zSql.  
26410 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f  These routines o
26420 6e 6c 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74  nly.** compile t
26430 68 65 20 66 69 72 73 74 20 73 74 61 74 65 6d 65  he first stateme
26440 6e 74 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a  nt in zSql, so *
26450 70 7a 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70  pzTail is left p
26460 6f 69 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68  ointing to.** wh
26470 61 74 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d  at remains uncom
26480 70 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70  piled..**.** ^*p
26490 70 53 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f  pStmt is left po
264a0 69 6e 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70  inting to a comp
264b0 69 6c 65 64 20 5b 70 72 65 70 61 72 65 64 20 73  iled [prepared s
264c0 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63  tatement] that c
264d0 61 6e 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65  an be.** execute
264e0 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
264f0 5f 73 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74  _step()].  ^If t
26500 68 65 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72  here is an error
26510 2c 20 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74  , *ppStmt is set
26520 0a 2a 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49  .** to NULL.  ^I
26530 66 20 74 68 65 20 69 6e 70 75 74 20 74 65 78 74  f the input text
26540 20 63 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c   contains no SQL
26550 20 28 69 66 20 74 68 65 20 69 6e 70 75 74 20 69   (if the input i
26560 73 20 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74  s an empty.** st
26570 72 69 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e  ring or a commen
26580 74 29 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20  t) then *ppStmt 
26590 69 73 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a  is set to NULL..
265a0 2a 2a 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70  ** The calling p
265b0 72 6f 63 65 64 75 72 65 20 69 73 20 72 65 73 70  rocedure is resp
265c0 6f 6e 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65  onsible for dele
265d0 74 69 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65  ting the compile
265e0 64 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65  d.** SQL stateme
265f0 6e 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  nt using [sqlite
26600 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66  3_finalize()] af
26610 74 65 72 20 69 74 20 68 61 73 20 66 69 6e 69 73  ter it has finis
26620 68 65 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20  hed with it..** 
26630 70 70 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62  ppStmt may not b
26640 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f  e NULL..**.** ^O
26650 6e 20 73 75 63 63 65 73 73 2c 20 74 68 65 20 73  n success, the s
26660 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
26670 20 66 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69   family of routi
26680 6e 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  nes return [SQLI
26690 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72  TE_OK];.** other
266a0 77 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63  wise an [error c
266b0 6f 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64  ode] is returned
266c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  ..**.** The sqli
266d0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
266e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
266f0 70 61 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65  pare16_v2() inte
26700 72 66 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65  rfaces are.** re
26710 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c  commended for al
26720 6c 20 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20  l new programs. 
26730 54 68 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e  The two older in
26740 74 65 72 66 61 63 65 73 20 61 72 65 20 72 65 74  terfaces are ret
26750 61 69 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63  ained.** for bac
26760 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
26770 6c 69 74 79 2c 20 62 75 74 20 74 68 65 69 72 20  lity, but their 
26780 75 73 65 20 69 73 20 64 69 73 63 6f 75 72 61 67  use is discourag
26790 65 64 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22  ed..** ^In the "
267a0 76 32 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20  v2" interfaces, 
267b0 74 68 65 20 70 72 65 70 61 72 65 64 20 73 74 61  the prepared sta
267c0 74 65 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69  tement.** that i
267d0 73 20 72 65 74 75 72 6e 65 64 20 28 74 68 65 20  s returned (the 
267e0 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f  [sqlite3_stmt] o
267f0 62 6a 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20  bject) contains 
26800 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a  a copy of the.**
26810 20 6f 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65   original SQL te
26820 78 74 2e 20 54 68 69 73 20 63 61 75 73 65 73 20  xt. This causes 
26830 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  the [sqlite3_ste
26840 70 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74  p()] interface t
26850 6f 0a 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66  o.** behave diff
26860 65 72 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65  erently in three
26870 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c   ways:.**.** <ol
26880 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  >.** <li>.** ^If
26890 20 74 68 65 20 64 61 74 61 62 61 73 65 20 73 63   the database sc
268a0 68 65 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e  hema changes, in
268b0 73 74 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69  stead of returni
268c0 6e 67 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d  ng [SQLITE_SCHEM
268d0 41 5d 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61  A] as it.** alwa
268e0 79 73 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b  ys used to do, [
268f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
26900 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c  will automatical
26910 6c 79 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65  ly recompile the
26920 20 53 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e   SQL.** statemen
26930 74 20 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e  t and try to run
26940 20 69 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61   it again. As ma
26950 6e 79 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41  ny as [SQLITE_MA
26960 58 5f 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a  X_SCHEMA_RETRY].
26970 2a 2a 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20  ** retries will 
26980 6f 63 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c  occur before sql
26990 69 74 65 33 5f 73 74 65 70 28 29 20 67 69 76 65  ite3_step() give
269a0 73 20 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73  s up and returns
269b0 20 61 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f   an error..** </
269c0 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a  li>.**.** <li>.*
269d0 2a 20 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72  * ^When an error
269e0 20 6f 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65   occurs, [sqlite
269f0 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72  3_step()] will r
26a00 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65  eturn one of the
26a10 20 64 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72   detailed.** [er
26a20 72 6f 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65  ror codes] or [e
26a30 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
26a40 64 65 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61  des].  ^The lega
26a50 63 79 20 62 65 68 61 76 69 6f 72 20 77 61 73 20  cy behavior was 
26a60 74 68 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  that.** [sqlite3
26a70 5f 73 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f  _step()] would o
26a80 6e 6c 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e  nly return a gen
26a90 65 72 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52  eric [SQLITE_ERR
26aa0 4f 52 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a  OR] result code.
26ab0 2a 2a 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69  ** and the appli
26ac0 63 61 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76  cation would hav
26ad0 65 20 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f  e to make a seco
26ae0 6e 64 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nd call to [sqli
26af0 74 65 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20  te3_reset()].** 
26b00 69 6e 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64  in order to find
26b10 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20   the underlying 
26b20 63 61 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f  cause of the pro
26b30 62 6c 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22  blem. With the "
26b40 76 32 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69  v2" prepare.** i
26b50 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20 75  nterfaces, the u
26b60 6e 64 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e  nderlying reason
26b70 20 66 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69   for the error i
26b80 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64  s returned immed
26b90 69 61 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e  iately..** </li>
26ba0 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e  .**.** <li>.** ^
26bb0 49 66 20 74 68 65 20 73 70 65 63 69 66 69 63 20  If the specific 
26bc0 76 61 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b  value bound to [
26bd0 70 61 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74  parameter | host
26be0 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74   parameter] in t
26bf0 68 65 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61  he .** WHERE cla
26c00 75 73 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65  use might influe
26c10 6e 63 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f  nce the choice o
26c20 66 20 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72  f query plan for
26c30 20 61 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a   a statement,.**
26c40 20 74 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d   then the statem
26c50 65 6e 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ent will be auto
26c60 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
26c70 69 6c 65 64 2c 20 61 73 20 69 66 20 74 68 65 72  iled, as if ther
26c80 65 20 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61  e had been .** a
26c90 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20   schema change, 
26ca0 6f 6e 20 74 68 65 20 66 69 72 73 74 20 20 5b 73  on the first  [s
26cb0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63  qlite3_step()] c
26cc0 61 6c 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  all following an
26cd0 79 20 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74  y change.** to t
26ce0 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
26cf0 5f 74 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73  _text | bindings
26d00 5d 20 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d  ] of that [param
26d10 65 74 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20  eter]. .** ^The 
26d20 73 70 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f  specific value o
26d30 66 20 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b  f WHERE-clause [
26d40 70 61 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74  parameter] might
26d50 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a   influence the .
26d60 2a 2a 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65  ** choice of que
26d70 72 79 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70  ry plan if the p
26d80 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
26d90 6c 65 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f  left-hand side o
26da0 66 20 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72  f a [LIKE].** or
26db0 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72   [GLOB] operator
26dc0 20 6f 72 20 69 66 20 74 68 65 20 70 61 72 61 6d   or if the param
26dd0 65 74 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64  eter is compared
26de0 20 74 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63   to an indexed c
26df0 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65  olumn.** and the
26e00 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
26e10 53 54 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74  STAT3] compile-t
26e20 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e  ime option is en
26e30 61 62 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  abled..** </li>.
26e40 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20  ** </ol>.*/.int 
26e50 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
26e60 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
26e70 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
26e80 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f  tabase handle */
26e90 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
26ea0 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51  Sql,       /* SQ
26eb0 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46  L statement, UTF
26ec0 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  -8 encoded */.  
26ed0 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
26ee0 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
26ef0 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
26f00 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
26f10 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
26f20 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
26f30 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
26f40 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26f50 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  r **pzTail     /
26f60 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
26f70 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
26f80 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
26f90 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
26fa0 72 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  re_v2(.  sqlite3
26fb0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
26fc0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e   /* Database han
26fd0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63  dle */.  const c
26fe0 68 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20  har *zSql,      
26ff0 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   /* SQL statemen
27000 74 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64  t, UTF-8 encoded
27010 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c   */.  int nByte,
27020 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
27030 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20   Maximum length 
27040 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73  of zSql in bytes
27050 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73  . */.  sqlite3_s
27060 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f  tmt **ppStmt,  /
27070 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74  * OUT: Statement
27080 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
27090 73 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c  st char **pzTail
270a0 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69       /* OUT: Poi
270b0 6e 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70  nter to unused p
270c0 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a  ortion of zSql *
270d0 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  /.);.int sqlite3
270e0 5f 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71  _prepare16(.  sq
270f0 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
27100 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
27110 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f  e handle */.  co
27120 6e 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20  nst void *zSql, 
27130 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61        /* SQL sta
27140 74 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65  tement, UTF-16 e
27150 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20  ncoded */.  int 
27160 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20  nByte,          
27170 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c      /* Maximum l
27180 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e  ength of zSql in
27190 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c   bytes. */.  sql
271a0 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74  ite3_stmt **ppSt
271b0 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61  mt,  /* OUT: Sta
271c0 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f  tement handle */
271d0 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a  .  const void **
271e0 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55  pzTail     /* OU
271f0 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e  T: Pointer to un
27200 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20  used portion of 
27210 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  zSql */.);.int s
27220 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
27230 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
27240 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
27250 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
27260 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
27270 64 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  d *zSql,       /
27280 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
27290 20 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20   UTF-16 encoded 
272a0 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
272b0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
272c0 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
272d0 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
272e0 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
272f0 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
27300 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
27310 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
27320 74 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20  t void **pzTail 
27330 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
27340 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
27350 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
27360 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
27370 52 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20  REF: Retrieving 
27380 53 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a  Statement SQL.**
27390 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
273a0 61 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ace can be used 
273b0 74 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61  to retrieve a sa
273c0 76 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20  ved copy of the 
273d0 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20  original.** SQL 
273e0 74 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65  text used to cre
273f0 61 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20  ate a [prepared 
27400 73 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68  statement] if th
27410 61 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  at statement was
27420 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69  .** compiled usi
27430 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
27440 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
27450 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
27460 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f  pare16_v2()]..*/
27470 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
27480 69 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33  ite3_sql(sqlite3
27490 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
274a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
274b0 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20  Determine If An 
274c0 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72  SQL Statement Wr
274d0 69 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73  ites The Databas
274e0 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  e.**.** ^The sql
274f0 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e  ite3_stmt_readon
27500 6c 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20  ly(X) interface 
27510 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f  returns true (no
27520 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e  n-zero) if.** an
27530 64 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70  d only if the [p
27540 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27550 74 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69  t] X makes no di
27560 72 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a  rect changes to.
27570 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f  ** the content o
27580 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  f the database f
27590 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20  ile..**.** Note 
275a0 74 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f  that [applicatio
275b0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
275c0 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b  nctions] or.** [
275d0 76 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20  virtual tables] 
275e0 6d 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65  might change the
275f0 20 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65   database indire
27600 63 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65  ctly as a side e
27610 66 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f  ffect.  .** ^(Fo
27620 72 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e  r example, if an
27630 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
27640 69 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20  ines a function 
27650 22 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a  "eval()" that .*
27660 2a 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33  * calls [sqlite3
27670 5f 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74  _exec()], then t
27680 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  he following SQL
27690 20 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64   statement would
276a0 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64  .** change the d
276b0 61 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72  atabase file thr
276c0 6f 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74  ough side-effect
276d0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  s:.**.** <blockq
276e0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
276f0 20 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45   SELECT eval('DE
27700 4c 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46  LETE FROM t1') F
27710 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65  ROM t2;.** </pre
27720 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a  ></blockquote>.*
27730 2a 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65  *.** But because
27740 20 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74   the [SELECT] st
27750 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
27760 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
27770 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72  base file.** dir
27780 65 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73  ectly, sqlite3_s
27790 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77  tmt_readonly() w
277a0 6f 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72  ould still retur
277b0 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  n true.)^.**.** 
277c0 5e 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e  ^Transaction con
277d0 74 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20  trol statements 
277e0 73 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c  such as [BEGIN],
277f0 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c   [COMMIT], [ROLL
27800 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50  BACK],.** [SAVEP
27810 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45  OINT], and [RELE
27820 41 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74  ASE] cause sqlit
27830 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27840 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
27850 65 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20  e,.** since the 
27860 73 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73  statements thems
27870 65 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74  elves do not act
27880 75 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65  ually modify the
27890 20 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a   database but.**
278a0 20 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e   rather they con
278b0 74 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20  trol the timing 
278c0 6f 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74  of when other st
278d0 61 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20  atements modify 
278e0 74 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65  the .** database
278f0 2e 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d  .  ^The [ATTACH]
27900 20 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74   and [DETACH] st
27910 61 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61  atements also ca
27920 75 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  use.** sqlite3_s
27930 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74  tmt_readonly() t
27940 6f 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69  o return true si
27950 6e 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65  nce, while those
27960 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63   statements.** c
27970 68 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67  hange the config
27980 75 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74  uration of a dat
27990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
279a0 2c 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61  , they do not ma
279b0 6b 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74  ke .** changes t
279c0 6f 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  o the content of
279d0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
279e0 6c 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a  les on disk..*/.
279f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  int sqlite3_stmt
27a00 5f 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65  _readonly(sqlite
27a10 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
27a20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
27a30 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20   Determine If A 
27a40 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
27a50 6e 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65  nt Has Been Rese
27a60 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  t.**.** ^The sql
27a70 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53  ite3_stmt_busy(S
27a80 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
27a90 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65  rns true (non-ze
27aa0 72 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70  ro) if the.** [p
27ab0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
27ac0 74 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74  t] S has been st
27ad0 65 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f  epped at least o
27ae0 6e 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73  nce using .** [s
27af0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
27b00 62 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20  but has not run 
27b10 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e  to completion an
27b20 64 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a  d/or has not .**
27b30 20 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e   been reset usin
27b40 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
27b50 28 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69  (S)].  ^The sqli
27b60 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
27b70 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65  .** interface re
27b80 74 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53  turns false if S
27b90 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
27ba0 65 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74  er.  If S is not
27bb0 20 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e   a .** NULL poin
27bc0 74 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ter and is not a
27bd0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61   pointer to a va
27be0 6c 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  lid [prepared st
27bf0 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65  atement].** obje
27c00 63 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ct, then the beh
27c10 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
27c20 65 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20  ed and probably 
27c30 75 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a  undesirable..**.
27c40 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63  ** This interfac
27c50 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e  e can be used in
27c60 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71   combination [sq
27c70 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
27c80 29 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20  )].** to locate 
27c90 61 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61  all prepared sta
27ca0 74 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74  tements associat
27cb0 65 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61  ed with a databa
27cc0 73 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  se .** connectio
27cd0 6e 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65  n that are in ne
27ce0 65 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65  ed of being rese
27cf0 74 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20  t.  This can be 
27d00 75 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61  used,.** for exa
27d10 6d 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73  mple, in diagnos
27d20 74 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  tic routines to 
27d30 73 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61  search for prepa
27d40 72 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  red .** statemen
27d50 74 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64  ts that are hold
27d60 69 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f  ing a transactio
27d70 6e 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73  n open..*/.int s
27d80 71 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79  qlite3_stmt_busy
27d90 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b  (sqlite3_stmt*);
27da0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
27db0 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79  : Dynamically Ty
27dc0 70 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74  ped Value Object
27dd0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70  .** KEYWORDS: {p
27de0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
27df0 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65  _value} {unprote
27e00 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27e10 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  ue}.**.** SQLite
27e20 20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65   uses the sqlite
27e30 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74  3_value object t
27e40 6f 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20  o represent all 
27e50 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63  values.** that c
27e60 61 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20  an be stored in 
27e70 61 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65  a database table
27e80 2e 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79  . SQLite uses dy
27e90 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20  namic typing.** 
27ea0 66 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69  for the values i
27eb0 74 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75  t stores.  ^Valu
27ec0 65 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c  es stored in sql
27ed0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27ee0 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74  ts.** can be int
27ef0 65 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20  egers, floating 
27f00 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74  point values, st
27f10 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72  rings, BLOBs, or
27f20 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20   NULL..**.** An 
27f30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
27f40 6a 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68  ject may be eith
27f50 65 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f  er "protected" o
27f60 72 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e  r "unprotected".
27f70 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61  .** Some interfa
27f80 63 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72  ces require a pr
27f90 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
27fa0 76 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e  value.  Other in
27fb0 74 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c  terfaces.** will
27fc0 20 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61   accept either a
27fd0 20 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e   protected or an
27fe0 20 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c   unprotected sql
27ff0 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45  ite3_value..** E
28000 76 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74  very interface t
28010 68 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69  hat accepts sqli
28020 74 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65  te3_value argume
28030 6e 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a  nts specifies.**
28040 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
28050 69 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72  it requires a pr
28060 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
28070 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
28080 20 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65   terms "protecte
28090 64 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63  d" and "unprotec
280a0 74 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68  ted" refer to wh
280b0 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20  ether or not.** 
280c0 61 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e  a mutex is held.
280d0 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75    An internal mu
280e0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
280f0 61 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  a protected.** s
28100 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28110 65 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78  ect but no mutex
28120 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20   is held for an 
28130 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73  unprotected.** s
28140 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
28150 65 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20  ect.  If SQLite 
28160 69 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62  is compiled to b
28170 65 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65  e single-threade
28180 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49  d.** (with [SQLI
28190 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d  TE_THREADSAFE=0]
281a0 20 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74   and with [sqlit
281b0 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d  e3_threadsafe()]
281c0 20 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a   returning 0).**
281d0 20 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73   or if SQLite is
281e0 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72   run in one of r
281f0 65 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64  educed mutex mod
28200 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  es .** [SQLITE_C
28210 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45  ONFIG_SINGLETHRE
28220 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  AD] or [SQLITE_C
28230 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
28240 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65  D].** then there
28250 20 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69   is no distincti
28260 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
28270 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
28280 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
28290 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e  value objects an
282a0 64 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73  d they can be us
282b0 65 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62  ed interchangeab
282c0 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a  ly.  However,.**
282d0 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64   for maximum cod
282e0 65 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74  e portability it
282f0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
28300 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
28310 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20  s.** still make 
28320 74 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20  the distinction 
28330 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65  between protecte
28340 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65  d and unprotecte
28350 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c  d.** sqlite3_val
28360 75 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20  ue objects even 
28370 77 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c  when not strictl
28380 79 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a  y required..**.*
28390 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
283a0 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61  alue objects tha
283b0 74 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20  t are passed as 
283c0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20  parameters into 
283d0 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  the.** implement
283e0 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63  ation of [applic
283f0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
28400 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65  L functions] are
28410 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e   protected..** ^
28420 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  The sqlite3_valu
28430 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
28440 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
28450 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d  _column_value()]
28460 20 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e   is unprotected.
28470 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20  .** Unprotected 
28480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
28490 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62  jects may only b
284a0 65 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b  e used with.** [
284b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
284c0 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  alue()] and [sql
284d0 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28  ite3_bind_value(
284e0 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69  )]..** The [sqli
284f0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c  te3_value_blob |
28500 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
28510 79 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66  ype()] family of
28520 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72  .** interfaces r
28530 65 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64  equire protected
28540 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
28550 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64  bjects..*/.typed
28560 65 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71  ef struct Mem sq
28570 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a  lite3_value;../*
28580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51  .** CAPI3REF: SQ
28590 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  L Function Conte
285a0 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20  xt Object.**.** 
285b0 54 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77  The context in w
285c0 68 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63  hich an SQL func
285d0 74 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73  tion executes is
285e0 20 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a   stored in an.**
285f0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
28600 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69   object.  ^A poi
28610 6e 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74  nter to an sqlit
28620 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63  e3_context objec
28630 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66  t.** is always f
28640 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
28650 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  o [application-d
28660 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
28670 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70  ions]..** The ap
28680 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
28690 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  d SQL function i
286a0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69  mplementation wi
286b0 6c 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20  ll pass this.** 
286c0 70 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20  pointer through 
286d0 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73  into calls to [s
286e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
286f0 74 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75  t | sqlite3_resu
28700 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74  lt()],.** [sqlit
28710 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
28720 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65  text()], [sqlite
28730 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a  3_user_data()],.
28740 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ** [sqlite3_cont
28750 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d  ext_db_handle()]
28760 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61  , [sqlite3_get_a
28770 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e  uxdata()],.** an
28780 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65  d/or [sqlite3_se
28790 74 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f  t_auxdata()]..*/
287a0 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
287b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
287c0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b  sqlite3_context;
287d0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
287e0 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73  : Binding Values
287f0 20 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61   To Prepared Sta
28800 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f  tements.** KEYWO
28810 52 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d  RDS: {host param
28820 65 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61  eter} {host para
28830 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61  meters} {host pa
28840 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a  rameter name}.**
28850 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20   KEYWORDS: {SQL 
28860 70 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20  parameter} {SQL 
28870 70 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72  parameters} {par
28880 61 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a  ameter binding}.
28890 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53  **.** ^(In the S
288a0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78  QL statement tex
288b0 74 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69  t input to [sqli
288c0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
288d0 5d 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e  ] and its varian
288e0 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20  ts,.** literals 
288f0 6d 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20  may be replaced 
28900 62 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d  by a [parameter]
28910 20 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e   that matches on
28920 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a  e of following.*
28930 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a  * templates:.**.
28940 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
28950 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e   ?.** <li>  ?NNN
28960 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a  .** <li>  :VVV.*
28970 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20  * <li>  @VVV.** 
28980 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f  <li>  $VVV.** </
28990 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65  ul>.**.** In the
289a0 20 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65   templates above
289b0 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73  , NNN represents
289c0 20 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65   an integer lite
289d0 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20  ral,.** and VVV 
289e0 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c  represents an al
289f0 70 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74  phanumeric ident
28a00 69 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76  ifier.)^  ^The v
28a10 61 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a  alues of these.*
28a20 2a 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c  * parameters (al
28a30 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20  so called "host 
28a40 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22  parameter names"
28a50 20 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74   or "SQL paramet
28a60 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20  ers").** can be 
28a70 73 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71  set using the sq
28a80 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
28a90 6f 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20  outines defined 
28aa0 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  here..**.** ^The
28ab0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
28ac0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  to the sqlite3_b
28ad0 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73  ind_*() routines
28ae0 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20   is always.** a 
28af0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
28b00 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62  sqlite3_stmt] ob
28b10 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72  ject returned fr
28b20 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  om.** [sqlite3_p
28b30 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
28b40 69 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a  its variants..**
28b50 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
28b60 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
28b70 69 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c  index of the SQL
28b80 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65   parameter to be
28b90 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65   set..** ^The le
28ba0 66 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d  ftmost SQL param
28bb0 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
28bc0 78 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74  x of 1.  ^When t
28bd0 68 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a  he same named.**
28be0 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69   SQL parameter i
28bf0 73 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e  s used more than
28c00 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e   once, second an
28c10 64 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20  d subsequent.** 
28c20 6f 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65  occurrences have
28c30 20 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20   the same index 
28c40 61 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63  as the first occ
28c50 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65  urrence..** ^The
28c60 20 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64   index for named
28c70 20 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20   parameters can 
28c80 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69  be looked up usi
28c90 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ng the.** [sqlit
28ca0 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
28cb0 72 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69  r_index()] API i
28cc0 66 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65  f desired.  ^The
28cd0 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f   index.** for "?
28ce0 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20  NNN" parameters 
28cf0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
28d00 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e  NNN..** ^The NNN
28d10 20 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62   value must be b
28d20 65 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65  etween 1 and the
28d30 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28   [sqlite3_limit(
28d40 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  )].** parameter 
28d50 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41  [SQLITE_LIMIT_VA
28d60 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28  RIABLE_NUMBER] (
28d70 64 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39  default value: 9
28d80 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  99)..**.** ^The 
28d90 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
28da0 73 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62  s the value to b
28db0 69 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d  ind to the param
28dc0 65 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  eter..** ^If the
28dd0 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
28de0 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
28df0 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74  _text() or sqlit
28e00 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
28e10 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62  .** or sqlite3_b
28e20 69 6e 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20  ind_blob() is a 
28e30 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65  NULL pointer the
28e40 6e 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  n the fourth par
28e50 61 6d 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e  ameter.** is ign
28e60 6f 72 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64  ored and the end
28e70 20 72 65 73 75 6c 74 20 69 73 20 74 68 65 20 73   result is the s
28e80 61 6d 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62  ame as sqlite3_b
28e90 69 6e 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a  ind_null()..**.*
28ea0 2a 20 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75  * ^(In those rou
28eb0 74 69 6e 65 73 20 74 68 61 74 20 68 61 76 65 20  tines that have 
28ec0 61 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  a fourth argumen
28ed0 74 2c 20 69 74 73 20 76 61 6c 75 65 20 69 73 20  t, its value is 
28ee0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
28ef0 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 70 61   bytes in the pa
28f00 72 61 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20  rameter.  To be 
28f10 63 6c 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65  clear: the value
28f20 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65   is the.** numbe
28f30 72 20 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75  r of <u>bytes</u
28f40 3e 20 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20  > in the value, 
28f50 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  not the number o
28f60 66 20 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a  f characters.)^.
28f70 2a 2a 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74  ** ^If the fourt
28f80 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
28f90 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74  qlite3_bind_text
28fa0 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  () or sqlite3_bi
28fb0 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69  nd_text16().** i
28fc0 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  s negative, then
28fd0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74   the length of t
28fe0 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20  he string is.** 
28ff0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
29000 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66 69  tes up to the fi
29010 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  rst zero termina
29020 74 6f 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66  tor..** If the f
29030 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
29040 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  to sqlite3_bind_
29050 62 6c 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69  blob() is negati
29060 76 65 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20  ve, then.** the 
29070 62 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65  behavior is unde
29080 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e  fined..** If a n
29090 6f 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72  on-negative four
290a0 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  th parameter is 
290b0 70 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69  provided to sqli
290c0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a  te3_bind_text().
290d0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ** or sqlite3_bi
290e0 6e 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e  nd_text16() then
290f0 20 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20   that parameter 
29100 6d 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65  must be the byte
29110 20 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65   offset.** where
29120 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61   the NUL termina
29130 74 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20  tor would occur 
29140 61 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72  assuming the str
29150 69 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20  ing were NUL.** 
29160 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20  terminated.  If 
29170 61 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65  any NUL characte
29180 72 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65  rs occur at byte
29190 20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68   offsets less th
291a0 61 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65  an .** the value
291b0 20 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70   of the fourth p
291c0 61 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68  arameter then th
291d0 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69  e resulting stri
291e0 6e 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a  ng value will.**
291f0 20 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65   contain embedde
29200 64 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73  d NULs.  The res
29210 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
29220 6e 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72  ns involving str
29230 69 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62  ings.** with emb
29240 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
29250 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
29260 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  The fifth argume
29270 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  nt to sqlite3_bi
29280 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74  nd_blob(), sqlit
29290 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20  e3_bind_text(), 
292a0 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62  and.** sqlite3_b
292b0 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20  ind_text16() is 
292c0 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65  a destructor use
292d0 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20  d to dispose of 
292e0 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73  the BLOB or.** s
292f0 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69  tring after SQLi
29300 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  te has finished 
29310 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64  with it.  ^The d
29320 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c  estructor is cal
29330 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73  led.** to dispos
29340 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72  e of the BLOB or
29350 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20   string even if 
29360 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69  the call to sqli
29370 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c  te3_bind_blob(),
29380 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  .** sqlite3_bind
29390 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69  _text(), or sqli
293a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28  te3_bind_text16(
293b0 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49  ) fails.  .** ^I
293c0 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75  f the fifth argu
293d0 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73  ment is.** the s
293e0 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51  pecial value [SQ
293f0 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68  LITE_STATIC], th
29400 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65  en SQLite assume
29410 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e  s that the.** in
29420 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20  formation is in 
29430 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65  static, unmanage
29440 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73  d space and does
29450 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20   not need to be 
29460 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  freed..** ^If th
29470 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29480 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b   has the value [
29490 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54  SQLITE_TRANSIENT
294a0 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74  ], then.** SQLit
294b0 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20  e makes its own 
294c0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20  private copy of 
294d0 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61  the data immedia
294e0 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20  tely, before.** 
294f0 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  the sqlite3_bind
29500 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  _*() routine ret
29510 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
29520 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65   sqlite3_bind_ze
29530 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65  roblob() routine
29540 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66   binds a BLOB of
29550 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a   length N that.*
29560 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  * is filled with
29570 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72   zeroes.  ^A zer
29580 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78  oblob uses a fix
29590 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d  ed amount of mem
295a0 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20  ory.** (just an 
295b0 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20  integer to hold 
295c0 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20  its size) while 
295d0 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63  it is being proc
295e0 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c  essed..** Zerobl
295f0 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64  obs are intended
29600 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61   to serve as pla
29610 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c  ceholders for BL
29620 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e  OBs whose.** con
29630 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72  tent is later wr
29640 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b  itten using.** [
29650 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65  sqlite3_blob_ope
29660 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20  n | incremental 
29670 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e  BLOB I/O] routin
29680 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69  es..** ^A negati
29690 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65  ve value for the
296a0 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74   zeroblob result
296b0 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67  s in a zero-leng
296c0 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e  th BLOB..**.** ^
296d0 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71  If any of the sq
296e0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
296f0 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
29700 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70  ed with a NULL p
29710 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68  ointer.** for th
29720 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
29730 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61  ement] or with a
29740 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d   prepared statem
29750 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a  ent for which.**
29760 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
29770 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65  ] has been calle
29780 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20  d more recently 
29790 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  than [sqlite3_re
297a0 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20  set()],.** then 
297b0 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65  the call will re
297c0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53  turn [SQLITE_MIS
297d0 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71  USE].  If any sq
297e0 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a  lite3_bind_().**
297f0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73   routine is pass
29800 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  ed a [prepared s
29810 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68  tatement] that h
29820 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
29830 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74  d, the.** result
29840 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e   is undefined an
29850 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66  d probably harmf
29860 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69  ul..**.** ^Bindi
29870 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61  ngs are not clea
29880 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69  red by the [sqli
29890 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75  te3_reset()] rou
298a0 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e  tine..** ^Unboun
298b0 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  d parameters are
298c0 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
298d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  NULL..**.** ^The
298e0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20   sqlite3_bind_* 
298f0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
29900 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73  [SQLITE_OK] on s
29910 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20  uccess or an.** 
29920 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20  [error code] if 
29930 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72  anything goes wr
29940 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ong..** ^[SQLITE
29950 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72  _RANGE] is retur
29960 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d  ned if the param
29970 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73  eter.** index is
29980 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20   out of range.  
29990 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20  ^[SQLITE_NOMEM] 
299a0 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d  is returned if m
299b0 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a  alloc() fails..*
299c0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
299d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
299e0 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
299f0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29a00 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29a10 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ()], and [sqlite
29a20 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
29a30 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
29a40 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62  t sqlite3_bind_b
29a50 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lob(sqlite3_stmt
29a60 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f  *, int, const vo
29a70 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64  id*, int n, void
29a80 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74  (*)(void*));.int
29a90 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f   sqlite3_bind_do
29aa0 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  uble(sqlite3_stm
29ab0 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29  t*, int, double)
29ac0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
29ad0 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73  nd_int(sqlite3_s
29ae0 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b  tmt*, int, int);
29af0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29b00 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  d_int64(sqlite3_
29b10 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69  stmt*, int, sqli
29b20 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20  te3_int64);.int 
29b30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c  sqlite3_bind_nul
29b40 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  l(sqlite3_stmt*,
29b50 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74   int);.int sqlit
29b60 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c  e3_bind_text(sql
29b70 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
29b80 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
29b90 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  t n, void(*)(voi
29ba0 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
29bb0 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71  3_bind_text16(sq
29bc0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29bd0 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
29be0 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
29bf0 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
29c00 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69  _bind_value(sqli
29c10 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29c20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61  const sqlite3_va
29c30 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
29c40 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
29c50 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
29c60 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a  int, int n);../*
29c70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75  .** CAPI3REF: Nu
29c80 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61  mber Of SQL Para
29c90 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68  meters.**.** ^Th
29ca0 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62  is routine can b
29cb0 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74  e used to find t
29cc0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51  he number of [SQ
29cd0 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a  L parameters].**
29ce0 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   in a [prepared 
29cf0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c  statement].  SQL
29d00 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
29d10 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a  tokens of the.**
29d20 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e   form "?", "?NNN
29d30 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41  ", ":AAA", "$AAA
29d40 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61  ", or "@AAA" tha
29d50 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c  t serve as.** pl
29d60 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76  aceholders for v
29d70 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b  alues that are [
29d80 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29d90 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f  b | bound].** to
29da0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20   the parameters 
29db0 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e  at a later time.
29dc0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f  .**.** ^(This ro
29dd0 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72  utine actually r
29de0 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78  eturns the index
29df0 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20   of the largest 
29e00 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70  (rightmost).** p
29e10 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c  arameter. For al
29e20 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f  l forms except ?
29e30 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63  NNN, this will c
29e40 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65  orrespond to the
29e50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e  .** number of un
29e60 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e  ique parameters.
29e70 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20    If parameters 
29e80 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d  of the ?NNN form
29e90 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68   are used,.** th
29ea0 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20  ere may be gaps 
29eb0 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a  in the list.)^.*
29ec0 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b  *.** See also: [
29ed0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
29ee0 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29  b|sqlite3_bind()
29ef0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  ],.** [sqlite3_b
29f00 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
29f10 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73  me()], and.** [s
29f20 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
29f30 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a  meter_index()]..
29f40 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  */.int sqlite3_b
29f50 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f  ind_parameter_co
29f60 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
29f70 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
29f80 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48  REF: Name Of A H
29f90 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a  ost Parameter.**
29fa0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
29fb0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
29fc0 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66  name(P,N) interf
29fd0 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  ace returns.** t
29fe0 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e  he name of the N
29ff0 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74  -th [SQL paramet
2a000 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70  er] in the [prep
2a010 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2a020 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61  P..** ^(SQL para
2a030 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f  meters of the fo
2a040 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41  rm "?NNN" or ":A
2a050 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72  AA" or "@AAA" or
2a060 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20   "$AAA".** have 
2a070 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20  a name which is 
2a080 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e  the string "?NNN
2a090 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22  " or ":AAA" or "
2a0a0 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a  @AAA" or "$AAA".
2a0b0 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  ** respectively.
2a0c0 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72  .** In other wor
2a0d0 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20  ds, the initial 
2a0e0 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40  ":" or "$" or "@
2a0f0 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69  " or "?".** is i
2a100 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20  ncluded as part 
2a110 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a  of the name.)^.*
2a120 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66  * ^Parameters of
2a130 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69   the form "?" wi
2a140 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e  thout a followin
2a150 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e  g integer have n
2a160 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72  o name.** and ar
2a170 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73  e referred to as
2a180 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22   "nameless" or "
2a190 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65  anonymous parame
2a1a0 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ters"..**.** ^Th
2a1b0 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
2a1c0 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
2a1d0 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
2a1e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
2a1f0 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
2a200 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
2a210 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
2a220 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
2a230 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
2a240 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
2a250 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
2a260 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
2a270 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
2a280 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
2a290 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
2a2a0 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
2a2b0 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
2a2c0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a2d0 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
2a2e0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
2a2f0 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
2a300 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
2a310 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
2a320 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
2a330 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
2a340 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
2a350 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
2a360 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
2a370 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
2a380 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2a390 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
2a3a0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
2a3b0 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
2a3c0 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
2a3d0 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
2a3e0 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
2a3f0 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
2a400 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
2a410 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
2a420 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
2a430 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
2a440 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
2a450 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
2a460 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
2a470 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
2a480 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
2a490 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
2a4a0 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
2a4b0 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
2a4c0 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
2a4d0 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
2a4e0 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
2a4f0 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
2a500 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
2a510 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
2a520 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
2a530 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
2a540 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
2a550 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2a560 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
2a570 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
2a580 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a590 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
2a5a0 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
2a5b0 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
2a5c0 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
2a5d0 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
2a5e0 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
2a5f0 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
2a600 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
2a610 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a620 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
2a630 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
2a640 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
2a650 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
2a660 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
2a670 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
2a680 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
2a690 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
2a6a0 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
2a6b0 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
2a6c0 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
2a6d0 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
2a6e0 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
2a6f0 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
2a700 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
2a710 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
2a720 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
2a730 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
2a740 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2a750 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
2a760 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2a770 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
2a780 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
2a790 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
2a7a0 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
2a7b0 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
2a7c0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
2a7d0 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
2a7e0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2a7f0 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
2a800 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
2a810 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
2a820 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
2a830 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
2a840 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
2a850 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
2a860 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
2a870 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
2a880 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
2a890 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a8a0 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
2a8b0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2a8c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
2a8d0 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
2a8e0 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
2a8f0 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
2a900 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
2a910 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
2a920 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
2a930 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
2a940 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
2a950 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
2a960 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
2a970 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
2a980 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2a990 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
2a9a0 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
2a9b0 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
2a9c0 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
2a9d0 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
2a9e0 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
2a9f0 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
2aa00 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
2aa10 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
2aa20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
2aa30 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2aa40 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
2aa50 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
2aa60 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
2aa70 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2aa80 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
2aa90 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
2aaa0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
2aab0 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
2aac0 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
2aad0 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
2aae0 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
2aaf0 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
2ab00 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2ab10 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
2ab20 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
2ab30 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
2ab40 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
2ab50 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
2ab60 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
2ab70 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
2ab80 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
2ab90 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
2aba0 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
2abb0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
2abc0 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
2abd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
2abe0 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
2abf0 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
2ac00 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
2ac10 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
2ac20 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
2ac30 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
2ac40 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
2ac50 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
2ac60 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
2ac70 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
2ac80 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
2ac90 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
2aca0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
2acb0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
2acc0 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
2acd0 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
2ace0 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2acf0 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
2ad00 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
2ad10 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
2ad20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
2ad30 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
2ad40 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
2ad50 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
2ad60 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
2ad70 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
2ad80 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
2ad90 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
2ada0 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
2adb0 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
2adc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2add0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2ade0 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
2adf0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2ae00 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
2ae10 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
2ae20 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2ae30 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
2ae40 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
2ae50 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
2ae60 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
2ae70 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
2ae80 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
2ae90 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
2aea0 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
2aeb0 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
2aec0 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
2aed0 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
2aee0 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
2aef0 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
2af00 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
2af10 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
2af20 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
2af30 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
2af40 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
2af50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
2af60 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
2af70 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2af80 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
2af90 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
2afa0 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
2afb0 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
2afc0 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
2afd0 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
2afe0 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
2aff0 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
2b000 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2b010 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
2b020 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2b030 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
2b040 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
2b050 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2b060 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
2b070 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
2b080 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
2b090 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
2b0a0 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
2b0b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
2b0c0 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
2b0d0 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
2b0e0 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
2b0f0 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
2b100 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
2b110 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
2b120 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
2b130 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
2b140 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
2b150 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
2b160 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
2b170 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
2b180 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
2b190 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
2b1a0 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
2b1b0 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
2b1c0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2b1d0 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
2b1e0 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
2b1f0 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
2b200 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
2b210 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
2b220 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
2b230 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
2b240 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
2b250 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
2b260 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
2b270 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
2b280 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
2b290 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2b2a0 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
2b2b0 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
2b2c0 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
2b2d0 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
2b2e0 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
2b2f0 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
2b300 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
2b310 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
2b320 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
2b330 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
2b340 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
2b350 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
2b360 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
2b370 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
2b380 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
2b390 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
2b3a0 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
2b3b0 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
2b3c0 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
2b3d0 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
2b3e0 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
2b3f0 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
2b400 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
2b410 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
2b420 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
2b430 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
2b440 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
2b450 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
2b460 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
2b470 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
2b480 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
2b490 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
2b4a0 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
2b4b0 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
2b4c0 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
2b4d0 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
2b4e0 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
2b4f0 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
2b500 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
2b510 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
2b520 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
2b530 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
2b540 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
2b550 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
2b560 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2b570 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
2b580 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
2b590 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
2b5a0 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
2b5b0 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
2b5c0 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
2b5d0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
2b5e0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2b5f0 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
2b600 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
2b610 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
2b620 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
2b630 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2b640 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
2b650 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
2b660 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
2b670 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2b680 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
2b690 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b6a0 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
2b6b0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b6c0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2b6d0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b6e0 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
2b6f0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2b700 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
2b710 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2b720 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
2b730 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
2b740 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2b750 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
2b760 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
2b770 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2b780 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
2b790 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
2b7a0 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
2b7b0 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
2b7c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2b7d0 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
2b7e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b7f0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2b800 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
2b810 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
2b820 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
2b830 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
2b840 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
2b850 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
2b860 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
2b870 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
2b880 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
2b890 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
2b8a0 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
2b8b0 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
2b8c0 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
2b8d0 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
2b8e0 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
2b8f0 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
2b900 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
2b910 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
2b920 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
2b930 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
2b940 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
2b950 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
2b960 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
2b970 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
2b980 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
2b990 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
2b9a0 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
2b9b0 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
2b9c0 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
2b9d0 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
2b9e0 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
2b9f0 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
2ba00 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
2ba10 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
2ba20 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
2ba30 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
2ba40 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
2ba50 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
2ba60 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
2ba70 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
2ba80 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
2ba90 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
2baa0 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
2bab0 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
2bac0 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
2bad0 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
2bae0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2baf0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
2bb00 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
2bb10 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
2bb20 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
2bb30 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
2bb40 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
2bb50 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
2bb60 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
2bb70 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
2bb80 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
2bb90 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
2bba0 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
2bbb0 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
2bbc0 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
2bbd0 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
2bbe0 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
2bbf0 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
2bc00 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
2bc10 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
2bc20 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
2bc30 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
2bc40 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
2bc50 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
2bc60 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
2bc70 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
2bc80 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
2bc90 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
2bca0 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
2bcb0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
2bcc0 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
2bcd0 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
2bce0 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
2bcf0 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
2bd00 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
2bd10 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
2bd20 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
2bd30 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2bd40 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
2bd50 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
2bd60 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
2bd70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2bd80 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bd90 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
2bda0 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
2bdb0 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
2bdc0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
2bdd0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
2bde0 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
2bdf0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
2be00 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
2be10 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
2be20 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
2be30 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
2be40 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
2be50 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
2be60 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2be70 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
2be80 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
2be90 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
2bea0 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
2beb0 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
2bec0 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
2bed0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
2bee0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2bef0 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
2bf00 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
2bf10 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
2bf20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
2bf30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
2bf40 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
2bf50 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
2bf60 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
2bf70 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
2bf80 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
2bf90 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
2bfa0 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
2bfb0 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
2bfc0 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
2bfd0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
2bfe0 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
2bff0 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
2c000 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
2c010 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
2c020 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
2c030 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
2c040 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
2c050 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
2c060 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
2c070 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c080 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
2c090 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
2c0a0 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
2c0b0 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
2c0c0 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
2c0d0 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
2c0e0 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
2c0f0 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c100 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
2c110 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
2c120 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
2c130 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
2c140 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
2c150 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
2c160 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
2c170 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
2c180 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
2c190 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
2c1a0 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
2c1b0 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
2c1c0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
2c1d0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
2c1e0 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
2c1f0 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
2c200 6e 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74  n an.** explicit
2c210 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
2c220 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
2c230 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
2c240 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
2c250 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
2c260 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
2c270 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
2c280 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
2c290 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
2c2a0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
2c2b0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
2c2c0 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
2c2d0 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
2c2e0 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
2c2f0 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
2c300 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
2c310 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c320 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
2c330 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
2c340 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
2c350 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
2c360 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
2c370 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
2c380 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
2c390 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
2c3a0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
2c3b0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
2c3c0 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
2c3d0 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
2c3e0 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
2c3f0 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
2c400 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
2c410 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
2c420 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
2c430 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
2c440 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
2c450 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
2c460 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
2c470 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
2c480 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
2c490 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
2c4a0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
2c4b0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
2c4c0 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
2c4d0 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
2c4e0 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
2c4f0 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
2c500 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
2c510 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
2c520 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
2c530 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
2c540 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c550 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
2c560 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
2c570 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
2c580 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
2c590 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
2c5a0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
2c5b0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
2c5c0 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
2c5d0 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
2c5e0 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
2c5f0 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
2c600 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
2c610 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
2c620 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
2c630 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
2c640 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
2c650 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
2c660 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
2c670 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
2c680 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
2c690 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
2c6a0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
2c6b0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
2c6c0 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
2c6d0 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
2c6e0 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
2c6f0 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
2c700 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
2c710 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2c720 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
2c730 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
2c740 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2c750 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
2c760 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
2c770 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
2c780 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
2c790 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
2c7a0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
2c7b0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
2c7c0 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
2c7d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
2c7e0 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
2c7f0 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
2c800 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
2c810 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
2c820 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
2c830 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
2c840 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
2c850 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
2c860 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
2c870 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
2c880 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
2c890 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
2c8a0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
2c8b0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
2c8c0 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
2c8d0 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
2c8e0 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
2c8f0 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
2c900 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
2c910 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
2c920 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c930 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
2c940 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
2c950 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
2c960 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
2c970 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
2c980 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
2c990 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
2c9a0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
2c9b0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
2c9c0 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
2c9d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
2c9e0 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
2c9f0 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
2ca00 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
2ca10 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
2ca20 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
2ca30 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
2ca40 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
2ca50 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
2ca60 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
2ca70 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
2ca80 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
2ca90 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
2caa0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
2cab0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
2cac0 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
2cad0 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
2cae0 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
2caf0 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
2cb00 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
2cb10 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
2cb20 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
2cb30 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
2cb40 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
2cb50 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
2cb60 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
2cb70 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
2cb80 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
2cb90 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
2cba0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
2cbb0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
2cbc0 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2cbd0 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
2cbe0 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
2cbf0 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
2cc00 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
2cc10 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
2cc20 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
2cc30 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
2cc40 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
2cc50 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
2cc60 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
2cc70 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
2cc80 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
2cc90 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
2cca0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
2ccb0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
2ccc0 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
2ccd0 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
2cce0 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
2ccf0 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
2cd00 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
2cd10 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
2cd20 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
2cd30 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
2cd40 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
2cd50 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
2cd60 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
2cd70 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
2cd80 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2cd90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
2cda0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
2cdb0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
2cdc0 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
2cdd0 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
2cde0 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
2cdf0 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
2ce00 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2ce10 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2ce20 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
2ce30 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
2ce40 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
2ce50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
2ce60 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
2ce70 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
2ce80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2ce90 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
2cea0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
2ceb0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
2cec0 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
2ced0 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
2cee0 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
2cef0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2cf00 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
2cf10 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
2cf20 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
2cf30 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
2cf40 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
2cf50 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
2cf60 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2cf70 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
2cf80 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
2cf90 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
2cfa0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
2cfb0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
2cfc0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
2cfd0 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
2cfe0 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
2cff0 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
2d000 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e  LL pointer..** ^
2d010 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
2d020 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e  _count(P) routin
2d030 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74  e returns 0 if t
2d040 68 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c  he previous call
2d050 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
2d060 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2d070 64 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  d [SQLITE_DONE].
2d080 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64    ^The sqlite3_d
2d090 61 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20  ata_count(P).** 
2d0a0 77 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d  will return non-
2d0b0 7a 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73  zero if previous
2d0c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
2d0d0 33 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72  3_step](P) retur
2d0e0 6e 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52  ned.** [SQLITE_R
2d0f0 4f 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74  OW], except in t
2d100 68 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b  he case of the [
2d110 50 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74  PRAGMA increment
2d120 61 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68  al_vacuum].** wh
2d130 65 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65  ere it always re
2d140 74 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65  turns zero since
2d150 20 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68   each step of th
2d160 61 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a  at multi-step.**
2d170 20 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20   pragma returns 
2d180 30 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74  0 columns of dat
2d190 61 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  a..**.** See als
2d1a0 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  o: [sqlite3_colu
2d1b0 6d 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  mn_count()].*/.i
2d1c0 6e 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  nt sqlite3_data_
2d1d0 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
2d1e0 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
2d1f0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e  ** CAPI3REF: Fun
2d200 64 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70  damental Datatyp
2d210 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  es.** KEYWORDS: 
2d220 53 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a  SQLITE_TEXT.**.*
2d230 2a 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20  * ^(Every value 
2d240 69 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e  in SQLite has on
2d250 65 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d  e of five fundam
2d260 65 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a  ental datatypes:
2d270 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
2d280 6c 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65  li> 64-bit signe
2d290 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69  d integer.** <li
2d2a0 3e 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c  > 64-bit IEEE fl
2d2b0 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d  oating point num
2d2c0 62 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69  ber.** <li> stri
2d2d0 6e 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a  ng.** <li> BLOB.
2d2e0 2a 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20  ** <li> NULL.** 
2d2f0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68  </ul>)^.**.** Th
2d300 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
2d310 65 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68  e codes for each
2d320 20 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e   of those types.
2d330 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  .**.** Note that
2d340 20 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54   the SQLITE_TEXT
2d350 20 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c   constant was al
2d360 73 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74  so used in SQLit
2d370 65 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66  e version 2.** f
2d380 6f 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20  or a completely 
2d390 64 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e  different meanin
2d3a0 67 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61  g.  Software tha
2d3b0 74 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20  t links against 
2d3c0 62 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76  both.** SQLite v
2d3d0 65 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c  ersion 2 and SQL
2d3e0 69 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68  ite version 3 sh
2d3f0 6f 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33  ould use SQLITE3
2d400 5f 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51  _TEXT, not.** SQ
2d410 4c 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64  LITE_TEXT..*/.#d
2d420 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54  efine SQLITE_INT
2d430 45 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20  EGER  1.#define 
2d440 53 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20  SQLITE_FLOAT    
2d450 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  2.#define SQLITE
2d460 5f 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66  _BLOB     4.#def
2d470 69 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20  ine SQLITE_NULL 
2d480 20 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c      5.#ifdef SQL
2d490 49 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66  ITE_TEXT.# undef
2d4a0 20 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c   SQLITE_TEXT.#el
2d4b0 73 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49  se.# define SQLI
2d4c0 54 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65  TE_TEXT     3.#e
2d4d0 6e 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c  ndif.#define SQL
2d4e0 49 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a  ITE3_TEXT     3.
2d4f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2d500 20 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46   Result Values F
2d510 72 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b  rom A Query.** K
2d520 45 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e  EYWORDS: {column
2d530 20 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e   access function
2d540 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  s}.**.** These r
2d550 6f 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65  outines form the
2d560 20 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e   "result set" in
2d570 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e  terface..**.** ^
2d580 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2d590 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f  eturn informatio
2d5a0 6e 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65  n about a single
2d5b0 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63   column of the c
2d5c0 75 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74  urrent.** result
2d5d0 20 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e   row of a query.
2d5e0 20 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65    ^In every case
2d5f0 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2d600 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
2d610 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70  .** to the [prep
2d620 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2d630 74 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76  that is being ev
2d640 61 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71  aluated (the [sq
2d650 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20  lite3_stmt*].** 
2d660 74 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65  that was returne
2d670 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
2d680 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
2d690 20 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69   one of its vari
2d6a0 61 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65  ants).** and the
2d6b0 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
2d6c0 20 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66   is the index of
2d6d0 20 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20   the column for 
2d6e0 77 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f  which informatio
2d6f0 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72  n.** should be r
2d700 65 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65  eturned. ^The le
2d710 66 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66  ftmost column of
2d720 20 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20   the result set 
2d730 68 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e  has the index 0.
2d740 0a 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20  .** ^The number 
2d750 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
2d760 65 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20  e result can be 
2d770 64 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67  determined using
2d780 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
2d790 75 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a  umn_count()]..**
2d7a0 0a 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73  .** If the SQL s
2d7b0 74 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f  tatement does no
2d7c0 74 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e  t currently poin
2d7d0 74 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77  t to a valid row
2d7e0 2c 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63  , or if the.** c
2d7f0 6f 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f  olumn index is o
2d800 75 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65  ut of range, the
2d810 20 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66   result is undef
2d820 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72  ined..** These r
2d830 6f 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79  outines may only
2d840 20 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20   be called when 
2d850 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2d860 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d870 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
2d880 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
2d890 5f 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65  _ROW] and neithe
2d8a0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  r.** [sqlite3_re
2d8b0 73 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69  set()] nor [sqli
2d8c0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2d8d0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
2d8e0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a   subsequently..*
2d8f0 2a 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73  * If any of thes
2d900 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63  e routines are c
2d910 61 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c  alled after [sql
2d920 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
2d930 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  .** [sqlite3_fin
2d940 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65  alize()] or afte
2d950 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
2d960 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a  )] has returned.
2d970 2a 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68  ** something oth
2d980 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
2d990 52 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74  ROW], the result
2d9a0 73 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e  s are undefined.
2d9b0 0a 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f  .** If [sqlite3_
2d9c0 73 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69  step()] or [sqli
2d9d0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2d9e0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2d9f0 65 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c  e()].** are call
2da00 65 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72  ed from a differ
2da10 65 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65  ent thread while
2da20 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f   any of these ro
2da30 75 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65  utines.** are pe
2da40 6e 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20  nding, then the 
2da50 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
2da60 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
2da70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2da80 5f 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20  _type() routine 
2da90 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b  returns the.** [
2daa0 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2dab0 20 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20   datatype code] 
2dac0 66 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20  for the initial 
2dad0 64 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20  data type.** of 
2dae0 74 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  the result colum
2daf0 6e 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65  n.  ^The returne
2db00 64 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f  d value is one o
2db10 66 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  f [SQLITE_INTEGE
2db20 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46  R],.** [SQLITE_F
2db30 4c 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54  LOAT], [SQLITE_T
2db40 45 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c  EXT], [SQLITE_BL
2db50 4f 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  OB], or [SQLITE_
2db60 4e 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75  NULL].  The valu
2db70 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79  e.** returned by
2db80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2db90 74 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d  type() is only m
2dba0 65 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20  eaningful if no 
2dbb0 74 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69  type.** conversi
2dbc0 6f 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65  ons have occurre
2dbd0 64 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62  d as described b
2dbe0 65 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74  elow.  After a t
2dbf0 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a  ype conversion,.
2dc00 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  ** the value ret
2dc10 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
2dc20 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
2dc30 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75  s undefined.  Fu
2dc40 74 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73  ture.** versions
2dc50 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63   of SQLite may c
2dc60 68 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69  hange the behavi
2dc70 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f  or of sqlite3_co
2dc80 6c 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66  lumn_type().** f
2dc90 6f 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20  ollowing a type 
2dca0 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a  conversion..**.*
2dcb0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2dcc0 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54   is a BLOB or UT
2dcd0 46 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20  F-8 string then 
2dce0 74 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  the sqlite3_colu
2dcf0 6d 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f  mn_bytes().** ro
2dd00 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
2dd10 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
2dd20 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
2dd30 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
2dd40 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2dd50 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20   UTF-16 string, 
2dd60 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2dd70 75 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76  umn_bytes() conv
2dd80 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
2dd90 6e 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20  ng to UTF-8 and 
2dda0 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65  then returns the
2ddb0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2ddc0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
2ddd0 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63  ult is a numeric
2dde0 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69   value then sqli
2ddf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2de00 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69  () uses.** [sqli
2de10 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20  te3_snprintf()] 
2de20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20  to convert that 
2de30 76 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38  value to a UTF-8
2de40 20 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75   string and retu
2de50 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  rns.** the numbe
2de60 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
2de70 61 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49  at string..** ^I
2de80 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2de90 4e 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74  NULL, then sqlit
2dea0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2deb0 29 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a  ) returns zero..
2dec0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  **.** ^If the re
2ded0 73 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f  sult is a BLOB o
2dee0 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20  r UTF-16 string 
2def0 74 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33  then the sqlite3
2df00 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2df10 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
2df20 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2df30 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2df40 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e   BLOB or string.
2df50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2df60 6c 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74  lt is a UTF-8 st
2df70 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74  ring, then sqlit
2df80 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2df90 36 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  6() converts.** 
2dfa0 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
2dfb0 46 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65  F-16 and then re
2dfc0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
2dfd0 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
2dfe0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
2dff0 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
2e000 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2e010 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73  umn_bytes16() us
2e020 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  es.** [sqlite3_s
2e030 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f  nprintf()] to co
2e040 6e 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65  nvert that value
2e050 20 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72   to a UTF-16 str
2e060 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a  ing and returns.
2e070 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
2e080 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73   bytes in that s
2e090 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68  tring..** ^If th
2e0a0 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c  e result is NULL
2e0b0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63  , then sqlite3_c
2e0c0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2e0d0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2e0e0 0a 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20  .** ^The values 
2e0f0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e100 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2e110 73 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  s()] and .** [sq
2e120 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e130 65 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69  es16()] do not i
2e140 6e 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20  nclude the zero 
2e150 74 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74  terminators at t
2e160 68 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65  he end.** of the
2e170 20 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63   string.  ^For c
2e180 6c 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75  larity: the valu
2e190 65 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  es returned by.*
2e1a0 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2e1b0 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b  n_bytes()] and [
2e1c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2e1d0 79 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68  ytes16()] are th
2e1e0 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62  e number of.** b
2e1f0 79 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69  ytes in the stri
2e200 6e 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62  ng, not the numb
2e210 65 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73  er of characters
2e220 2e 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73  ..**.** ^Strings
2e230 20 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c   returned by sql
2e240 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2e250 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  () and sqlite3_c
2e260 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a  olumn_text16(),.
2e270 2a 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74  ** even empty st
2e280 72 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79  rings, are alway
2e290 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  s zero-terminate
2e2a0 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a  d.  ^The return.
2e2b0 2a 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71  ** value from sq
2e2c0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2e2d0 62 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c  b() for a zero-l
2e2e0 65 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20  ength BLOB is a 
2e2f0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a  NULL pointer..**
2e300 0a 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20  .** ^The object 
2e310 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
2e320 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75  ite3_column_valu
2e330 65 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75  e()] is an.** [u
2e340 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2e350 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2e360 2e 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65  .  An unprotecte
2e370 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  d sqlite3_value 
2e380 6f 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e  object.** may on
2e390 6c 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20  ly be used with 
2e3a0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61  [sqlite3_bind_va
2e3b0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
2e3c0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2e3d0 28 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b  ()]..** If the [
2e3e0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2e3f0 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e400 74 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  t returned by.**
2e410 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2e420 5f 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65  _value()] is use
2e430 64 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77  d in any other w
2e440 61 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61  ay, including ca
2e450 6c 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e  lls.** to routin
2e460 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
2e470 5f 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b  _value_int()], [
2e480 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2e490 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2e4a0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2e4b0 73 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62  s()], then the b
2e4c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
2e4d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ined..**.** Thes
2e4e0 65 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d  e routines attem
2e4f0 70 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  pt to convert th
2e500 65 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70  e value where ap
2e510 70 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72  propriate.  ^For
2e520 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20  .** example, if 
2e530 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70  the internal rep
2e540 72 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46  resentation is F
2e550 4c 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20  LOAT and a text 
2e560 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71  result.** is req
2e570 75 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33  uested, [sqlite3
2e580 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20  _snprintf()] is 
2e590 75 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20  used internally 
2e5a0 74 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a  to perform the.*
2e5b0 2a 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74  * conversion aut
2e5c0 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54  omatically.  ^(T
2e5d0 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62  he following tab
2e5e0 6c 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63  le details the c
2e5f0 6f 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68  onversions.** th
2e600 61 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a  at are applied:.
2e610 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
2e620 65 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72  e>.** <table bor
2e630 64 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e  der="1">.** <tr>
2e640 3c 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72  <th> Internal<br
2e650 3e 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65  >Type <th> Reque
2e660 73 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68  sted<br>Type <th
2e670 3e 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a  >  Conversion.**
2e680 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55  .** <tr><td>  NU
2e690 4c 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47  LL    <td> INTEG
2e6a0 45 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74  ER   <td> Result
2e6b0 20 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64   is 0.** <tr><td
2e6c0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
2e6d0 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52   FLOAT    <td> R
2e6e0 65 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20  esult is 0.0.** 
2e6f0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e700 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
2e710 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e720 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2e730 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2e740 20 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20      <td>   BLOB 
2e750 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2e760 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
2e770 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54  .** <tr><td> INT
2e780 45 47 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41  EGER  <td>  FLOA
2e790 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
2e7a0 74 20 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74  t from integer t
2e7b0 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c  o float.** <tr><
2e7c0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64  td> INTEGER  <td
2e7d0 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2e7e0 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2e7f0 20 6f 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a   of the integer.
2e800 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45  ** <tr><td> INTE
2e810 47 45 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  GER  <td>   BLOB
2e820 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
2e830 20 49 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a   INTEGER->TEXT.*
2e840 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41  * <tr><td>  FLOA
2e850 54 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52  T   <td> INTEGER
2e860 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74     <td> [CAST] t
2e870 6f 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72  o INTEGER.** <tr
2e880 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2e890 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
2e8a0 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
2e8b0 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
2e8c0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
2e8d0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
2e8e0 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20      <td> [CAST] 
2e8f0 74 6f 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c  to BLOB.** <tr><
2e900 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2e910 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
2e920 20 5b 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47   [CAST] to INTEG
2e930 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  ER.** <tr><td>  
2e940 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c  TEXT    <td>  FL
2e950 4f 41 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53  OAT    <td> [CAS
2e960 54 5d 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74  T] to REAL.** <t
2e970 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20  r><td>  TEXT    
2e980 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2e990 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a  td> No change.**
2e9a0 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20   <tr><td>  BLOB 
2e9b0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
2e9c0 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e9d0 20 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e   INTEGER.** <tr>
2e9e0 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
2e9f0 64 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64  d>  FLOAT    <td
2ea00 3e 20 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c  > [CAST] to REAL
2ea10 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2ea20 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2ea30 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2ea40 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2ea50 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2ea60 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2ea70 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2ea80 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2ea90 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2eaa0 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2eab0 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2eac0 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2ead0 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2eae0 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2eaf0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2eb00 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2eb10 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2eb20 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2eb30 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2eb40 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2eb50 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2eb60 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2eb70 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2eb80 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2eb90 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2eba0 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2ebb0 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2ebc0 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2ebd0 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2ebe0 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2ebf0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2ec00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ec10 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2ec20 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2ec30 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2ec40 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ec50 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2ec60 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2ec70 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2ec80 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2ec90 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2eca0 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2ecb0 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2ecc0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2ecd0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2ece0 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2ecf0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2ed00 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2ed10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ed20 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2ed30 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2ed40 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2ed50 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2ed60 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2ed70 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2ed80 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2ed90 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2eda0 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2edb0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2edc0 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2edd0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2ede0 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2edf0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2ee00 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2ee10 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2ee20 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2ee30 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2ee40 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2ee50 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2ee60 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2ee70 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2ee80 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2ee90 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2eea0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2eeb0 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2eec0 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2eed0 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2eee0 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2eef0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2ef00 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2ef10 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2ef20 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2ef30 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2ef40 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2ef50 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2ef60 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2ef70 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2ef80 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2ef90 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2efa0 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2efb0 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2efc0 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2efd0 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2efe0 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2eff0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2f000 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2f010 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2f020 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2f030 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2f040 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2f050 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2f060 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2f070 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2f080 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2f090 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2f0a0 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2f0b0 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2f0c0 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2f0d0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2f0e0 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2f0f0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2f100 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2f110 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2f120 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2f130 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2f140 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2f150 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2f160 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2f170 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2f180 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2f190 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2f1a0 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2f1b0 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2f1c0 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2f1d0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2f1e0 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2f1f0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2f200 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2f210 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2f220 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2f230 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2f240 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2f250 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2f260 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2f270 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2f280 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2f290 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2f2a0 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2f2b0 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2f2c0 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2f2d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2f2e0 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2f2f0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2f300 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2f310 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2f320 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2f330 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2f340 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f350 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2f360 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2f370 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2f380 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2f390 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2f3a0 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2f3b0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2f3c0 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2f3d0 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2f3e0 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2f3f0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2f400 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2f410 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2f420 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2f430 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2f440 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2f450 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2f460 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2f470 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2f480 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2f490 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2f4a0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2f4b0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f4c0 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  lob()], [sqlite3
2f4d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c  _column_text()],
2f4e0 20 65 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73   etc. into.** [s
2f4f0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a  qlite3_free()]..
2f500 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d  **.** ^(If a mem
2f510 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65  ory allocation e
2f520 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69  rror occurs duri
2f530 6e 67 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f  ng the evaluatio
2f540 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74  n of any.** of t
2f550 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61  hese routines, a
2f560 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69   default value i
2f570 73 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65  s returned.  The
2f580 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a   default value.*
2f590 2a 20 69 73 20 65 69 74 68 65 72 20 74 68 65 20  * is either the 
2f5a0 69 6e 74 65 67 65 72 20 30 2c 20 74 68 65 20 66  integer 0, the f
2f5b0 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75  loating point nu
2f5c0 6d 62 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e  mber 0.0, or a N
2f5d0 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20  ULL.** pointer. 
2f5e0 20 53 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c   Subsequent call
2f5f0 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72  s to [sqlite3_er
2f600 72 63 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65  rcode()] will re
2f610 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  turn.** [SQLITE_
2f620 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e  NOMEM].)^.*/.con
2f630 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f640 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c  _column_blob(sql
2f650 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f660 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2f670 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f680 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2f690 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2f6a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2f6b0 65 73 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d  es16(sqlite3_stm
2f6c0 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64  t*, int iCol);.d
2f6d0 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f  ouble sqlite3_co
2f6e0 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69  lumn_double(sqli
2f6f0 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69  te3_stmt*, int i
2f700 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  Col);.int sqlite
2f710 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c  3_column_int(sql
2f720 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f730 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69  iCol);.sqlite3_i
2f740 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c  nt64 sqlite3_col
2f750 75 6d 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  umn_int64(sqlite
2f760 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f770 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  l);.const unsign
2f780 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2f790 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c  _column_text(sql
2f7a0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2f7b0 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  iCol);.const voi
2f7c0 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
2f7d0 6e 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33  n_text16(sqlite3
2f7e0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f7f0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2f800 6f 6c 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74  olumn_type(sqlit
2f810 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f820 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c  ol);.sqlite3_val
2f830 75 65 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ue *sqlite3_colu
2f840 6d 6e 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33  mn_value(sqlite3
2f850 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f860 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f870 45 46 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72  EF: Destroy A Pr
2f880 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
2f890 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54   Object.**.** ^T
2f8a0 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  he sqlite3_final
2f8b0 69 7a 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69  ize() function i
2f8c0 73 20 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65  s called to dele
2f8d0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
2f8e0 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49  tatement]..** ^I
2f8f0 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2f900 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2f910 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e  the statement en
2f920 63 6f 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72  countered no err
2f930 6f 72 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65  ors.** or if the
2f940 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65   statement is ne
2f950 76 65 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74  ver been evaluat
2f960 65 64 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ed, then sqlite3
2f970 5f 66 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75  _finalize() retu
2f980 72 6e 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b  rns.** SQLITE_OK
2f990 2e 20 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  .  ^If the most 
2f9a0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
2f9b0 6e 20 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53  n of statement S
2f9c0 20 66 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a   failed, then.**
2f9d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f9e0 65 28 53 29 20 72 65 74 75 72 6e 73 20 74 68 65  e(S) returns the
2f9f0 20 61 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72   appropriate [er
2fa00 72 6f 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ror code] or.** 
2fa10 5b 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20  [extended error 
2fa20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  code]..**.** ^Th
2fa30 65 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  e sqlite3_finali
2fa40 7a 65 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61  ze(S) routine ca
2fa50 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61  n be called at a
2fa60 6e 79 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a  ny point during.
2fa70 2a 2a 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c  ** the life cycl
2fa80 65 20 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73  e of [prepared s
2fa90 74 61 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20  tatement] S:.** 
2faa0 62 65 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74  before statement
2fab0 20 53 20 69 73 20 65 76 65 72 20 65 76 61 6c 75   S is ever evalu
2fac0 61 74 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f  ated, after.** o
2fad0 6e 65 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73  ne or more calls
2fae0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
2faf0 65 74 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20  et()], or after 
2fb00 61 6e 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b  any call.** to [
2fb10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
2fb20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
2fb30 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
2fb40 20 73 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a   statement has.*
2fb50 2a 20 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63  * completed exec
2fb60 75 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ution..**.** ^In
2fb70 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66  voking sqlite3_f
2fb80 69 6e 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e  inalize() on a N
2fb90 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61  ULL pointer is a
2fba0 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e   harmless no-op.
2fbb0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69  .**.** The appli
2fbc0 63 61 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61  cation must fina
2fbd0 6c 69 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70  lize every [prep
2fbe0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2fbf0 69 6e 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69  in order to avoi
2fc00 64 0a 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65  d.** resource le
2fc10 61 6b 73 2e 20 20 49 74 20 69 73 20 61 20 67 72  aks.  It is a gr
2fc20 69 65 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72  ievous error for
2fc30 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fc40 20 74 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a   to try to use.*
2fc50 2a 20 61 20 70 72 65 70 61 72 65 64 20 73 74 61  * a prepared sta
2fc60 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20  tement after it 
2fc70 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
2fc80 65 64 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20  ed.  Any use of 
2fc90 61 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  a prepared.** st
2fca0 61 74 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74  atement after it
2fcb0 20 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69   has been finali
2fcc0 7a 65 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69  zed can result i
2fcd0 6e 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a  n undefined and.
2fce0 2a 2a 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62  ** undesirable b
2fcf0 65 68 61 76 69 6f 72 20 73 75 63 68 20 61 73 20  ehavior such as 
2fd00 73 65 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65  segfaults and he
2fd10 61 70 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a  ap corruption..*
2fd20 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69  /.int sqlite3_fi
2fd30 6e 61 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73  nalize(sqlite3_s
2fd40 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
2fd50 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
2fd60 73 65 74 20 41 20 50 72 65 70 61 72 65 64 20 53  set A Prepared S
2fd70 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
2fd80 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
2fd90 33 5f 72 65 73 65 74 28 29 20 66 75 6e 63 74 69  3_reset() functi
2fda0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2fdb0 72 65 73 65 74 20 61 20 5b 70 72 65 70 61 72 65  reset a [prepare
2fdc0 64 20 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20  d statement].** 
2fdd0 6f 62 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69  object back to i
2fde0 74 73 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65  ts initial state
2fdf0 2c 20 72 65 61 64 79 20 74 6f 20 62 65 20 72 65  , ready to be re
2fe00 2d 65 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41  -executed..** ^A
2fe10 6e 79 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ny SQL statement
2fe20 20 76 61 72 69 61 62 6c 65 73 20 74 68 61 74 20   variables that 
2fe30 68 61 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64  had values bound
2fe40 20 74 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a   to them using.*
2fe50 2a 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62  * the [sqlite3_b
2fe60 69 6e 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74  ind_blob | sqlit
2fe70 65 33 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d  e3_bind_*() API]
2fe80 20 72 65 74 61 69 6e 20 74 68 65 69 72 20 76 61   retain their va
2fe90 6c 75 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71  lues..** Use [sq
2fea0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
2feb0 69 6e 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74  ings()] to reset
2fec0 20 74 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a   the bindings..*
2fed0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2fee0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2fef0 65 72 66 61 63 65 20 72 65 73 65 74 73 20 74 68  erface resets th
2ff00 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
2ff10 65 6d 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b  ement] S.** back
2ff20 20 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   to the beginnin
2ff30 67 20 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d  g of its program
2ff40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
2ff50 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c  most recent call
2ff60 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   to [sqlite3_ste
2ff70 70 28 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a  p(S)] for the.**
2ff80 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
2ff90 6d 65 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64  ment] S returned
2ffa0 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72   [SQLITE_ROW] or
2ffb0 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a   [SQLITE_DONE],.
2ffc0 2a 2a 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65  ** or if [sqlite
2ffd0 33 5f 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e  3_step(S)] has n
2ffe0 65 76 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e  ever before been
2fff0 20 63 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a   called on S,.**
30000 20 74 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72   then [sqlite3_r
30010 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73  eset(S)] returns
30020 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a   [SQLITE_OK]..**
30030 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74  .** ^If the most
30040 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20   recent call to 
30050 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
30060 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72  ] for the.** [pr
30070 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30080 5d 20 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e  ] S indicated an
30090 20 65 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20   error, then.** 
300a0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
300b0 29 5d 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70  )] returns an ap
300c0 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
300d0 20 63 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54   code]..**.** ^T
300e0 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  he [sqlite3_rese
300f0 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20  t(S)] interface 
30100 64 6f 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20  does not change 
30110 74 68 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66  the values.** of
30120 20 61 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69   any [sqlite3_bi
30130 6e 64 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73  nd_blob|bindings
30140 5d 20 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] on the [prepar
30150 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e  ed statement] S.
30160 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
30170 72 65 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74  reset(sqlite3_st
30180 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
30190 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 72 65  ** CAPI3REF: Cre
301a0 61 74 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20  ate Or Redefine 
301b0 53 51 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  SQL Functions.**
301c0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63   KEYWORDS: {func
301d0 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f  tion creation ro
301e0 75 74 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f  utines}.** KEYWO
301f0 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30200 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30210 6e 63 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f  nction}.** KEYWO
30220 52 44 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f  RDS: {applicatio
30230 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
30240 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e  nctions}.**.** ^
30250 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
30260 28 63 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e  (collectively kn
30270 6f 77 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e  own as "function
30280 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e   creation routin
30290 65 73 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64  es").** are used
302a0 20 74 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63   to add SQL func
302b0 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61  tions or aggrega
302c0 74 65 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69  tes or to redefi
302d0 6e 65 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a  ne the behavior.
302e0 2a 2a 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53  ** of existing S
302f0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
30300 61 67 67 72 65 67 61 74 65 73 2e 20 20 54 68 65  aggregates.  The
30310 20 6f 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65   only difference
30320 73 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65  s between.** the
30330 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
30340 74 68 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  the text encodin
30350 67 20 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a  g expected for.*
30360 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * the second par
30370 61 6d 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65  ameter (the name
30380 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
30390 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a   being created).
303a0 2a 2a 20 61 6e 64 20 74 68 65 20 70 72 65 73 65  ** and the prese
303b0 6e 63 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f  nce or absence o
303c0 66 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 63  f a destructor c
303d0 61 6c 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74  allback for.** t
303e0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
303f0 61 74 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ata pointer..**.
30400 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  ** ^The first pa
30410 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
30420 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
30430 69 6f 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68  ion] to which th
30440 65 20 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f  e SQL.** functio
30450 6e 20 69 73 20 74 6f 20 62 65 20 61 64 64 65 64  n is to be added
30460 2e 20 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63  .  ^If an applic
30470 61 74 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20  ation uses more 
30480 74 68 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73  than one databas
30490 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e.** connection 
304a0 74 68 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  then application
304b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
304c0 63 74 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61  ctions must be a
304d0 64 64 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20  dded.** to each 
304e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
304f0 69 6f 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a  ion separately..
30500 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e  **.** ^The secon
30510 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
30520 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53  he name of the S
30530 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  QL function to b
30540 65 20 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20  e created or.** 
30550 72 65 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65  redefined.  ^The
30560 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e   length of the n
30570 61 6d 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74  ame is limited t
30580 6f 20 32 35 35 20 62 79 74 65 73 20 69 6e 20 61  o 255 bytes in a
30590 20 55 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73   UTF-8.** repres
305a0 65 6e 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73  entation, exclus
305b0 69 76 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d  ive of the zero-
305c0 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f  terminator.  ^No
305d0 74 65 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65  te that the name
305e0 0a 2a 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74  .** length limit
305f0 20 69 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74   is in UTF-8 byt
30600 65 73 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65  es, not characte
30610 72 73 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79  rs nor UTF-16 by
30620 74 65 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61  tes.  .** ^Any a
30630 74 74 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65  ttempt to create
30640 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68   a function with
30650 20 61 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a   a longer name.*
30660 2a 20 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e  * will result in
30670 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d   [SQLITE_MISUSE]
30680 20 62 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e   being returned.
30690 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
306a0 64 20 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72  d parameter (nAr
306b0 67 29 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d  g).** is the num
306c0 62 65 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73  ber of arguments
306d0 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 66 75   that the SQL fu
306e0 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67  nction or.** agg
306f0 72 65 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49  regate takes. ^I
30700 66 20 74 68 69 73 20 70 61 72 61 6d 65 74 65 72  f this parameter
30710 20 69 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65   is -1, then the
30720 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
30730 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61  .** aggregate ma
30740 79 20 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65  y take any numbe
30750 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62  r of arguments b
30760 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65  etween 0 and the
30770 20 6c 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79   limit.** set by
30780 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d   [sqlite3_limit]
30790 28 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46  ([SQLITE_LIMIT_F
307a0 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20  UNCTION_ARG]).  
307b0 49 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  If the third.** 
307c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73  parameter is les
307d0 73 20 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65  s than -1 or gre
307e0 61 74 65 72 20 74 68 61 6e 20 31 32 37 20 74 68  ater than 127 th
307f0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
30800 69 73 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e  is.** undefined.
30810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72  .**.** ^The four
30820 74 68 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54  th parameter, eT
30830 65 78 74 52 65 70 2c 20 73 70 65 63 69 66 69 65  extRep, specifie
30840 73 20 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54  s what.** [SQLIT
30850 45 5f 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e  E_UTF8 | text en
30860 63 6f 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c  coding] this SQL
30870 20 66 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72   function prefer
30880 73 20 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72  s for.** its par
30890 61 6d 65 74 65 72 73 2e 20 20 54 68 65 20 61 70  ameters.  The ap
308a0 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
308b0 20 73 65 74 20 74 68 69 73 20 70 61 72 61 6d 65   set this parame
308c0 74 65 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54  ter to.** [SQLIT
308d0 45 5f 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68  E_UTF16LE] if th
308e0 65 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  e function imple
308f0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65  mentation invoke
30900 73 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76  s .** [sqlite3_v
30910 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d  alue_text16le()]
30920 20 6f 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72   on an input, or
30930 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45   [SQLITE_UTF16BE
30940 5d 20 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c  ] if the.** impl
30950 65 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b  ementation invok
30960 65 73 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  es [sqlite3_valu
30970 65 5f 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e  e_text16be()] on
30980 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a   an input, or.**
30990 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20   [SQLITE_UTF16] 
309a0 69 66 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  if [sqlite3_valu
309b0 65 5f 74 65 78 74 31 36 28 29 5d 20 69 73 20 75  e_text16()] is u
309c0 73 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f  sed, or [SQLITE_
309d0 55 54 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69  UTF8].** otherwi
309e0 73 65 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53  se.  ^The same S
309f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20  QL function may 
30a00 62 65 20 72 65 67 69 73 74 65 72 65 64 20 6d 75  be registered mu
30a10 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69  ltiple times usi
30a20 6e 67 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20  ng.** different 
30a30 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65  preferred text e
30a40 6e 63 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64  ncodings, with d
30a50 69 66 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65  ifferent impleme
30a60 6e 74 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20  ntations for.** 
30a70 65 61 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a  each encoding..*
30a80 2a 20 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65  * ^When multiple
30a90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
30aa0 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e   of the same fun
30ab0 63 74 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61  ction are availa
30ac0 62 6c 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77  ble, SQLite.** w
30ad0 69 6c 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65  ill pick the one
30ae0 20 74 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74   that involves t
30af0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
30b00 6f 66 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69  of data conversi
30b10 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  on..**.** ^The f
30b20 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
30b30 6d 61 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62  may optionally b
30b40 65 20 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c  e ORed with [SQL
30b50 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49  ITE_DETERMINISTI
30b60 43 5d 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20  C].** to signal 
30b70 74 68 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f  that the functio
30b80 6e 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65  n will always re
30b90 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65  turn the same re
30ba0 73 75 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68  sult given.** th
30bb0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69  e same inputs wi
30bc0 74 68 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51  thin a single SQ
30bd0 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f  L statement.  Mo
30be0 73 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  st SQL functions
30bf0 20 61 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e   are.** determin
30c00 69 73 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c  istic.  The buil
30c10 74 2d 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20  t-in [random()] 
30c20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
30c30 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a  an example of a.
30c40 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  ** function that
30c50 20 69 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e   is not determin
30c60 69 73 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69  istic.  The SQLi
30c70 74 65 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72  te query planner
30c80 20 69 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70   is able to.** p
30c90 65 72 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61  erform additiona
30ca0 6c 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20  l optimizations 
30cb0 6f 6e 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63  on deterministic
30cc0 20 66 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75   functions, so u
30cd0 73 65 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51  se.** of the [SQ
30ce0 4c 49 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54  LITE_DETERMINIST
30cf0 49 43 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f  IC] flag is reco
30d00 6d 6d 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f  mmended where po
30d10 73 73 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ssible..**.** ^(
30d20 54 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65  The fifth parame
30d30 74 65 72 20 69 73 20 61 6e 20 61 72 62 69 74 72  ter is an arbitr
30d40 61 72 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68  ary pointer.  Th
30d50 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  e implementation
30d60 20 6f 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74   of the.** funct
30d70 69 6f 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63  ion can gain acc
30d80 65 73 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e  ess to this poin
30d90 74 65 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ter using [sqlit
30da0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e  e3_user_data()].
30db0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69  )^.**.** ^The si
30dc0 78 74 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64  xth, seventh and
30dd0 20 65 69 67 68 74 68 20 70 61 72 61 6d 65 74 65   eighth paramete
30de0 72 73 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70  rs, xFunc, xStep
30df0 20 61 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65   and xFinal, are
30e00 0a 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  .** pointers to 
30e10 43 2d 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74  C-language funct
30e20 69 6f 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d  ions that implem
30e30 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  ent the SQL func
30e40 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30e50 67 61 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20  gate. ^A scalar 
30e60 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
30e70 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
30e80 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ntation of the x
30e90 46 75 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  Func.** callback
30ea0 20 6f 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e   only; NULL poin
30eb0 74 65 72 73 20 6d 75 73 74 20 62 65 20 70 61 73  ters must be pas
30ec0 73 65 64 20 61 73 20 74 68 65 20 78 53 74 65 70  sed as the xStep
30ed0 20 61 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70   and xFinal.** p
30ee0 61 72 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61  arameters. ^An a
30ef0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
30f00 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61  ction requires a
30f10 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
30f20 20 6f 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64   of xStep.** and
30f30 20 78 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c   xFinal and NULL
30f40 20 70 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65   pointer must be
30f50 20 70 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e   passed for xFun
30f60 63 2e 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e  c. ^To delete an
30f70 20 65 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c   existing.** SQL
30f80 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67   function or agg
30f90 72 65 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c  regate, pass NUL
30fa0 4c 20 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61  L pointers for a
30fb0 6c 6c 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f  ll three functio
30fc0 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a  n.** callbacks..
30fd0 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e  **.** ^(If the n
30fe0 69 6e 74 68 20 70 61 72 61 6d 65 74 65 72 20 74  inth parameter t
30ff0 6f 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  o sqlite3_create
31000 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69  _function_v2() i
31010 73 20 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74  s not NULL,.** t
31020 68 65 6e 20 69 74 20 69 73 20 64 65 73 74 72 75  hen it is destru
31030 63 74 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  ctor for the app
31040 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f  lication data po
31050 69 6e 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64  inter. .** The d
31060 65 73 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76  estructor is inv
31070 6f 6b 65 64 20 77 68 65 6e 20 74 68 65 20 66 75  oked when the fu
31080 6e 63 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65  nction is delete
31090 64 2c 20 65 69 74 68 65 72 20 62 79 20 62 65 69  d, either by bei
310a0 6e 67 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64  ng.** overloaded
310b0 20 6f 72 20 77 68 65 6e 20 74 68 65 20 64 61 74   or when the dat
310c0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
310d0 20 63 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54   closes.)^.** ^T
310e0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 69 73  he destructor is
310f0 20 61 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66   also invoked if
31100 20 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20   the call to.** 
31110 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
31120 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69  unction_v2() fai
31130 6c 73 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65  ls..** ^When the
31140 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c   destructor call
31150 62 61 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74  back of the tent
31160 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 69  h parameter is i
31170 6e 76 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73  nvoked, it.** is
31180 20 70 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65   passed a single
31190 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
311a0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
311b0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
311c0 61 20 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68  a .** pointer wh
311d0 69 63 68 20 77 61 73 20 74 68 65 20 66 69 66 74  ich was the fift
311e0 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  h parameter to s
311f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31200 6e 63 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  nction_v2()..**.
31210 2a 2a 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74  ** ^It is permit
31220 74 65 64 20 74 6f 20 72 65 67 69 73 74 65 72 20  ted to register 
31230 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65  multiple impleme
31240 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  ntations of the 
31250 73 61 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  same.** function
31260 73 20 77 69 74 68 20 74 68 65 20 73 61 6d 65 20  s with the same 
31270 6e 61 6d 65 20 62 75 74 20 77 69 74 68 20 65 69  name but with ei
31280 74 68 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e  ther differing n
31290 75 6d 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67  umbers of.** arg
312a0 75 6d 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72  uments or differ
312b0 69 6e 67 20 70 72 65 66 65 72 72 65 64 20 74 65  ing preferred te
312c0 78 74 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e  xt encodings.  ^
312d0 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a  SQLite will use.
312e0 2a 2a 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74  ** the implement
312f0 61 74 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20  ation that most 
31300 63 6c 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20  closely matches 
31310 74 68 65 20 77 61 79 20 69 6e 20 77 68 69 63 68  the way in which
31320 20 74 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63   the.** SQL func
31330 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e  tion is used.  ^
31340 41 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  A function imple
31350 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61  mentation with a
31360 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a   non-negative.**
31370 20 6e 41 72 67 20 70 61 72 61 6d 65 74 65 72 20   nArg parameter 
31380 69 73 20 61 20 62 65 74 74 65 72 20 6d 61 74 63  is a better matc
31390 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f  h than a functio
313a0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
313b0 20 77 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74   with.** a negat
313c0 69 76 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75  ive nArg.  ^A fu
313d0 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
313e0 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
313f0 65 6e 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63  encoding.** matc
31400 68 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  hes the database
31410 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62   encoding is a b
31420 65 74 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74  etter.** match t
31430 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77  han a function w
31440 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31450 67 20 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20  g is different. 
31460 20 0a 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e   .** ^A function
31470 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31480 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31490 73 20 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c  s between UTF16l
314a0 65 20 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a  e and UTF16be.**
314b0 20 69 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74   is a closer mat
314c0 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69  ch than a functi
314d0 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65 6e 63  on where the enc
314e0 6f 64 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65  oding difference
314f0 20 69 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55   is.** between U
31500 54 46 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a  TF8 and UTF16..*
31510 2a 0a 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66  *.** ^Built-in f
31520 75 6e 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20  unctions may be 
31530 6f 76 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65  overloaded by ne
31540 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  w application-de
31550 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e  fined functions.
31560 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69  .**.** ^An appli
31570 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
31580 75 6e 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69  unction is permi
31590 74 74 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68  tted to call oth
315a0 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
315b0 65 72 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65  erfaces.  Howeve
315c0 72 2c 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75  r, such calls mu
315d0 73 74 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20  st not.** close 
315e0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
315f0 6e 65 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61  nection nor fina
31600 6c 69 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68  lize or reset th
31610 65 20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74  e prepared.** st
31620 61 74 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68  atement in which
31630 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
31640 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74   running..*/.int
31650 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31660 66 75 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69  function(.  sqli
31670 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
31680 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e   char *zFunction
31690 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
316a0 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
316b0 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
316c0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
316d0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
316e0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
316f0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31700 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
31710 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31720 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31730 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
31740 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
31750 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
31760 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
31770 36 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  6(.  sqlite3 *db
31780 2c 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  ,.  const void *
31790 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
317a0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
317b0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
317c0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
317d0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
317e0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
317f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
31800 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
31810 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
31820 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
31830 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
31840 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
31850 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74  context*).);.int
31860 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31870 66 75 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73  function_v2(.  s
31880 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
31890 6e 73 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74  nst char *zFunct
318a0 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
318b0 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
318c0 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
318d0 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
318e0 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
318f0 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
31900 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
31910 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
31920 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
31930 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
31940 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
31950 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
31960 74 2a 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65  t*),.  void(*xDe
31970 73 74 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b  stroy)(void*).);
31980 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
31990 3a 20 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73  : Text Encodings
319a0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
319b0 73 74 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74  stant define int
319c0 65 67 65 72 20 63 6f 64 65 73 20 74 68 61 74 20  eger codes that 
319d0 72 65 70 72 65 73 65 6e 74 20 74 68 65 20 76 61  represent the va
319e0 72 69 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e  rious.** text en
319f0 63 6f 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65  codings supporte
31a00 64 20 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  d by SQLite..*/.
31a10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31a20 54 46 38 20 20 20 20 20 20 20 20 20 20 20 31 0a  TF8           1.
31a30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31a40 54 46 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a  TF16LE        2.
31a50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31a60 54 46 31 36 42 45 20 20 20 20 20 20 20 20 33 0a  TF16BE        3.
31a70 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55  #define SQLITE_U
31a80 54 46 31 36 20 20 20 20 20 20 20 20 20 20 34 20  TF16          4 
31a90 20 20 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65     /* Use native
31aa0 20 62 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23   byte order */.#
31ab0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e  define SQLITE_AN
31ac0 59 20 20 20 20 20 20 20 20 20 20 20 20 35 20 20  Y            5  
31ad0 20 20 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20    /* Deprecated 
31ae0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
31af0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20  E_UTF16_ALIGNED 
31b00 20 38 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33   8    /* sqlite3
31b10 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31b20 6e 20 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  n only */../*.**
31b30 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74   CAPI3REF: Funct
31b40 69 6f 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20  ion Flags.**.** 
31b50 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
31b60 6d 61 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65  may be ORed toge
31b70 74 68 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a  ther with the .*
31b80 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
31b90 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74 20   preferred text 
31ba0 65 6e 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65  encoding] as the
31bb0 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74   fourth argument
31bc0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
31bd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
31be0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
31bf0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
31c00 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
31c10 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
31c20 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66  n_v2()]..*/.#def
31c30 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52  ine SQLITE_DETER
31c40 4d 49 4e 49 53 54 49 43 20 20 20 20 30 78 38 30  MINISTIC    0x80
31c50 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
31c60 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
31c70 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
31c80 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
31c90 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
31ca0 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
31cb0 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
31cc0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
31cd0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
31ce0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
31cf0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
31d00 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
31d10 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
31d20 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
31d30 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
31d40 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
31d50 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
31d60 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
31d70 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
31d80 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
31d90 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
31da0 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
31db0 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
31dc0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
31dd0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
31de0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
31df0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
31e00 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
31e10 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
31e20 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
31e30 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
31e40 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
31e50 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
31e60 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
31e70 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
31e80 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
31e90 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
31ea0 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
31eb0 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
31ec0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
31ed0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
31ee0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
31ef0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
31f00 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
31f10 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
31f20 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31f30 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
31f40 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
31f50 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
31f60 6e 74 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20  nt64,int),.     
31f70 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
31f80 20 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69   void*,sqlite3_i
31f90 6e 74 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f  nt64);.#endif../
31fa0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
31fb0 62 74 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e  btaining SQL Fun
31fc0 63 74 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20  ction Parameter 
31fd0 56 61 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65  Values.**.** The
31fe0 20 43 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c   C-language impl
31ff0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51  ementation of SQ
32000 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20  L functions and 
32010 61 67 67 72 65 67 61 74 65 73 20 75 73 65 73 0a  aggregates uses.
32020 2a 2a 20 74 68 69 73 20 73 65 74 20 6f 66 20 69  ** this set of i
32030 6e 74 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65  nterface routine
32040 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65 20  s to access the 
32050 70 61 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73  parameter values
32060 20 6f 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74   on.** the funct
32070 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
32080 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e  ..**.** The xFun
32090 63 20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75  c (for scalar fu
320a0 6e 63 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65  nctions) or xSte
320b0 70 20 28 66 6f 72 20 61 67 67 72 65 67 61 74 65  p (for aggregate
320c0 73 29 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a  s) parameters.**
320d0 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65   to [sqlite3_cre
320e0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20  ate_function()] 
320f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  and [sqlite3_cre
32100 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29  ate_function16()
32110 5d 0a 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c  ].** define call
32120 62 61 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65  backs that imple
32130 6d 65 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e  ment the SQL fun
32140 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65  ctions and aggre
32150 67 61 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72  gates..** The 3r
32160 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
32170 68 65 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69  hese callbacks i
32180 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f  s an array of po
32190 69 6e 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72  inters to.** [pr
321a0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
321b0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20  value] objects. 
321c0 20 54 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73   There is one [s
321d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
321e0 6a 65 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68  ject for.** each
321f0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
32200 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20  e SQL function. 
32210 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
32220 61 72 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65  are used to.** e
32230 78 74 72 61 63 74 20 76 61 6c 75 65 73 20 66 72  xtract values fr
32240 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  om the [sqlite3_
32250 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
32260 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
32270 69 6e 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77  ines work only w
32280 69 74 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73  ith [protected s
32290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
322a0 6a 65 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74  jects..** Any at
322b0 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65  tempt to use the
322c0 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61  se routines on a
322d0 6e 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  n [unprotected s
322e0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
322f0 20 6f 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20   object results 
32300 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
32310 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  avior..**.** ^Th
32320 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72  ese routines wor
32330 6b 20 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20  k just like the 
32340 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63  corresponding [c
32350 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e  olumn access fun
32360 63 74 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70  ctions].** excep
32370 74 20 74 68 61 74 20 20 74 68 65 73 65 20 72 6f  t that  these ro
32380 75 74 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69  utines take a si
32390 6e 67 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20  ngle [protected 
323a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
323b0 62 6a 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72  bject.** pointer
323c0 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73   instead of a [s
323d0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f  qlite3_stmt*] po
323e0 69 6e 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74  inter and an int
323f0 65 67 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62  eger column numb
32400 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  er..**.** ^The s
32410 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
32420 74 31 36 28 29 20 69 6e 74 65 72 66 61 63 65 20  t16() interface 
32430 65 78 74 72 61 63 74 73 20 61 20 55 54 46 2d 31  extracts a UTF-1
32440 36 20 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74  6 string.** in t
32450 68 65 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f  he native byte-o
32460 72 64 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74  rder of the host
32470 20 6d 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a   machine.  ^The.
32480 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
32490 5f 74 65 78 74 31 36 62 65 28 29 20 61 6e 64 20  _text16be() and 
324a0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
324b0 78 74 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61  xt16le() interfa
324c0 63 65 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55  ces.** extract U
324d0 54 46 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73  TF-16 strings as
324e0 20 62 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20   big-endian and 
324f0 6c 69 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65  little-endian re
32500 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a  spectively..**.*
32510 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
32520 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
32530 70 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 61  pe() interface a
32540 74 74 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79  ttempts to apply
32550 0a 2a 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69  .** numeric affi
32560 6e 69 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75  nity to the valu
32570 65 2e 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74  e.  This means t
32580 68 61 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69  hat an attempt i
32590 73 0a 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e  s.** made to con
325a0 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20 74  vert the value t
325b0 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20  o an integer or 
325c0 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20  floating point. 
325d0 20 49 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f   If.** such a co
325e0 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73  nversion is poss
325f0 69 62 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73  ible without los
32600 73 20 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  s of information
32610 20 28 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f   (in other.** wo
32620 72 64 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75  rds, if the valu
32630 65 20 69 73 20 61 20 73 74 72 69 6e 67 20 74 68  e is a string th
32640 61 74 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20  at looks like a 
32650 6e 75 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20  number).** then 
32660 74 68 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  the conversion i
32670 73 20 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74  s performed.  Ot
32680 68 65 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65  herwise no conve
32690 72 73 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a  rsion occurs..**
326a0 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54   The [SQLITE_INT
326b0 45 47 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d  EGER | datatype]
326c0 20 61 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f   after conversio
326d0 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
326e0 0a 2a 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61  .**.** Please pa
326f0 79 20 70 61 72 74 69 63 75 6c 61 72 20 61 74 74  y particular att
32700 65 6e 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61  ention to the fa
32710 63 74 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e  ct that the poin
32720 74 65 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20  ter returned.** 
32730 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61  from [sqlite3_va
32740 6c 75 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  lue_blob()], [sq
32750 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32760 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
32770 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
32780 28 29 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c  ()] can be inval
32790 69 64 61 74 65 64 20 62 79 20 61 20 73 75 62 73  idated by a subs
327a0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a  equent call to.*
327b0 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  * [sqlite3_value
327c0 5f 62 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69  _bytes()], [sqli
327d0 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31  te3_value_bytes1
327e0 36 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  6()], [sqlite3_v
327f0 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a  alue_text()],.**
32800 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c   or [sqlite3_val
32810 75 65 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a  ue_text16()]..**
32820 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32830 65 73 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65  es must be calle
32840 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20  d from the same 
32850 74 68 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65  thread as.** the
32860 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68   SQL function th
32870 61 74 20 73 75 70 70 6c 69 65 64 20 74 68 65 20  at supplied the 
32880 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d  [sqlite3_value*]
32890 20 70 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a   parameters..*/.
328a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
328b0 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73  te3_value_blob(s
328c0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
328d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
328e0 65 5f 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f  e_bytes(sqlite3_
328f0 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
32900 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
32910 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
32920 2a 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  *);.double sqlit
32930 65 33 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28  e3_value_double(
32940 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
32950 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  .int sqlite3_val
32960 75 65 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76  ue_int(sqlite3_v
32970 61 6c 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f  alue*);.sqlite3_
32980 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61  int64 sqlite3_va
32990 6c 75 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  lue_int64(sqlite
329a0 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74  3_value*);.const
329b0 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a   unsigned char *
329c0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
329d0 78 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  xt(sqlite3_value
329e0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
329f0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
32a00 78 74 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c  xt16(sqlite3_val
32a10 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  ue*);.const void
32a20 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   *sqlite3_value_
32a30 74 65 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33  text16le(sqlite3
32a40 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20  _value*);.const 
32a50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
32a60 6c 75 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c  lue_text16be(sql
32a70 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32a80 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32a90 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32aa0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
32ab0 33 5f 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f  3_value_numeric_
32ac0 74 79 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c  type(sqlite3_val
32ad0 75 65 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ue*);../*.** CAP
32ae0 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67  I3REF: Obtain Ag
32af0 67 72 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e  gregate Function
32b00 20 43 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49   Context.**.** I
32b10 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
32b20 66 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20  f aggregate SQL 
32b30 66 75 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68  functions use th
32b40 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f  is.** routine to
32b50 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
32b60 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65   for storing the
32b70 69 72 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  ir state..**.** 
32b80 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d 65 20  ^The first time 
32b90 74 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  the sqlite3_aggr
32ba0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32bb0 4e 29 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61  N) routine is ca
32bc0 6c 6c 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70  lled .** for a p
32bd0 61 72 74 69 63 75 6c 61 72 20 61 67 67 72 65 67  articular aggreg
32be0 61 74 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51  ate function, SQ
32bf0 4c 69 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65  Lite.** allocate
32c00 73 20 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a  s N of memory, z
32c10 65 72 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d  eroes out that m
32c20 65 6d 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72  emory, and retur
32c30 6e 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  ns a pointer.** 
32c40 74 6f 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72  to the new memor
32c50 79 2e 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e  y. ^On second an
32c60 64 20 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c  d subsequent cal
32c70 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
32c80 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32c90 78 74 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d  xt() for the sam
32ca0 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
32cb0 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a  tion instance,.*
32cc0 2a 20 74 68 65 20 73 61 6d 65 20 62 75 66 66 65  * the same buffe
32cd0 72 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  r is returned.  
32ce0 53 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  Sqlite3_aggregat
32cf0 65 5f 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e  e_context() is n
32d00 6f 72 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65  ormally.** calle
32d10 64 20 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20  d once for each 
32d20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68  invocation of th
32d30 65 20 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b  e xStep callback
32d40 20 61 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a   and then one.**
32d50 20 6c 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20   last time when 
32d60 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
32d70 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20  ack is invoked. 
32d80 20 5e 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20   ^(When no rows 
32d90 6d 61 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72  match.** an aggr
32da0 65 67 61 74 65 20 71 75 65 72 79 2c 20 74 68 65  egate query, the
32db0 20 78 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63   xStep() callbac
32dc0 6b 20 6f 66 20 74 68 65 20 61 67 67 72 65 67 61  k of the aggrega
32dd0 74 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69  te function.** i
32de0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
32df0 20 6e 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e   never called an
32e00 64 20 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61  d xFinal() is ca
32e10 6c 6c 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63  lled exactly onc
32e20 65 2e 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63  e..** In those c
32e30 61 73 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67  ases, sqlite3_ag
32e40 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
32e50 29 20 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65  ) might be calle
32e60 64 20 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72  d for the.** fir
32e70 73 74 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74  st time from wit
32e80 68 69 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a  hin xFinal().)^.
32e90 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
32ea0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
32eb0 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e  text(C,N) routin
32ec0 65 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  e returns a NULL
32ed0 20 70 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65   pointer .** whe
32ee0 6e 20 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69  n first called i
32ef0 66 20 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e  f N is less than
32f00 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
32f10 6f 20 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79  o or if a memory
32f20 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72  .** allocate err
32f30 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a  or occurs..**.**
32f40 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66   ^(The amount of
32f50 20 73 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64   space allocated
32f60 20 62 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72   by sqlite3_aggr
32f70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
32f80 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69  N) is.** determi
32f90 6e 65 64 20 62 79 20 74 68 65 20 4e 20 70 61 72  ned by the N par
32fa0 61 6d 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20  ameter on first 
32fb0 73 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e  successful call.
32fc0 20 20 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a    Changing the.*
32fd0 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20  * value of N in 
32fe0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20  subsequent call 
32ff0 74 6f 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  to sqlite3_aggre
33000 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77  gate_context() w
33010 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d  ithin.** the sam
33020 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
33030 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69  tion instance wi
33040 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68  ll not resize th
33050 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f  e memory.** allo
33060 63 61 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69  cation.)^  Withi
33070 6e 20 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c  n the xFinal cal
33080 6c 62 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73  lback, it is cus
33090 74 6f 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a  tomary to set.**
330a0 20 4e 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f   N=0 in calls to
330b0 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
330c0 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
330d0 73 6f 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70  so that no .** p
330e0 6f 69 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20  ointless memory 
330f0 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75  allocations occu
33100 72 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65  r..**.** ^SQLite
33110 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66   automatically f
33120 72 65 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20  rees the memory 
33130 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a  allocated by .**
33140 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
33150 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65  te_context() whe
33160 6e 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  n the aggregate 
33170 71 75 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e  query concludes.
33180 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  .**.** The first
33190 20 70 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20   parameter must 
331a0 62 65 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  be a copy of the
331b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
331c0 74 65 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74  text | SQL funct
331d0 69 6f 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61  ion context] tha
331e0 74 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  t is the first p
331f0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74  arameter.** to t
33200 68 65 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e  he xStep or xFin
33210 61 6c 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74  al callback rout
33220 69 6e 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  ine that impleme
33230 6e 74 73 20 74 68 65 20 61 67 67 72 65 67 61 74  nts the aggregat
33240 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  e.** function..*
33250 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e  *.** This routin
33260 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64  e must be called
33270 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74   from the same t
33280 68 72 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a  hread in which.*
33290 2a 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  * the aggregate 
332a0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
332b0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
332c0 20 2a 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67   *sqlite3_aggreg
332d0 61 74 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69  ate_context(sqli
332e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
332f0 74 20 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a  t nBytes);../*.*
33300 2a 20 43 41 50 49 33 52 45 46 3a 20 55 73 65 72  * CAPI3REF: User
33310 20 44 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69   Data For Functi
33320 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ons.**.** ^The s
33330 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61  qlite3_user_data
33340 28 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  () interface ret
33350 75 72 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a  urns a copy of.*
33360 2a 20 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68  * the pointer th
33370 61 74 20 77 61 73 20 74 68 65 20 70 55 73 65 72  at was the pUser
33380 44 61 74 61 20 70 61 72 61 6d 65 74 65 72 20 28  Data parameter (
33390 74 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  the 5th paramete
333a0 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  r).** of the [sq
333b0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
333c0 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20  ction()].** and 
333d0 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
333e0 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f  function16()] ro
333f0 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67  utines that orig
33400 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74  inally.** regist
33410 65 72 65 64 20 74 68 65 20 61 70 70 6c 69 63 61  ered the applica
33420 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e  tion defined fun
33430 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  ction..**.** Thi
33440 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62  s routine must b
33450 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
33460 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
33470 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70   which.** the ap
33480 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
33490 64 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  d function is ru
334a0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
334b0 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74  sqlite3_user_dat
334c0 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
334d0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
334e0 33 52 45 46 3a 20 44 61 74 61 62 61 73 65 20 43  3REF: Database C
334f0 6f 6e 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75  onnection For Fu
33500 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54  nctions.**.** ^T
33510 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  he sqlite3_conte
33520 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69  xt_db_handle() i
33530 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
33540 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68   a copy of.** th
33550 65 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  e pointer to the
33560 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33570 63 74 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20  ction] (the 1st 
33580 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66  parameter).** of
33590 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72   the [sqlite3_cr
335a0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
335b0 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
335c0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
335d0 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74  16()] routines t
335e0 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a  hat originally.*
335f0 2a 20 72 65 67 69 73 74 65 72 65 64 20 74 68 65  * registered the
33600 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66   application def
33610 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a  ined function..*
33620 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
33630 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61  e3_context_db_ha
33640 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  ndle(sqlite3_con
33650 74 65 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  text*);../*.** C
33660 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
33670 6e 20 41 75 78 69 6c 69 61 72 79 20 44 61 74 61  n Auxiliary Data
33680 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e  .**.** These fun
33690 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73  ctions may be us
336a0 65 64 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65  ed by (non-aggre
336b0 67 61 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69  gate) SQL functi
336c0 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69  ons to.** associ
336d0 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69 74  ate metadata wit
336e0 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65  h argument value
336f0 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20 76  s. If the same v
33700 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20 74  alue is passed t
33710 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e  o.** multiple in
33720 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
33730 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69   same SQL functi
33740 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79 20  on during query 
33750 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72  execution, under
33760 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73  .** some circums
33770 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63  tances the assoc
33780 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d  iated metadata m
33790 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64 2e  ay be preserved.
337a0 20 20 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20    An example.** 
337b0 6f 66 20 77 68 65 72 65 20 74 68 69 73 20 6d 69  of where this mi
337c0 67 68 74 20 62 65 20 75 73 65 66 75 6c 20 69 73  ght be useful is
337d0 20 69 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78   in a regular-ex
337e0 70 72 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e  pression matchin
337f0 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54  g.** function. T
33800 68 65 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73  he compiled vers
33810 69 6f 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c  ion of the regul
33820 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
33830 6e 20 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a  n be stored as.*
33840 2a 20 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63  * metadata assoc
33850 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 70  iated with the p
33860 61 74 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20  attern string.  
33870 0a 2a 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67  .** Then as long
33880 20 61 73 20 74 68 65 20 70 61 74 74 65 72 6e 20   as the pattern 
33890 73 74 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74  string remains t
338a0 68 65 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20  he same,.** the 
338b0 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72  compiled regular
338c0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
338d0 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c  be reused on mul
338e0 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74  tiple.** invocat
338f0 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65  ions of the same
33900 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
33910 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65   ^The sqlite3_ge
33920 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
33930 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
33940 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d  pointer to the m
33950 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63  etadata.** assoc
33960 69 61 74 65 64 20 62 79 20 74 68 65 20 73 71 6c  iated by the sql
33970 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33980 28 29 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68  () function with
33990 20 74 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e   the Nth argumen
339a0 74 0a 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68  t.** value to th
339b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
339c0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20  fined function. 
339d0 5e 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20  ^If there is no 
339e0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f  metadata.** asso
339f0 63 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20  ciated with the 
33a00 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e  function argumen
33a10 74 2c 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f  t, this sqlite3_
33a20 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e  get_auxdata() in
33a30 74 65 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72  terface.** retur
33a40 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
33a50 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
33a60 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74  lite3_set_auxdat
33a70 61 28 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72  a(C,N,P,X) inter
33a80 66 61 63 65 20 73 61 76 65 73 20 50 20 61 73 20  face saves P as 
33a90 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
33aa0 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
33ab0 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
33ac0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
33ad0 63 74 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75  ction.  ^Subsequ
33ae0 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ent.** calls to 
33af0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
33b00 61 74 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20  ata(C,N) return 
33b10 50 20 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20  P from the most 
33b20 72 65 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65  recent.** sqlite
33b30 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c  3_set_auxdata(C,
33b40 4e 2c 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74  N,P,X) call if t
33b50 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 73  he metadata is s
33b60 74 69 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a  till valid or.**
33b70 20 4e 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74   NULL if the met
33b80 61 64 61 74 61 20 68 61 73 20 62 65 65 6e 20 64  adata has been d
33b90 69 73 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66  iscarded..** ^Af
33ba0 74 65 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f  ter each call to
33bb0 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33bc0 64 61 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68  data(C,N,P,X) wh
33bd0 65 72 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c  ere X is not NUL
33be0 4c 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c  L,.** SQLite wil
33bf0 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73  l invoke the des
33c00 74 72 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e  tructor function
33c10 20 58 20 77 69 74 68 20 70 61 72 61 6d 65 74 65   X with paramete
33c20 72 20 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f  r P exactly.** o
33c30 6e 63 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65  nce, when the me
33c40 74 61 64 61 74 61 20 69 73 20 64 69 73 63 61 72  tadata is discar
33c50 64 65 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69  ded..** SQLite i
33c60 73 20 66 72 65 65 20 74 6f 20 64 69 73 63 61 72  s free to discar
33c70 64 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 61  d the metadata a
33c80 74 20 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c  t any time, incl
33c90 75 64 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c  uding: <ul>.** <
33ca0 6c 69 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72  li> when the cor
33cb0 72 65 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74  responding funct
33cc0 69 6f 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68  ion parameter ch
33cd0 61 6e 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  anges, or.** <li
33ce0 3e 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f  > when [sqlite3_
33cf0 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
33d00 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
33d10 20 69 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   is called for t
33d20 68 65 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73  he.**      SQL s
33d30 74 61 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20  tatement, or.** 
33d40 3c 6c 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65  <li> when sqlite
33d50 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_set_auxdata() 
33d60 69 73 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e  is invoked again
33d70 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72   on the same par
33d80 61 6d 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c  ameter, or.** <l
33d90 69 3e 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72  i> during the or
33da0 69 67 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73  iginal sqlite3_s
33db0 65 74 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c  et_auxdata() cal
33dc0 6c 20 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20  l when a memory 
33dd0 0a 2a 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74  .**      allocat
33de0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
33df0 2e 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  . </ul>)^.**.** 
33e00 4e 6f 74 65 20 74 68 65 20 6c 61 73 74 20 62 75  Note the last bu
33e10 6c 6c 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c  llet in particul
33e20 61 72 2e 20 20 54 68 65 20 64 65 73 74 72 75 63  ar.  The destruc
33e30 74 6f 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c  tor X in .** sql
33e40 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61  ite3_set_auxdata
33e50 28 43 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20  (C,N,P,X) might 
33e60 62 65 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69  be called immedi
33e70 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68  ately, before th
33e80 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74  e.** sqlite3_set
33e90 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72  _auxdata() inter
33ea0 66 61 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e  face even return
33eb0 73 2e 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65  s.  Hence sqlite
33ec0 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a  3_set_auxdata().
33ed0 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c  ** should be cal
33ee0 6c 65 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64  led near the end
33ef0 20 6f 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   of the function
33f00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
33f10 61 6e 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74  and the.** funct
33f20 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
33f30 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61  on should not ma
33f40 6b 65 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20  ke any use of P 
33f50 61 66 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33  after.** sqlite3
33f60 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 68  _set_auxdata() h
33f70 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a  as been called..
33f80 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74  **.** ^(In pract
33f90 69 63 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73  ice, metadata is
33fa0 20 70 72 65 73 65 72 76 65 64 20 62 65 74 77 65   preserved betwe
33fb0 65 6e 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c  en function call
33fc0 73 20 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  s for.** functio
33fd0 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68 61  n parameters tha
33fe0 74 20 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69  t are compile-ti
33ff0 6d 65 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e  me constants, in
34000 63 6c 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a  cluding literal.
34010 2a 2a 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70  ** values and [p
34020 61 72 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65  arameters] and e
34030 78 70 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f  xpressions compo
34040 73 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  sed from the sam
34050 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  e.)^.**.** These
34060 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62   routines must b
34070 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68  e called from th
34080 65 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e  e same thread in
34090 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51   which.** the SQ
340a0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
340b0 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
340c0 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
340d0 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ata(sqlite3_cont
340e0 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f  ext*, int N);.vo
340f0 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  id sqlite3_set_a
34100 75 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63  uxdata(sqlite3_c
34110 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20  ontext*, int N, 
34120 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28  void*, void (*)(
34130 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a  void*));.../*.**
34140 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74   CAPI3REF: Const
34150 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70  ants Defining Sp
34160 65 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72  ecial Destructor
34170 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20   Behavior.**.** 
34180 54 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61  These are specia
34190 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65  l values for the
341a0 20 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74   destructor that
341b0 20 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73   is passed in as
341c0 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72   the.** final ar
341d0 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e  gument to routin
341e0 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33  es like [sqlite3
341f0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e  _result_blob()].
34200 20 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75    ^If the destru
34210 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  ctor.** argument
34220 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49   is SQLITE_STATI
34230 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74  C, it means that
34240 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69   the content poi
34250 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74  nter is constant
34260 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76  .** and will nev
34270 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64  er change.  It d
34280 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  oes not need to 
34290 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e  be destroyed.  ^
342a0 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52  The.** SQLITE_TR
342b0 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65  ANSIENT value me
342c0 61 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e  ans that the con
342d0 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79  tent will likely
342e0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68   change in.** th
342f0 65 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e  e near future an
34300 64 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68  d that SQLite sh
34310 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77  ould make its ow
34320 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  n private copy o
34330 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74  f.** the content
34340 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e   before returnin
34350 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70  g..**.** The typ
34360 65 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72  edef is necessar
34370 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64  y to work around
34380 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72   problems in cer
34390 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70  tain.** C++ comp
343a0 69 6c 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  ilers..*/.typede
343b0 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33  f void (*sqlite3
343c0 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
343d0 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e  )(void*);.#defin
343e0 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20  e SQLITE_STATIC 
343f0 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64       ((sqlite3_d
34400 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30  estructor_type)0
34410 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
34420 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73  _TRANSIENT   ((s
34430 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f  qlite3_destructo
34440 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a  r_type)-1)../*.*
34450 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 74  * CAPI3REF: Sett
34460 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f  ing The Result O
34470 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f  f An SQL Functio
34480 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  n.**.** These ro
34490 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64 20  utines are used 
344a0 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20  by the xFunc or 
344b0 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73  xFinal callbacks
344c0 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65   that.** impleme
344d0 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  nt SQL functions
344e0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
344f0 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65    See.** [sqlite
34500 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34510 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  n()] and [sqlite
34520 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
34530 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64  n16()].** for ad
34540 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
34550 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tion..**.** Thes
34560 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b  e functions work
34570 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20   very much like 
34580 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62  the [parameter b
34590 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f  inding] family o
345a0 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75  f.** functions u
345b0 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75  sed to bind valu
345c0 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d  es to host param
345d0 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72 65  eters in prepare
345e0 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  d statements..**
345f0 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53   Refer to the [S
34600 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f  QL parameter] do
34610 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20  cumentation for 
34620 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
34630 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54  mation..**.** ^T
34640 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34650 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61  t_blob() interfa
34660 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
34670 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70  lt from.** an ap
34680 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34690 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
346a0 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20   the BLOB whose 
346b0 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74  content is point
346c0 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20  ed.** to by the 
346d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
346e0 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20   and which is N 
346f0 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65  bytes long where
34700 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69   N is the.** thi
34710 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  rd parameter..**
34720 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34730 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
34740 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73 65  () interfaces se
34750 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  t the result of.
34760 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
34770 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
34780 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42  ion to be a BLOB
34790 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20   containing all 
347a0 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e  zero.** bytes an
347b0 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a  d N bytes in siz
347c0 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68  e, where N is th
347d0 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32  e value of the 2
347e0 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  nd parameter..**
347f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
34800 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29  _result_double()
34810 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
34820 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a  the result from.
34830 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  ** an applicatio
34840 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34850 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74  on to be a float
34860 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20  ing point value 
34870 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
34880 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74  its 2nd argument
34890 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
348a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
348b0 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
348c0 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
348d0 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61   functions.** ca
348e0 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  use the implemen
348f0 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ted SQL function
34900 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63   to throw an exc
34910 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69  eption..** ^SQLi
34920 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72 69  te uses the stri
34930 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79  ng pointed to by
34940 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61   the.** 2nd para
34950 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33  meter of sqlite3
34960 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20  _result_error() 
34970 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
34980 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61  t_error16().** a
34990 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e  s the text of an
349a0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20   error message. 
349b0 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72   ^SQLite interpr
349c0 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a  ets the error.**
349d0 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 20   message string 
349e0 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73  from sqlite3_res
349f0 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55  ult_error() as U
34a00 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a  TF-8. ^SQLite.**
34a10 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65 20   interprets the 
34a20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69  string from sqli
34a30 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34a40 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20 69  16() as UTF-16 i
34a50 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65  n native.** byte
34a60 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65   order.  ^If the
34a70 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72   third parameter
34a80 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75   to sqlite3_resu
34a90 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72  lt_error().** or
34aa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34ab0 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67  error16() is neg
34ac0 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74  ative then SQLit
34ad0 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20 65  e takes as the e
34ae0 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20  rror.** message 
34af0 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f  all text up thro
34b00 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a 65  ugh the first ze
34b10 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a  ro character..**
34b20 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20 70   ^If the third p
34b30 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34b40 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34b50 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
34b60 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
34b70 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  ) is non-negativ
34b80 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61  e then SQLite ta
34b90 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a  kes that many.**
34ba0 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
34bb0 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65  acters) from the
34bc0 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
34bd0 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  s the error mess
34be0 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  age..** ^The sql
34bf0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34c00 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  r() and sqlite3_
34c10 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34c20 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b  .** routines mak
34c30 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70 79  e a private copy
34c40 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65   of the error me
34c50 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f 72  ssage text befor
34c60 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e  e.** they return
34c70 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61  .  Hence, the ca
34c80 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  lling function c
34c90 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72  an deallocate or
34ca0 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74  .** modify the t
34cb0 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20 72  ext after they r
34cc0 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61  eturn without ha
34cd0 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  rm..** ^The sqli
34ce0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
34cf0 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e  _code() function
34d00 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72 72   changes the err
34d10 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72  or code.** retur
34d20 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 73  ned by SQLite as
34d30 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20   a result of an 
34d40 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74  error in a funct
34d50 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c  ion.  ^By defaul
34d60 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20  t,.** the error 
34d70 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45  code is SQLITE_E
34d80 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71  RROR.  ^A subseq
34d90 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c  uent call to sql
34da0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
34db0 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  r().** or sqlite
34dc0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
34dd0 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65 72  () resets the er
34de0 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49  ror code to SQLI
34df0 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20  TE_ERROR..**.** 
34e00 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34e10 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
34e20 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
34e30 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34e40 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34e50 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34e60 61 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42  a string or BLOB
34e70 20 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20   is too long to 
34e80 72 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a  represent..**.**
34e90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
34ea0 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d  sult_error_nomem
34eb0 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75  () interface cau
34ec0 73 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68  ses SQLite to th
34ed0 72 6f 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20  row an.** error 
34ee0 69 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20  indicating that 
34ef0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
34f00 69 6f 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a  ion failed..**.*
34f10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34f20 65 73 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65  esult_int() inte
34f30 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
34f40 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
34f50 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
34f60 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
34f70 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d  on to be the 32-
34f80 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
34f90 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
34fa0 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
34fb0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73  ument..** ^The s
34fc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e  qlite3_result_in
34fd0 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
34fe0 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20  sets the return 
34ff0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20  value.** of the 
35000 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
35010 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
35020 62 65 20 74 68 65 20 36 34 2d 62 69 74 20 73 69  be the 64-bit si
35030 67 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20  gned integer.** 
35040 76 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74  value given in t
35050 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e  he 2nd argument.
35060 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
35070 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28  te3_result_null(
35080 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
35090 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
350a0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
350b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
350c0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e  function to be N
350d0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
350e0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
350f0 65 78 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72  ext(), sqlite3_r
35100 65 73 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a  esult_text16(),.
35110 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  ** sqlite3_resul
35120 74 5f 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e  t_text16le(), an
35130 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
35140 5f 74 65 78 74 31 36 62 65 28 29 20 69 6e 74 65  _text16be() inte
35150 72 66 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68  rfaces.** set th
35160 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f  e return value o
35170 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
35180 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
35190 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65  on to be.** a te
351a0 78 74 20 73 74 72 69 6e 67 20 77 68 69 63 68 20  xt string which 
351b0 69 73 20 72 65 70 72 65 73 65 6e 74 65 64 20 61  is represented a
351c0 73 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20  s UTF-8, UTF-16 
351d0 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
351e0 72 2c 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74  r,.** UTF-16 lit
351f0 74 6c 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55  tle endian, or U
35200 54 46 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e  TF-16 big endian
35210 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  , respectively..
35220 2a 2a 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73  ** ^SQLite takes
35230 20 74 68 65 20 74 65 78 74 20 72 65 73 75 6c 74   the text result
35240 20 66 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63   from the applic
35250 61 74 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68  ation from.** th
35260 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
35270 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  of the sqlite3_r
35280 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35290 72 66 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74  rfaces..** ^If t
352a0 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
352b0 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
352c0 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
352d0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65  erfaces.** is ne
352e0 67 61 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c  gative, then SQL
352f0 69 74 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74  ite takes result
35300 20 74 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32   text from the 2
35310 6e 64 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  nd parameter.** 
35320 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72 73  through the firs
35330 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72  t zero character
35340 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64  ..** ^If the 3rd
35350 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
35360 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
35370 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
35380 73 0a 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61  s.** is non-nega
35390 74 69 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61  tive, then as ma
353a0 6e 79 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ny bytes (not ch
353b0 61 72 61 63 74 65 72 73 29 20 6f 66 20 74 68 65  aracters) of the
353c0 20 74 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64   text.** pointed
353d0 20 74 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70   to by the 2nd p
353e0 61 72 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b  arameter are tak
353f0 65 6e 20 61 73 20 74 68 65 20 61 70 70 6c 69 63  en as the applic
35400 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a  ation-defined.**
35410 20 66 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74   function result
35420 2e 20 20 49 66 20 74 68 65 20 33 72 64 20 70 61  .  If the 3rd pa
35430 72 61 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e  rameter is non-n
35440 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74  egative, then it
35450 0a 2a 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20  .** must be the 
35460 62 79 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f  byte offset into
35470 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
35480 65 20 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e  e the NUL termin
35490 61 74 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70  ator would.** ap
354a0 70 65 61 72 20 69 66 20 74 68 65 20 73 74 72 69  pear if the stri
354b0 6e 67 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72  ng where NUL ter
354c0 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79  minated.  If any
354d0 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73 20   NUL characters 
354e0 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20  occur.** in the 
354f0 73 74 72 69 6e 67 20 61 74 20 61 20 62 79 74 65  string at a byte
35500 20 6f 66 66 73 65 74 20 74 68 61 74 20 69 73 20   offset that is 
35510 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 76 61  less than the va
35520 6c 75 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a  lue of the 3rd.*
35530 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65  * parameter, the
35540 6e 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20  n the resulting 
35550 73 74 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74  string will cont
35560 61 69 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c  ain embedded NUL
35570 73 20 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73  s and the.** res
35580 75 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f  ult of expressio
35590 6e 73 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20  ns operating on 
355a0 73 74 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62  strings with emb
355b0 65 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e  edded NULs is un
355c0 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20  defined..** ^If 
355d0 74 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65  the 4th paramete
355e0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
355f0 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e  _result_text* in
35600 74 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73  terfaces.** or s
35610 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c  qlite3_result_bl
35620 6f 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c  ob is a non-NULL
35630 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53   pointer, then S
35640 51 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74  QLite calls that
35650 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20  .** function as 
35660 74 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f  the destructor o
35670 6e 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c  n the text or BL
35680 4f 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69  OB result when i
35690 74 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65  t has.** finishe
356a0 64 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73  d using that res
356b0 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ult..** ^If the 
356c0 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
356d0 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
356e0 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
356f0 61 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71  aces or to.** sq
35700 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
35710 62 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c  b is the special
35720 20 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45   constant SQLITE
35730 5f 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51  _STATIC, then SQ
35740 4c 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20  Lite.** assumes 
35750 74 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72  that the text or
35760 20 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20   BLOB result is 
35770 69 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63  in constant spac
35780 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a  e and does not.*
35790 2a 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65  * copy the conte
357a0 6e 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65  nt of the parame
357b0 74 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64  ter nor call a d
357c0 65 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65  estructor on the
357d0 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e   content.** when
357e0 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64   it has finished
357f0 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
35800 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
35810 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
35820 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
35830 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
35840 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65  ces.** or sqlite
35850 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73  3_result_blob is
35860 20 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e   the special con
35870 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41  stant SQLITE_TRA
35880 4e 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53  NSIENT.** then S
35890 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f  QLite makes a co
358a0 70 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  py of the result
358b0 20 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61   into space obta
358c0 69 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f  ined from.** fro
358d0 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
358e0 63 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72  c()] before it r
358f0 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eturns..**.** ^T
35900 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35910 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66  t_value() interf
35920 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
35930 75 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70  ult of.** the ap
35940 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
35950 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
35960 20 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b   a copy the.** [
35970 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
35980 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35990 74 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  t specified by t
359a0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
359b0 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74  .  ^The.** sqlit
359c0 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
359d0 29 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65  ) interface make
359e0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
359f0 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a  [sqlite3_value].
35a00 2a 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b  ** so that the [
35a10 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73  sqlite3_value] s
35a20 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20  pecified in the 
35a30 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68  parameter may ch
35a40 61 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65  ange or.** be de
35a50 61 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20  allocated after 
35a60 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76  sqlite3_result_v
35a70 61 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77  alue() returns w
35a80 69 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20  ithout harm..** 
35a90 5e 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  ^A [protected sq
35aa0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35ab0 65 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62  ect may always b
35ac0 65 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a  e used where an.
35ad0 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20  ** [unprotected 
35ae0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f  sqlite3_value] o
35af0 62 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65  bject is require
35b00 64 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20  d, so either.** 
35b10 6b 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33  kind of [sqlite3
35b20 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63  _value] object c
35b30 61 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20  an be used with 
35b40 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a  this interface..
35b50 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72  **.** If these r
35b60 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c  outines are call
35b70 65 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74  ed from within t
35b80 68 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  he different thr
35b90 65 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20  ead.** than the 
35ba0 6f 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  one containing t
35bb0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
35bc0 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
35bd0 74 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a  that received.**
35be0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
35bf0 6e 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20  ntext] pointer, 
35c00 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20  the results are 
35c10 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f  undefined..*/.vo
35c20 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35c30 74 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63  t_blob(sqlite3_c
35c40 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76  ontext*, const v
35c50 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28  oid*, int, void(
35c60 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64  *)(void*));.void
35c70 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35c80 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63  double(sqlite3_c
35c90 6f 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29  ontext*, double)
35ca0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35cb0 65 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69  esult_error(sqli
35cc0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
35cd0 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b  nst char*, int);
35ce0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
35cf0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c  sult_error16(sql
35d00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
35d10 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29  onst void*, int)
35d20 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
35d30 65 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62  esult_error_toob
35d40 69 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ig(sqlite3_conte
35d50 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
35d60 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f  e3_result_error_
35d70 6e 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f  nomem(sqlite3_co
35d80 6e 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71  ntext*);.void sq
35d90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
35da0 6f 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f  or_code(sqlite3_
35db0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
35dc0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35dd0 75 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ult_int(sqlite3_
35de0 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a  context*, int);.
35df0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35e00 75 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65  ult_int64(sqlite
35e10 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69  3_context*, sqli
35e20 74 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64  te3_int64);.void
35e30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35e40 6e 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e  null(sqlite3_con
35e50 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
35e60 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
35e70 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35e80 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  *, const char*, 
35e90 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35ea0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35eb0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35ec0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35ed0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35ee0 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
35ef0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35f00 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
35f10 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
35f20 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
35f30 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
35f40 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
35f50 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
35f60 36 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  6be(sqlite3_cont
35f70 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64  ext*, const void
35f80 2a 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76  *, int,void(*)(v
35f90 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c  oid*));.void sql
35fa0 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75  ite3_result_valu
35fb0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35fc0 74 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t*, sqlite3_valu
35fd0 65 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  e*);.void sqlite
35fe0 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
35ff0 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  b(sqlite3_contex
36000 74 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  t*, int n);../*.
36010 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66  ** CAPI3REF: Def
36020 69 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e  ine New Collatin
36030 67 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a  g Sequences.**.*
36040 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
36050 6e 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20  ns add, remove, 
36060 6f 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c  or modify a [col
36070 6c 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74  lation] associat
36080 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  ed.** with the [
36090 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
360a0 69 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61  ion] specified a
360b0 73 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  s the first argu
360c0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
360d0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
360e0 6c 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d  lation is a UTF-
360f0 38 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20  8 string.** for 
36100 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36110 6f 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73  ollation() and s
36120 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
36130 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20  llation_v2().** 
36140 61 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72  and a UTF-16 str
36150 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
36160 74 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c  te order for sql
36170 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
36180 61 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43  ation16()..** ^C
36190 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74  ollation names t
361a0 68 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61  hat compare equa
361b0 6c 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b  l according to [
361c0 73 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70  sqlite3_strnicmp
361d0 28 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69  ()] are.** consi
361e0 64 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20  dered to be the 
361f0 73 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a  same name..**.**
36200 20 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67   ^(The third arg
36210 75 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29  ument (eTextRep)
36220 20 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20   must be one of 
36230 74 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a  the constants:.*
36240 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b  * <ul>.** <li> [
36250 53 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a  SQLITE_UTF8],.**
36260 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54   <li> [SQLITE_UT
36270 46 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  F16LE],.** <li> 
36280 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d  [SQLITE_UTF16BE]
36290 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54  ,.** <li> [SQLIT
362a0 45 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20  E_UTF16], or.** 
362b0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
362c0 31 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20  16_ALIGNED]..** 
362d0 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20  </ul>)^.** ^The 
362e0 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e  eTextRep argumen
362f0 74 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65  t determines the
36300 20 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72   encoding of str
36310 69 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74  ings passed.** t
36320 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
36330 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
36340 6b 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  k, xCallback..**
36350 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54   ^The [SQLITE_UT
36360 46 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  F16] and [SQLITE
36370 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20  _UTF16_ALIGNED] 
36380 76 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74  values for eText
36390 52 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72  Rep.** force str
363a0 69 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36  ings to be UTF16
363b0 20 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74   with native byt
363c0 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65  e order..** ^The
363d0 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41   [SQLITE_UTF16_A
363e0 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f  LIGNED] value fo
363f0 72 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65  r eTextRep force
36400 73 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67  s strings to beg
36410 69 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e  in.** on an even
36420 20 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a   byte address..*
36430 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
36440 20 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c   argument, pArg,
36450 20 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69   is an applicati
36460 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20  on data pointer 
36470 74 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a  that is passed.*
36480 2a 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  * through as the
36490 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
364a0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
364b0 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61   function callba
364c0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ck..**.** ^The f
364d0 69 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78  ifth argument, x
364e0 43 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70  Callback, is a p
364f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f  ointer to the co
36500 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36510 2e 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63  ..** ^Multiple c
36520 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
36530 6e 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74  ns can be regist
36540 65 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73  ered using the s
36550 61 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20  ame name but.** 
36560 77 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65  with different e
36570 54 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65  TextRep paramete
36580 72 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69  rs and SQLite wi
36590 6c 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72  ll use whichever
365a0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  .** function req
365b0 75 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20  uires the least 
365c0 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74  amount of data t
365d0 72 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  ransformation..*
365e0 2a 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62  * ^If the xCallb
365f0 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ack argument is 
36600 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f  NULL then the co
36610 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36620 20 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20   is.** deleted. 
36630 20 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61   ^When all colla
36640 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68  ting functions h
36650 61 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e  aving the same n
36660 61 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c  ame are deleted,
36670 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69  .** that collati
36680 6f 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  on is no longer 
36690 75 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  usable..**.** ^T
366a0 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  he collating fun
366b0 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69  ction callback i
366c0 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61  s invoked with a
366d0 20 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72   copy of the pAr
366e0 67 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  g .** applicatio
366f0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61  n data pointer a
36700 6e 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69  nd with two stri
36710 6e 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64  ngs in the encod
36720 69 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a  ing specified.**
36730 20 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70   by the eTextRep
36740 20 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20   argument.  The 
36750 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36760 6f 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61  on must return a
36770 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61  n.** integer tha
36780 74 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a  t is negative, z
36790 65 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65  ero, or positive
367a0 0a 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74  .** if the first
367b0 20 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20   string is less 
367c0 74 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20  than, equal to, 
367d0 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20  or greater than 
367e0 74 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72  the second,.** r
367f0 65 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20  espectively.  A 
36800 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36810 6f 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72  on must always r
36820 65 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61  eturn the same a
36830 6e 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74  nswer.** given t
36840 68 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20  he same inputs. 
36850 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20   If two or more 
36860 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
36870 6f 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72  ons are register
36880 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d  ed.** to the sam
36890 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65  e collation name
368a0 20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e   (using differen
368b0 74 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65  t eTextRep value
368c0 73 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d  s) then all.** m
368d0 75 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69  ust give an equi
368e0 76 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68  valent answer wh
368f0 65 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  en invoked with 
36900 65 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e  equivalent strin
36910 67 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61  gs..** The colla
36920 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75  ting function mu
36930 73 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c  st obey the foll
36940 6f 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73  owing properties
36950 20 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69   for all.** stri
36960 6e 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a  ngs A, B, and C:
36970 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c  .**.** <ol>.** <
36980 6c 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e  li> If A==B then
36990 20 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49   B==A..** <li> I
369a0 66 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20  f A==B and B==C 
369b0 74 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c  then A==C..** <l
369c0 69 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45  i> If A&lt;B THE
369d0 4e 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69  N B&gt;A..** <li
369e0 3e 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20  > If A&lt;B and 
369f0 42 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74  B&lt;C then A&lt
36a00 3b 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a  ;C..** </ol>.**.
36a10 2a 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e  ** If a collatin
36a20 67 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73  g function fails
36a30 20 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76   any of the abov
36a40 65 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e  e constraints an
36a50 64 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74  d that.** collat
36a60 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
36a70 20 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20   registered and 
36a80 75 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62  used, then the b
36a90 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74  ehavior of SQLit
36aa0 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65  e.** is undefine
36ab0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
36ac0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36ad0 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b  lation_v2() work
36ae0 73 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63  s like sqlite3_c
36af0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28  reate_collation(
36b00 29 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64  ).** with the ad
36b10 64 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20  dition that the 
36b20 78 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63  xDestroy callbac
36b30 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20  k is invoked on 
36b40 70 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65  pArg when.** the
36b50 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36b60 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a  ion is deleted..
36b70 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75  ** ^Collating fu
36b80 6e 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65  nctions are dele
36b90 74 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72  ted when they ar
36ba0 65 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20  e overridden by 
36bb0 6c 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74  later.** calls t
36bc0 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  o the collation 
36bd0 63 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f  creation functio
36be0 6e 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a  ns or when the.*
36bf0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
36c00 65 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65  ection] is close
36c10 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
36c20 5f 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  _close()]..**.**
36c30 20 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63   ^The xDestroy c
36c40 61 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f  allback is <u>no
36c50 74 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20  t</u> called if 
36c60 74 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  the .** sqlite3_
36c70 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
36c80 5f 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66  _v2() function f
36c90 61 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69  ails.  Applicati
36ca0 6f 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a  ons that invoke.
36cb0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  ** sqlite3_creat
36cc0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29  e_collation_v2()
36cd0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c   with a non-NULL
36ce0 20 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65   xDestroy argume
36cf0 6e 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68  nt should .** ch
36d00 65 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63  eck the return c
36d10 6f 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20  ode and dispose 
36d20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
36d30 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a  on data pointer.
36d40 2a 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61  ** themselves ra
36d50 74 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74  ther than expect
36d60 69 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65  ing SQLite to de
36d70 61 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74  al with it for t
36d80 68 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  hem..** This is 
36d90 64 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65  different from e
36da0 76 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74  very other SQLit
36db0 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68  e interface.  Th
36dc0 65 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20  e inconsistency 
36dd0 0a 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61  .** is unfortuna
36de0 74 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65  te but cannot be
36df0 20 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74   changed without
36e00 20 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61   breaking backwa
36e10 72 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  rds .** compatib
36e20 69 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  ility..**.** See
36e30 20 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33   also:  [sqlite3
36e40 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
36e50 64 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  d()] and [sqlite
36e60 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
36e70 65 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ed16()]..*/.int 
36e80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
36e90 6f 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69  ollation(.  sqli
36ea0 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63  te3*, .  const c
36eb0 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69  har *zName, .  i
36ec0 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20  nt eTextRep, .  
36ed0 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e  void *pArg,.  in
36ee0 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69  t(*xCompare)(voi
36ef0 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36f00 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69  d*,int,const voi
36f10 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  d*).);.int sqlit
36f20 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36f30 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  ion_v2(.  sqlite
36f40 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
36f50 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
36f60 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
36f70 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
36f80 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
36f90 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36fa0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36fb0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
36fc0 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69  roy)(void*).);.i
36fd0 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74  nt sqlite3_creat
36fe0 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20  e_collation16(. 
36ff0 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f   sqlite3*, .  co
37000 6e 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c  nst void *zName,
37010 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
37020 20 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a   .  void *pArg,.
37030 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29    int(*xCompare)
37040 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74  (void*,int,const
37050 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74   void*,int,const
37060 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a   void*).);../*.*
37070 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c  * CAPI3REF: Coll
37080 61 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c  ation Needed Cal
37090 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f  lbacks.**.** ^To
370a0 20 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f   avoid having to
370b0 20 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f   register all co
370c0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
370d0 73 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62  s before a datab
370e0 61 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73  ase.** can be us
370f0 65 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c  ed, a single cal
37100 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d  lback function m
37110 61 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64  ay be registered
37120 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61   with the.** [da
37130 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37140 6e 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  n] to be invoked
37150 20 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64   whenever an und
37160 65 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  efined collation
37170 0a 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20  .** sequence is 
37180 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
37190 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  ^If the function
371a0 20 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75   is registered u
371b0 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33  sing the sqlite3
371c0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
371d0 64 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e  d() API,.** then
371e0 20 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68   it is passed th
371f0 65 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66  e names of undef
37200 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ined collation s
37210 65 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69  equences as stri
37220 6e 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69  ngs.** encoded i
37230 6e 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c  n UTF-8. ^If sql
37240 69 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e  ite3_collation_n
37250 65 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65  eeded16() is use
37260 64 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20  d,.** the names 
37270 61 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54  are passed as UT
37280 46 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20  F-16 in machine 
37290 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
372a0 72 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f  r..** ^A call to
372b0 20 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e   either function
372c0 20 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78   replaces the ex
372d0 69 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e  isting collation
372e0 2d 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b  -needed callback
372f0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74  ..**.** ^(When t
37300 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  he callback is i
37310 6e 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73  nvoked, the firs
37320 74 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65  t argument passe
37330 64 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f  d is a copy.** o
37340 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67  f the second arg
37350 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
37360 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
37370 64 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  d() or.** sqlite
37380 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64  3_collation_need
37390 65 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63  ed16().  The sec
373a0 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ond argument is 
373b0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
373c0 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65  connection.  The
373d0 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20   third argument 
373e0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
373f0 45 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45  E_UTF8], [SQLITE
37400 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72  _UTF16BE],.** or
37410 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45   [SQLITE_UTF16LE
37420 5d 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68  ], indicating th
37430 65 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65  e most desirable
37440 20 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c   form of the col
37450 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e  lation.** sequen
37460 63 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ce function requ
37470 69 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74  ired.  The fourt
37480 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  h parameter is t
37490 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a  he name of the.*
374a0 2a 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61  * required colla
374b0 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e  tion sequence.)^
374c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62  .**.** The callb
374d0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f  ack function sho
374e0 75 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65  uld register the
374f0 20 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69   desired collati
37500 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  on using.** [sql
37510 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
37520 61 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  ation()], [sqlit
37530 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
37540 69 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  ion16()], or.** 
37550 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
37560 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e  collation_v2()].
37570 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
37580 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37590 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20  (.  sqlite3*, . 
375a0 20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28   void*, .  void(
375b0 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33  *)(void*,sqlite3
375c0 2a 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63  *,int eTextRep,c
375d0 6f 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69  onst char*).);.i
375e0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  nt sqlite3_colla
375f0 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20  tion_needed16(. 
37600 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
37610 69 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76  id*,.  void(*)(v
37620 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e  oid*,sqlite3*,in
37630 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74  t eTextRep,const
37640 20 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64   void*).);..#ifd
37650 65 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f  ef SQLITE_HAS_CO
37660 44 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  DEC./*.** Specif
37670 79 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e  y the key for an
37680 20 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62   encrypted datab
37690 61 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69  ase.  This routi
376a0 6e 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  ne should be.** 
376b0 63 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74  called right aft
376c0 65 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  er sqlite3_open(
376d0 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64  )..**.** The cod
376e0 65 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74  e to implement t
376f0 68 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61  his API is not a
37700 76 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20  vailable in the 
37710 70 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a  public release.*
37720 2a 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  * of SQLite..*/.
37730 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28  int sqlite3_key(
37740 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20  .  sqlite3 *db, 
37750 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37760 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f    /* Database to
37770 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20   be rekeyed */. 
37780 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37790 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
377a0 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
377b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79  .int sqlite3_key
377c0 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
377d0 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  db,             
377e0 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73        /* Databas
377f0 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20  e to be rekeyed 
37800 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
37810 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20  *zDbName,       
37820 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74      /* Name of t
37830 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20  he database */. 
37840 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65   const void *pKe
37850 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20  y, int nKey     
37860 2f 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b  /* The key */.);
37870 0a 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74  ../*.** Change t
37880 68 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65  he key on an ope
37890 6e 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20  n database.  If 
378a0 74 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61  the current data
378b0 62 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65  base is not.** e
378c0 6e 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72  ncrypted, this r
378d0 6f 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72  outine will encr
378e0 79 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77  ypt it.  If pNew
378f0 3d 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20  ==0 or nNew==0, 
37900 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
37910 69 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a  is decrypted..**
37920 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20  .** The code to 
37930 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41  implement this A
37940 50 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61  PI is not availa
37950 62 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69  ble in the publi
37960 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20  c release.** of 
37970 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73  SQLite..*/.int s
37980 71 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20  qlite3_rekey(.  
37990 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
379a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
379b0 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65  * Database to be
379c0 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f   rekeyed */.  co
379d0 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20  nst void *pKey, 
379e0 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20  int nKey     /* 
379f0 54 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29  The new key */.)
37a00 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  ;.int sqlite3_re
37a10 6b 65 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65  key_v2(.  sqlite
37a20 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20  3 *db,          
37a30 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
37a40 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79  base to be rekey
37a50 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  ed */.  const ch
37a60 61 72 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20  ar *zDbName,    
37a70 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f         /* Name o
37a80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 2a  f the database *
37a90 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
37aa0 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20  pKey, int nKey  
37ab0 20 20 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65     /* The new ke
37ac0 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53  y */.);../*.** S
37ad0 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
37ae0 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
37af0 53 45 45 20 64 61 74 61 62 61 73 65 2e 20 20 55  SEE database.  U
37b00 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61  nless .** activa
37b10 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65  ted, none of the
37b20 20 53 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69   SEE routines wi
37b30 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64  ll work..*/.void
37b40 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74   sqlite3_activat
37b50 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63  e_see(.  const c
37b60 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65  har *zPassPhrase
37b70 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76          /* Activ
37b80 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a  ation phrase */.
37b90 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65  );.#endif..#ifde
37ba0 66 20 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f  f SQLITE_ENABLE_
37bb0 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63  CEROD./*.** Spec
37bc0 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74 69  ify the activati
37bd0 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52  on key for a CER
37be0 4f 44 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e  OD database.  Un
37bf0 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74  less .** activat
37c00 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20  ed, none of the 
37c10 43 45 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77  CEROD routines w
37c20 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69  ill work..*/.voi
37c30 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61  d sqlite3_activa
37c40 74 65 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73  te_cerod(.  cons
37c50 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
37c60 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
37c70 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
37c80 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a  */.);.#endif../*
37c90 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75  .** CAPI3REF: Su
37ca0 73 70 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20  spend Execution 
37cb0 46 6f 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65  For A Short Time
37cc0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
37cd0 65 33 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74  e3_sleep() funct
37ce0 69 6f 6e 20 63 61 75 73 65 73 20 74 68 65 20 63  ion causes the c
37cf0 75 72 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f  urrent thread to
37d00 20 73 75 73 70 65 6e 64 20 65 78 65 63 75 74 69   suspend executi
37d10 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61  on.** for at lea
37d20 73 74 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d  st a number of m
37d30 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63  illiseconds spec
37d40 69 66 69 65 64 20 69 6e 20 69 74 73 20 70 61 72  ified in its par
37d50 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66  ameter..**.** If
37d60 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
37d70 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73  ystem does not s
37d80 75 70 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71  upport sleep req
37d90 75 65 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69  uests with.** mi
37da0 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72  llisecond time r
37db0 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20  esolution, then 
37dc0 74 68 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65  the time will be
37dd0 20 72 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a   rounded up to.*
37de0 2a 20 74 68 65 20 6e 65 61 72 65 73 74 20 73 65  * the nearest se
37df0 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72  cond. The number
37e00 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73   of milliseconds
37e10 20 6f 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c   of sleep actual
37e20 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20  ly.** requested 
37e30 66 72 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69  from the operati
37e40 6e 67 20 73 79 73 74 65 6d 20 69 73 20 72 65 74  ng system is ret
37e50 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51  urned..**.** ^SQ
37e60 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20  Lite implements 
37e70 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 62  this interface b
37e80 79 20 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53  y calling the xS
37e90 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64  leep().** method
37ea0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37eb0 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
37ec0 6a 65 63 74 2e 20 20 49 66 20 74 68 65 20 78 53  ject.  If the xS
37ed0 6c 65 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a  leep() method.**
37ee0 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c 74 20   of the default 
37ef0 56 46 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65  VFS is not imple
37f00 6d 65 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79  mented correctly
37f10 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  , or not impleme
37f20 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20  nted at.** all, 
37f30 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
37f40 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65  r of sqlite3_sle
37f50 65 70 28 29 20 6d 61 79 20 64 65 76 69 61 74 65  ep() may deviate
37f60 20 66 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69   from the descri
37f70 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20  ption.** in the 
37f80 70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61  previous paragra
37f90 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  phs..*/.int sqli
37fa0 74 65 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a  te3_sleep(int);.
37fb0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
37fc0 20 4e 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c   Name Of The Fol
37fd0 64 65 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70  der Holding Temp
37fe0 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a  orary Files.**.*
37ff0 2a 20 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62  * ^(If this glob
38000 61 6c 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d  al variable is m
38010 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
38020 61 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69  a string which i
38030 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66  s.** the name of
38040 20 61 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61   a folder (a.k.a
38050 2e 20 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68  . directory), th
38060 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79  en all temporary
38070 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65   files.** create
38080 64 20 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e  d by SQLite when
38090 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69   using a built-i
380a0 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c  n [sqlite3_vfs |
380b0 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65   VFS].** will be
380c0 20 70 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20   placed in that 
380d0 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49  directory.)^  ^I
380e0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  f this variable.
380f0 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  ** is a NULL poi
38100 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
38110 65 20 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61  e performs a sea
38120 72 63 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f  rch for an appro
38130 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72  priate.** tempor
38140 61 72 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f  ary file directo
38150 72 79 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63  ry..**.** Applic
38160 61 74 69 6f 6e 73 20 61 72 65 20 73 74 72 6f 6e  ations are stron
38170 67 6c 79 20 64 69 73 63 6f 75 72 61 67 65 64 20  gly discouraged 
38180 66 72 6f 6d 20 75 73 69 6e 67 20 74 68 69 73 20  from using this 
38190 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 2e  global variable.
381a0 0a 2a 2a 20 49 74 20 69 73 20 72 65 71 75 69 72  .** It is requir
381b0 65 64 20 74 6f 20 73 65 74 20 61 20 74 65 6d 70  ed to set a temp
381c0 6f 72 61 72 79 20 66 6f 6c 64 65 72 20 6f 6e 20  orary folder on 
381d0 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20  Windows Runtime 
381e0 28 57 69 6e 52 54 29 2e 0a 2a 2a 20 42 75 74 20  (WinRT)..** But 
381f0 66 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 70 6c  for all other pl
38200 61 74 66 6f 72 6d 73 2c 20 69 74 20 69 73 20 68  atforms, it is h
38210 69 67 68 6c 79 20 72 65 63 6f 6d 6d 65 6e 64 65  ighly recommende
38220 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69  d that applicati
38230 6f 6e 73 0a 2a 2a 20 6e 65 69 74 68 65 72 20 72  ons.** neither r
38240 65 61 64 20 6e 6f 72 20 77 72 69 74 65 20 74 68  ead nor write th
38250 69 73 20 76 61 72 69 61 62 6c 65 2e 20 20 54 68  is variable.  Th
38260 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  is global variab
38270 6c 65 20 69 73 20 61 20 72 65 6c 69 63 0a 2a 2a  le is a relic.**
38280 20 74 68 61 74 20 65 78 69 73 74 73 20 66 6f 72   that exists for
38290 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
382a0 74 69 62 69 6c 69 74 79 20 6f 66 20 6c 65 67 61  tibility of lega
382b0 63 79 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  cy applications 
382c0 61 6e 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65  and should.** be
382d0 20 61 76 6f 69 64 65 64 20 69 6e 20 6e 65 77 20   avoided in new 
382e0 70 72 6f 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20  projects..**.** 
382f0 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74  It is not safe t
38300 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79  o read or modify
38310 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 69   this variable i
38320 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a  n more than one.
38330 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61 20 74  ** thread at a t
38340 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20  ime.  It is not 
38350 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20  safe to read or 
38360 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38370 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61  able.** if a [da
38380 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38390 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73 65 64  n] is being used
383a0 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d   at the same tim
383b0 65 20 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a  e in a separate.
383c0 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74  ** thread..** It
383d0 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61   is intended tha
383e0 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
383f0 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61  be set once.** a
38400 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73  s part of proces
38410 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
38420 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20   and before any 
38430 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
38440 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76  .** routines hav
38450 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e  e been called an
38460 64 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  d that this vari
38470 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68  able remain unch
38480 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66  anged.** thereaf
38490 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
384a0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
384b0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61  ctory pragma] ma
384c0 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  y modify this va
384d0 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65  riable and cause
384e0 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20  .** it to point 
384f0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
38500 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
38510 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74  _malloc].  ^Furt
38520 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20  hermore,.** the 
38530 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
38540 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c  ctory pragma] al
38550 77 61 79 73 20 61 73 73 75 6d 65 73 20 74 68 61  ways assumes tha
38560 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20  t any string.** 
38570 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
38580 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20  le points to is 
38590 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f  held in memory o
385a0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a  btained from .**
385b0 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
385c0 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61  ] and the pragma
385d0 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20   may attempt to 
385e0 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79  free that memory
385f0 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  .** using [sqlit
38600 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e  e3_free]..** Hen
38610 63 65 2c 20 69 66 20 74 68 69 73 20 76 61 72 69  ce, if this vari
38620 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64  able is modified
38630 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65   directly, eithe
38640 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a  r it should be.*
38650 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d  * made NULL or m
38660 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20  ade to point to 
38670 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
38680 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
38690 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65  lloc].** or else
386a0 20 74 68 65 20 75 73 65 20 6f 66 20 74 68 65 20   the use of the 
386b0 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
386c0 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68  ctory pragma] sh
386d0 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e  ould be avoided.
386e0 0a 2a 2a 20 45 78 63 65 70 74 20 77 68 65 6e 20  .** Except when 
386f0 72 65 71 75 65 73 74 65 64 20 62 79 20 74 68 65  requested by the
38700 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72   [temp_store_dir
38710 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20  ectory pragma], 
38720 53 51 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e  SQLite.** does n
38730 6f 74 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f  ot free the memo
38740 72 79 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f  ry that sqlite3_
38750 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 70  temp_directory p
38760 6f 69 6e 74 73 20 74 6f 2e 20 20 49 66 0a 2a 2a  oints to.  If.**
38770 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
38780 20 77 61 6e 74 73 20 74 68 61 74 20 6d 65 6d 6f   wants that memo
38790 72 79 20 74 6f 20 62 65 20 66 72 65 65 64 2c 20  ry to be freed, 
387a0 69 74 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 73 6f  it must do.** so
387b0 20 69 74 73 65 6c 66 2c 20 74 61 6b 69 6e 67 20   itself, taking 
387c0 63 61 72 65 20 74 6f 20 6f 6e 6c 79 20 64 6f 20  care to only do 
387d0 73 6f 20 61 66 74 65 72 20 61 6c 6c 20 5b 64 61  so after all [da
387e0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
387f0 6e 5d 0a 2a 2a 20 6f 62 6a 65 63 74 73 20 68 61  n].** objects ha
38800 76 65 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65  ve been destroye
38810 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65  d..**.** <b>Note
38820 20 74 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74   to Windows Runt
38830 69 6d 65 20 75 73