/ Hex Artifact Content
Login

Artifact fef15a64d1358f5c365bd3f46f4c1915d5a5e5f0:


0000: 2f 2a 0a 2a 2a 20 32 30 30 31 20 53 65 70 74 65  /*.** 2001 Septe
0010: 6d 62 65 72 20 31 35 0a 2a 2a 0a 2a 2a 20 54 68  mber 15.**.** Th
0020: 65 20 61 75 74 68 6f 72 20 64 69 73 63 6c 61 69  e author disclai
0030: 6d 73 20 63 6f 70 79 72 69 67 68 74 20 74 6f 20  ms copyright to 
0040: 74 68 69 73 20 73 6f 75 72 63 65 20 63 6f 64 65  this source code
0050: 2e 20 20 49 6e 20 70 6c 61 63 65 20 6f 66 0a 2a  .  In place of.*
0060: 2a 20 61 20 6c 65 67 61 6c 20 6e 6f 74 69 63 65  * a legal notice
0070: 2c 20 68 65 72 65 20 69 73 20 61 20 62 6c 65 73  , here is a bles
0080: 73 69 6e 67 3a 0a 2a 2a 0a 2a 2a 20 20 20 20 4d  sing:.**.**    M
0090: 61 79 20 79 6f 75 20 64 6f 20 67 6f 6f 64 20 61  ay you do good a
00a0: 6e 64 20 6e 6f 74 20 65 76 69 6c 2e 0a 2a 2a 20  nd not evil..** 
00b0: 20 20 20 4d 61 79 20 79 6f 75 20 66 69 6e 64 20     May you find 
00c0: 66 6f 72 67 69 76 65 6e 65 73 73 20 66 6f 72 20  forgiveness for 
00d0: 79 6f 75 72 73 65 6c 66 20 61 6e 64 20 66 6f 72  yourself and for
00e0: 67 69 76 65 20 6f 74 68 65 72 73 2e 0a 2a 2a 20  give others..** 
00f0: 20 20 20 4d 61 79 20 79 6f 75 20 73 68 61 72 65     May you share
0100: 20 66 72 65 65 6c 79 2c 20 6e 65 76 65 72 20 74   freely, never t
0110: 61 6b 69 6e 67 20 6d 6f 72 65 20 74 68 61 6e 20  aking more than 
0120: 79 6f 75 20 67 69 76 65 2e 0a 2a 2a 0a 2a 2a 2a  you give..**.***
0130: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0140: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0150: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0160: 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
0170: 2a 2a 2a 2a 2a 2a 0a 2a 2a 20 54 68 69 73 20 68  ******.** This h
0180: 65 61 64 65 72 20 66 69 6c 65 20 64 65 66 69 6e  eader file defin
0190: 65 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65  es the interface
01a0: 20 74 68 61 74 20 74 68 65 20 53 51 4c 69 74 65   that the SQLite
01b0: 20 6c 69 62 72 61 72 79 0a 2a 2a 20 70 72 65 73   library.** pres
01c0: 65 6e 74 73 20 74 6f 20 63 6c 69 65 6e 74 20 70  ents to client p
01d0: 72 6f 67 72 61 6d 73 2e 20 20 49 66 20 61 20 43  rograms.  If a C
01e0: 2d 66 75 6e 63 74 69 6f 6e 2c 20 73 74 72 75 63  -function, struc
01f0: 74 75 72 65 2c 20 64 61 74 61 74 79 70 65 2c 0a  ture, datatype,.
0200: 2a 2a 20 6f 72 20 63 6f 6e 73 74 61 6e 74 20 64  ** or constant d
0210: 65 66 69 6e 69 74 69 6f 6e 20 64 6f 65 73 20 6e  efinition does n
0220: 6f 74 20 61 70 70 65 61 72 20 69 6e 20 74 68 69  ot appear in thi
0230: 73 20 66 69 6c 65 2c 20 74 68 65 6e 20 69 74 20  s file, then it 
0240: 69 73 0a 2a 2a 20 6e 6f 74 20 61 20 70 75 62 6c  is.** not a publ
0250: 69 73 68 65 64 20 41 50 49 20 6f 66 20 53 51 4c  ished API of SQL
0260: 69 74 65 2c 20 69 73 20 73 75 62 6a 65 63 74 20  ite, is subject 
0270: 74 6f 20 63 68 61 6e 67 65 20 77 69 74 68 6f 75  to change withou
0280: 74 0a 2a 2a 20 6e 6f 74 69 63 65 2c 20 61 6e 64  t.** notice, and
0290: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 72   should not be r
02a0: 65 66 65 72 65 6e 63 65 64 20 62 79 20 70 72 6f  eferenced by pro
02b0: 67 72 61 6d 73 20 74 68 61 74 20 75 73 65 20 53  grams that use S
02c0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 6f 6d  QLite..**.** Som
02d0: 65 20 6f 66 20 74 68 65 20 64 65 66 69 6e 69 74  e of the definit
02e0: 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20 69 6e  ions that are in
02f0: 20 74 68 69 73 20 66 69 6c 65 20 61 72 65 20 6d   this file are m
0300: 61 72 6b 65 64 20 61 73 0a 2a 2a 20 22 65 78 70  arked as.** "exp
0310: 65 72 69 6d 65 6e 74 61 6c 22 2e 20 20 45 78 70  erimental".  Exp
0320: 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74 65 72 66  erimental interf
0330: 61 63 65 73 20 61 72 65 20 6e 6f 72 6d 61 6c 6c  aces are normall
0340: 79 20 6e 65 77 0a 2a 2a 20 66 65 61 74 75 72 65  y new.** feature
0350: 73 20 72 65 63 65 6e 74 6c 79 20 61 64 64 65 64  s recently added
0360: 20 74 6f 20 53 51 4c 69 74 65 2e 20 20 57 65 20   to SQLite.  We 
0370: 64 6f 20 6e 6f 74 20 61 6e 74 69 63 69 70 61 74  do not anticipat
0380: 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20 74 6f 20  e changes.** to 
0390: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
03a0: 65 72 66 61 63 65 73 20 62 75 74 20 72 65 73 65  erfaces but rese
03b0: 72 76 65 20 74 68 65 20 72 69 67 68 74 20 74 6f  rve the right to
03c0: 20 6d 61 6b 65 20 6d 69 6e 6f 72 20 63 68 61 6e   make minor chan
03d0: 67 65 73 0a 2a 2a 20 69 66 20 65 78 70 65 72 69  ges.** if experi
03e0: 65 6e 63 65 20 66 72 6f 6d 20 75 73 65 20 22 69  ence from use "i
03f0: 6e 20 74 68 65 20 77 69 6c 64 22 20 73 75 67 67  n the wild" sugg
0400: 65 73 74 20 73 75 63 68 20 63 68 61 6e 67 65 73  est such changes
0410: 20 61 72 65 20 70 72 75 64 65 6e 74 2e 0a 2a 2a   are prudent..**
0420: 0a 2a 2a 20 54 68 65 20 6f 66 66 69 63 69 61 6c  .** The official
0430: 20 43 2d 6c 61 6e 67 75 61 67 65 20 41 50 49 20   C-language API 
0440: 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
0450: 72 20 53 51 4c 69 74 65 20 69 73 20 64 65 72 69  r SQLite is deri
0460: 76 65 64 0a 2a 2a 20 66 72 6f 6d 20 63 6f 6d 6d  ved.** from comm
0470: 65 6e 74 73 20 69 6e 20 74 68 69 73 20 66 69 6c  ents in this fil
0480: 65 2e 20 20 54 68 69 73 20 66 69 6c 65 20 69 73  e.  This file is
0490: 20 74 68 65 20 61 75 74 68 6f 72 69 74 61 74 69   the authoritati
04a0: 76 65 20 73 6f 75 72 63 65 0a 2a 2a 20 6f 6e 20  ve source.** on 
04b0: 68 6f 77 20 53 51 4c 69 74 65 20 69 6e 74 65 72  how SQLite inter
04c0: 66 61 63 65 73 20 61 72 65 20 73 75 70 70 6f 73  faces are suppos
04d0: 65 20 74 6f 20 6f 70 65 72 61 74 65 2e 0a 2a 2a  e to operate..**
04e0: 0a 2a 2a 20 54 68 65 20 6e 61 6d 65 20 6f 66 20  .** The name of 
04f0: 74 68 69 73 20 66 69 6c 65 20 75 6e 64 65 72 20  this file under 
0500: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61  configuration ma
0510: 6e 61 67 65 6d 65 6e 74 20 69 73 20 22 73 71 6c  nagement is "sql
0520: 69 74 65 2e 68 2e 69 6e 22 2e 0a 2a 2a 20 54 68  ite.h.in"..** Th
0530: 65 20 6d 61 6b 65 66 69 6c 65 20 6d 61 6b 65 73  e makefile makes
0540: 20 73 6f 6d 65 20 6d 69 6e 6f 72 20 63 68 61 6e   some minor chan
0550: 67 65 73 20 74 6f 20 74 68 69 73 20 66 69 6c 65  ges to this file
0560: 20 28 73 75 63 68 20 61 73 20 69 6e 73 65 72 74   (such as insert
0570: 69 6e 67 0a 2a 2a 20 74 68 65 20 76 65 72 73 69  ing.** the versi
0580: 6f 6e 20 6e 75 6d 62 65 72 29 20 61 6e 64 20 63  on number) and c
0590: 68 61 6e 67 65 73 20 69 74 73 20 6e 61 6d 65 20  hanges its name 
05a0: 74 6f 20 22 73 71 6c 69 74 65 33 2e 68 22 20 61  to "sqlite3.h" a
05b0: 73 0a 2a 2a 20 70 61 72 74 20 6f 66 20 74 68 65  s.** part of the
05c0: 20 62 75 69 6c 64 20 70 72 6f 63 65 73 73 2e 0a   build process..
05d0: 2a 2f 0a 23 69 66 6e 64 65 66 20 5f 53 51 4c 49  */.#ifndef _SQLI
05e0: 54 45 33 5f 48 5f 0a 23 64 65 66 69 6e 65 20 5f  TE3_H_.#define _
05f0: 53 51 4c 49 54 45 33 5f 48 5f 0a 23 69 6e 63 6c  SQLITE3_H_.#incl
0600: 75 64 65 20 3c 73 74 64 61 72 67 2e 68 3e 20 20  ude <stdarg.h>  
0610: 20 20 20 2f 2a 20 4e 65 65 64 65 64 20 66 6f 72     /* Needed for
0620: 20 74 68 65 20 64 65 66 69 6e 69 74 69 6f 6e 20   the definition 
0630: 6f 66 20 76 61 5f 6c 69 73 74 20 2a 2f 0a 0a 2f  of va_list */../
0640: 2a 0a 2a 2a 20 4d 61 6b 65 20 73 75 72 65 20 77  *.** Make sure w
0650: 65 20 63 61 6e 20 63 61 6c 6c 20 74 68 69 73 20  e can call this 
0660: 73 74 75 66 66 20 66 72 6f 6d 20 43 2b 2b 2e 0a  stuff from C++..
0670: 2a 2f 0a 23 69 66 64 65 66 20 5f 5f 63 70 6c 75  */.#ifdef __cplu
0680: 73 70 6c 75 73 0a 65 78 74 65 72 6e 20 22 43 22  splus.extern "C"
0690: 20 7b 0a 23 65 6e 64 69 66 0a 0a 0a 2f 2a 0a 2a   {.#endif.../*.*
06a0: 2a 20 41 64 64 20 74 68 65 20 61 62 69 6c 69 74  * Add the abilit
06b0: 79 20 74 6f 20 6f 76 65 72 72 69 64 65 20 27 65  y to override 'e
06c0: 78 74 65 72 6e 27 0a 2a 2f 0a 23 69 66 6e 64 65  xtern'.*/.#ifnde
06d0: 66 20 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 0a  f SQLITE_EXTERN.
06e0: 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  # define SQLITE_
06f0: 45 58 54 45 52 4e 20 65 78 74 65 72 6e 0a 23 65  EXTERN extern.#e
0700: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 73  ndif../*.** Thes
0710: 65 20 6e 6f 2d 6f 70 20 6d 61 63 72 6f 73 20 61  e no-op macros a
0720: 72 65 20 75 73 65 64 20 69 6e 20 66 72 6f 6e 74  re used in front
0730: 20 6f 66 20 69 6e 74 65 72 66 61 63 65 73 20 74   of interfaces t
0740: 6f 20 6d 61 72 6b 20 74 68 6f 73 65 0a 2a 2a 20  o mark those.** 
0750: 69 6e 74 65 72 66 61 63 65 73 20 61 73 20 65 69  interfaces as ei
0760: 74 68 65 72 20 64 65 70 72 65 63 61 74 65 64 20  ther deprecated 
0770: 6f 72 20 65 78 70 65 72 69 6d 65 6e 74 61 6c 2e  or experimental.
0780: 20 20 4e 65 77 20 61 70 70 6c 69 63 61 74 69 6f    New applicatio
0790: 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 6f 74  ns.** should not
07a0: 20 75 73 65 20 64 65 70 72 65 63 61 74 65 64 20   use deprecated 
07b0: 69 6e 74 65 72 66 61 63 65 73 20 2d 20 74 68 65  interfaces - the
07c0: 79 20 61 72 65 20 73 75 70 70 6f 72 74 20 66 6f  y are support fo
07d0: 72 20 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63  r backwards.** c
07e0: 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c  ompatibility onl
07f0: 79 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 20  y.  Application 
0800: 77 72 69 74 65 72 73 20 73 68 6f 75 6c 64 20 62  writers should b
0810: 65 20 61 77 61 72 65 20 74 68 61 74 0a 2a 2a 20  e aware that.** 
0820: 65 78 70 65 72 69 6d 65 6e 74 61 6c 20 69 6e 74  experimental int
0830: 65 72 66 61 63 65 73 20 61 72 65 20 73 75 62 6a  erfaces are subj
0840: 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
0850: 20 70 6f 69 6e 74 20 72 65 6c 65 61 73 65 73 2e   point releases.
0860: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 6d 61 63  .**.** These mac
0870: 72 6f 73 20 75 73 65 64 20 74 6f 20 72 65 73 6f  ros used to reso
0880: 6c 76 65 20 74 6f 20 76 61 72 69 6f 75 73 20 6b  lve to various k
0890: 69 6e 64 73 20 6f 66 20 63 6f 6d 70 69 6c 65 72  inds of compiler
08a0: 20 6d 61 67 69 63 20 74 68 61 74 0a 2a 2a 20 77   magic that.** w
08b0: 6f 75 6c 64 20 67 65 6e 65 72 61 74 65 20 77 61  ould generate wa
08c0: 72 6e 69 6e 67 20 6d 65 73 73 61 67 65 73 20 77  rning messages w
08d0: 68 65 6e 20 74 68 65 79 20 77 65 72 65 20 75 73  hen they were us
08e0: 65 64 2e 20 20 42 75 74 20 74 68 61 74 0a 2a 2a  ed.  But that.**
08f0: 20 63 6f 6d 70 69 6c 65 72 20 6d 61 67 69 63 20   compiler magic 
0900: 65 6e 64 65 64 20 75 70 20 67 65 6e 65 72 61 74  ended up generat
0910: 69 6e 67 20 73 75 63 68 20 61 20 66 6c 75 72 72  ing such a flurr
0920: 79 20 6f 66 20 62 75 67 20 72 65 70 6f 72 74 73  y of bug reports
0930: 0a 2a 2a 20 74 68 61 74 20 77 65 20 68 61 76 65  .** that we have
0940: 20 74 61 6b 65 6e 20 69 74 20 61 6c 6c 20 6f 75   taken it all ou
0950: 74 20 61 6e 64 20 67 6f 6e 65 20 62 61 63 6b 20  t and gone back 
0960: 74 6f 20 75 73 69 6e 67 20 73 69 6d 70 6c 65 0a  to using simple.
0970: 2a 2a 20 6e 6f 6f 70 20 6d 61 63 72 6f 73 2e 0a  ** noop macros..
0980: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
0990: 45 5f 44 45 50 52 45 43 41 54 45 44 0a 23 64 65  E_DEPRECATED.#de
09a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 58 50 45  fine SQLITE_EXPE
09b0: 52 49 4d 45 4e 54 41 4c 0a 0a 2f 2a 0a 2a 2a 20  RIMENTAL../*.** 
09c0: 45 6e 73 75 72 65 20 74 68 65 73 65 20 73 79 6d  Ensure these sym
09d0: 62 6f 6c 73 20 77 65 72 65 20 6e 6f 74 20 64 65  bols were not de
09e0: 66 69 6e 65 64 20 62 79 20 73 6f 6d 65 20 70 72  fined by some pr
09f0: 65 76 69 6f 75 73 20 68 65 61 64 65 72 20 66 69  evious header fi
0a00: 6c 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53 51  le..*/.#ifdef SQ
0a10: 4c 49 54 45 5f 56 45 52 53 49 4f 4e 0a 23 20 75  LITE_VERSION.# u
0a20: 6e 64 65 66 20 53 51 4c 49 54 45 5f 56 45 52 53  ndef SQLITE_VERS
0a30: 49 4f 4e 0a 23 65 6e 64 69 66 0a 23 69 66 64 65  ION.#endif.#ifde
0a40: 66 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e  f SQLITE_VERSION
0a50: 5f 4e 55 4d 42 45 52 0a 23 20 75 6e 64 65 66 20  _NUMBER.# undef 
0a60: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f 4e  SQLITE_VERSION_N
0a70: 55 4d 42 45 52 0a 23 65 6e 64 69 66 0a 0a 2f 2a  UMBER.#endif../*
0a80: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
0a90: 6d 70 69 6c 65 2d 54 69 6d 65 20 4c 69 62 72 61  mpile-Time Libra
0aa0: 72 79 20 56 65 72 73 69 6f 6e 20 4e 75 6d 62 65  ry Version Numbe
0ab0: 72 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 5b  rs.**.** ^(The [
0ac0: 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5d 20  SQLITE_VERSION] 
0ad0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
0ae0: 61 63 72 6f 20 69 6e 20 74 68 65 20 73 71 6c 69  acro in the sqli
0af0: 74 65 33 2e 68 20 68 65 61 64 65 72 0a 2a 2a 20  te3.h header.** 
0b00: 65 76 61 6c 75 61 74 65 73 20 74 6f 20 61 20 73  evaluates to a s
0b10: 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 20 74 68  tring literal th
0b20: 61 74 20 69 73 20 74 68 65 20 53 51 4c 69 74 65  at is the SQLite
0b30: 20 76 65 72 73 69 6f 6e 20 69 6e 20 74 68 65 0a   version in the.
0b40: 2a 2a 20 66 6f 72 6d 61 74 20 22 58 2e 59 2e 5a  ** format "X.Y.Z
0b50: 22 20 77 68 65 72 65 20 58 20 69 73 20 74 68 65  " where X is the
0b60: 20 6d 61 6a 6f 72 20 76 65 72 73 69 6f 6e 20 6e   major version n
0b70: 75 6d 62 65 72 20 28 61 6c 77 61 79 73 20 33 20  umber (always 3 
0b80: 66 6f 72 0a 2a 2a 20 53 51 4c 69 74 65 33 29 20  for.** SQLite3) 
0b90: 61 6e 64 20 59 20 69 73 20 74 68 65 20 6d 69 6e  and Y is the min
0ba0: 6f 72 20 76 65 72 73 69 6f 6e 20 6e 75 6d 62 65  or version numbe
0bb0: 72 20 61 6e 64 20 5a 20 69 73 20 74 68 65 20 72  r and Z is the r
0bc0: 65 6c 65 61 73 65 20 6e 75 6d 62 65 72 2e 29 5e  elease number.)^
0bd0: 0a 2a 2a 20 5e 28 54 68 65 20 5b 53 51 4c 49 54  .** ^(The [SQLIT
0be0: 45 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52  E_VERSION_NUMBER
0bf0: 5d 20 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C preprocessor
0c00: 20 6d 61 63 72 6f 20 72 65 73 6f 6c 76 65 73 20   macro resolves 
0c10: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  to an integer.**
0c20: 20 77 69 74 68 20 74 68 65 20 76 61 6c 75 65 20   with the value 
0c30: 28 58 2a 31 30 30 30 30 30 30 20 2b 20 59 2a 31  (X*1000000 + Y*1
0c40: 30 30 30 20 2b 20 5a 29 20 77 68 65 72 65 20 58  000 + Z) where X
0c50: 2c 20 59 2c 20 61 6e 64 20 5a 20 61 72 65 20 74  , Y, and Z are t
0c60: 68 65 20 73 61 6d 65 0a 2a 2a 20 6e 75 6d 62 65  he same.** numbe
0c70: 72 73 20 75 73 65 64 20 69 6e 20 5b 53 51 4c 49  rs used in [SQLI
0c80: 54 45 5f 56 45 52 53 49 4f 4e 5d 2e 29 5e 0a 2a  TE_VERSION].)^.*
0c90: 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 56 45 52  * The SQLITE_VER
0ca0: 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 66 6f 72 20  SION_NUMBER for 
0cb0: 61 6e 79 20 67 69 76 65 6e 20 72 65 6c 65 61 73  any given releas
0cc0: 65 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c  e of SQLite will
0cd0: 20 61 6c 73 6f 0a 2a 2a 20 62 65 20 6c 61 72 67   also.** be larg
0ce0: 65 72 20 74 68 61 6e 20 74 68 65 20 72 65 6c 65  er than the rele
0cf0: 61 73 65 20 66 72 6f 6d 20 77 68 69 63 68 20 69  ase from which i
0d00: 74 20 69 73 20 64 65 72 69 76 65 64 2e 20 20 45  t is derived.  E
0d10: 69 74 68 65 72 20 59 20 77 69 6c 6c 0a 2a 2a 20  ither Y will.** 
0d20: 62 65 20 68 65 6c 64 20 63 6f 6e 73 74 61 6e 74  be held constant
0d30: 20 61 6e 64 20 5a 20 77 69 6c 6c 20 62 65 20 69   and Z will be i
0d40: 6e 63 72 65 6d 65 6e 74 65 64 20 6f 72 20 65 6c  ncremented or el
0d50: 73 65 20 59 20 77 69 6c 6c 20 62 65 20 69 6e 63  se Y will be inc
0d60: 72 65 6d 65 6e 74 65 64 0a 2a 2a 20 61 6e 64 20  remented.** and 
0d70: 5a 20 77 69 6c 6c 20 62 65 20 72 65 73 65 74 20  Z will be reset 
0d80: 74 6f 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53  to zero..**.** S
0d90: 69 6e 63 65 20 76 65 72 73 69 6f 6e 20 33 2e 36  ince version 3.6
0da0: 2e 31 38 2c 20 53 51 4c 69 74 65 20 73 6f 75 72  .18, SQLite sour
0db0: 63 65 20 63 6f 64 65 20 68 61 73 20 62 65 65 6e  ce code has been
0dc0: 20 73 74 6f 72 65 64 20 69 6e 20 74 68 65 0a 2a   stored in the.*
0dd0: 2a 20 3c 61 20 68 72 65 66 3d 22 68 74 74 70 3a  * <a href="http:
0de0: 2f 2f 77 77 77 2e 66 6f 73 73 69 6c 2d 73 63 6d  //www.fossil-scm
0df0: 2e 6f 72 67 2f 22 3e 46 6f 73 73 69 6c 20 63 6f  .org/">Fossil co
0e00: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61  nfiguration mana
0e10: 67 65 6d 65 6e 74 0a 2a 2a 20 73 79 73 74 65 6d  gement.** system
0e20: 3c 2f 61 3e 2e 20 20 5e 54 68 65 20 53 51 4c 49  </a>.  ^The SQLI
0e30: 54 45 5f 53 4f 55 52 43 45 5f 49 44 20 6d 61 63  TE_SOURCE_ID mac
0e40: 72 6f 20 65 76 61 6c 75 61 74 65 73 20 74 6f 0a  ro evaluates to.
0e50: 2a 2a 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  ** a string whic
0e60: 68 20 69 64 65 6e 74 69 66 69 65 73 20 61 20 70  h identifies a p
0e70: 61 72 74 69 63 75 6c 61 72 20 63 68 65 63 6b 2d  articular check-
0e80: 69 6e 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20  in of SQLite.** 
0e90: 77 69 74 68 69 6e 20 69 74 73 20 63 6f 6e 66 69  within its confi
0ea0: 67 75 72 61 74 69 6f 6e 20 6d 61 6e 61 67 65 6d  guration managem
0eb0: 65 6e 74 20 73 79 73 74 65 6d 2e 20 20 5e 54 68  ent system.  ^Th
0ec0: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
0ed0: 49 44 0a 2a 2a 20 73 74 72 69 6e 67 20 63 6f 6e  ID.** string con
0ee0: 74 61 69 6e 73 20 74 68 65 20 64 61 74 65 20 61  tains the date a
0ef0: 6e 64 20 74 69 6d 65 20 6f 66 20 74 68 65 20 63  nd time of the c
0f00: 68 65 63 6b 2d 69 6e 20 28 55 54 43 29 20 61 6e  heck-in (UTC) an
0f10: 64 20 61 6e 20 53 48 41 31 0a 2a 2a 20 68 61 73  d an SHA1.** has
0f20: 68 20 6f 66 20 74 68 65 20 65 6e 74 69 72 65 20  h of the entire 
0f30: 73 6f 75 72 63 65 20 74 72 65 65 2e 0a 2a 2a 0a  source tree..**.
0f40: 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
0f50: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
0f60: 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
0f70: 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e 75 6d 62  _libversion_numb
0f80: 65 72 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  er()], [sqlite3_
0f90: 73 6f 75 72 63 65 69 64 28 29 5d 2c 0a 2a 2a 20  sourceid()],.** 
0fa0: 5b 73 71 6c 69 74 65 5f 76 65 72 73 69 6f 6e 28  [sqlite_version(
0fb0: 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 5f 73  )] and [sqlite_s
0fc0: 6f 75 72 63 65 5f 69 64 28 29 5d 2e 0a 2a 2f 0a  ource_id()]..*/.
0fd0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 56  #define SQLITE_V
0fe0: 45 52 53 49 4f 4e 20 20 20 20 20 20 20 20 22 2d  ERSION        "-
0ff0: 2d 56 45 52 53 2d 2d 22 0a 23 64 65 66 69 6e 65  -VERS--".#define
1000: 20 53 51 4c 49 54 45 5f 56 45 52 53 49 4f 4e 5f   SQLITE_VERSION_
1010: 4e 55 4d 42 45 52 20 2d 2d 56 45 52 53 49 4f 4e  NUMBER --VERSION
1020: 2d 4e 55 4d 42 45 52 2d 2d 0a 23 64 65 66 69 6e  -NUMBER--.#defin
1030: 65 20 53 51 4c 49 54 45 5f 53 4f 55 52 43 45 5f  e SQLITE_SOURCE_
1040: 49 44 20 20 20 20 20 20 22 2d 2d 53 4f 55 52 43  ID      "--SOURC
1050: 45 2d 49 44 2d 2d 22 0a 0a 2f 2a 0a 2a 2a 20 43  E-ID--"../*.** C
1060: 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d  API3REF: Run-Tim
1070: 65 20 4c 69 62 72 61 72 79 20 56 65 72 73 69 6f  e Library Versio
1080: 6e 20 4e 75 6d 62 65 72 73 0a 2a 2a 20 4b 45 59  n Numbers.** KEY
1090: 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 76  WORDS: sqlite3_v
10a0: 65 72 73 69 6f 6e 2c 20 73 71 6c 69 74 65 33 5f  ersion, sqlite3_
10b0: 73 6f 75 72 63 65 69 64 0a 2a 2a 0a 2a 2a 20 54  sourceid.**.** T
10c0: 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73 20  hese interfaces 
10d0: 70 72 6f 76 69 64 65 20 74 68 65 20 73 61 6d 65  provide the same
10e0: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 73 20   information as 
10f0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  the [SQLITE_VERS
1100: 49 4f 4e 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  ION],.** [SQLITE
1110: 5f 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 5d  _VERSION_NUMBER]
1120: 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 53 4f  , and [SQLITE_SO
1130: 55 52 43 45 5f 49 44 5d 20 43 20 70 72 65 70 72  URCE_ID] C prepr
1140: 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 73 0a 2a  ocessor macros.*
1150: 2a 20 62 75 74 20 61 72 65 20 61 73 73 6f 63 69  * but are associ
1160: 61 74 65 64 20 77 69 74 68 20 74 68 65 20 6c 69  ated with the li
1170: 62 72 61 72 79 20 69 6e 73 74 65 61 64 20 6f 66  brary instead of
1180: 20 74 68 65 20 68 65 61 64 65 72 20 66 69 6c 65   the header file
1190: 2e 20 20 5e 28 43 61 75 74 69 6f 75 73 0a 2a 2a  .  ^(Cautious.**
11a0: 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67   programmers mig
11b0: 68 74 20 69 6e 63 6c 75 64 65 20 61 73 73 65 72  ht include asser
11c0: 74 28 29 20 73 74 61 74 65 6d 65 6e 74 73 20 69  t() statements i
11d0: 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 74  n their applicat
11e0: 69 6f 6e 20 74 6f 0a 2a 2a 20 76 65 72 69 66 79  ion to.** verify
11f0: 20 74 68 61 74 20 76 61 6c 75 65 73 20 72 65 74   that values ret
1200: 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 69  urned by these i
1210: 6e 74 65 72 66 61 63 65 73 20 6d 61 74 63 68 20  nterfaces match 
1220: 74 68 65 20 6d 61 63 72 6f 73 20 69 6e 0a 2a 2a  the macros in.**
1230: 20 74 68 65 20 68 65 61 64 65 72 2c 20 61 6e 64   the header, and
1240: 20 74 68 75 73 20 69 6e 73 75 72 65 20 74 68 61   thus insure tha
1250: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
1260: 6e 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  n is.** compiled
1270: 20 77 69 74 68 20 6d 61 74 63 68 69 6e 67 20 6c   with matching l
1280: 69 62 72 61 72 79 20 61 6e 64 20 68 65 61 64 65  ibrary and heade
1290: 72 20 66 69 6c 65 73 2e 0a 2a 2a 0a 2a 2a 20 3c  r files..**.** <
12a0: 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
12b0: 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 71 6c 69  .** assert( sqli
12c0: 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e 5f 6e  te3_libversion_n
12d0: 75 6d 62 65 72 28 29 3d 3d 53 51 4c 49 54 45 5f  umber()==SQLITE_
12e0: 56 45 52 53 49 4f 4e 5f 4e 55 4d 42 45 52 20 29  VERSION_NUMBER )
12f0: 3b 0a 2a 2a 20 61 73 73 65 72 74 28 20 73 74 72  ;.** assert( str
1300: 63 6d 70 28 73 71 6c 69 74 65 33 5f 73 6f 75 72  cmp(sqlite3_sour
1310: 63 65 69 64 28 29 2c 53 51 4c 49 54 45 5f 53 4f  ceid(),SQLITE_SO
1320: 55 52 43 45 5f 49 44 29 3d 3d 30 20 29 3b 0a 2a  URCE_ID)==0 );.*
1330: 2a 20 61 73 73 65 72 74 28 20 73 74 72 63 6d 70  * assert( strcmp
1340: 28 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73  (sqlite3_libvers
1350: 69 6f 6e 28 29 2c 53 51 4c 49 54 45 5f 56 45 52  ion(),SQLITE_VER
1360: 53 49 4f 4e 29 3d 3d 30 20 29 3b 0a 2a 2a 20 3c  SION)==0 );.** <
1370: 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
1380: 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  e>)^.**.** ^The 
1390: 73 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b  sqlite3_version[
13a0: 5d 20 73 74 72 69 6e 67 20 63 6f 6e 73 74 61 6e  ] string constan
13b0: 74 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 74  t contains the t
13c0: 65 78 74 20 6f 66 20 5b 53 51 4c 49 54 45 5f 56  ext of [SQLITE_V
13d0: 45 52 53 49 4f 4e 5d 0a 2a 2a 20 6d 61 63 72 6f  ERSION].** macro
13e0: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
13f0: 6c 69 62 76 65 72 73 69 6f 6e 28 29 20 66 75 6e  libversion() fun
1400: 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 20  ction returns a 
1410: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
1420: 2a 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  * to the sqlite3
1430: 5f 76 65 72 73 69 6f 6e 5b 5d 20 73 74 72 69 6e  _version[] strin
1440: 67 20 63 6f 6e 73 74 61 6e 74 2e 20 20 54 68 65  g constant.  The
1450: 20 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73   sqlite3_libvers
1460: 69 6f 6e 28 29 0a 2a 2a 20 66 75 6e 63 74 69 6f  ion().** functio
1470: 6e 20 69 73 20 70 72 6f 76 69 64 65 64 20 66 6f  n is provided fo
1480: 72 20 75 73 65 20 69 6e 20 44 4c 4c 73 20 73 69  r use in DLLs si
1490: 6e 63 65 20 44 4c 4c 20 75 73 65 72 73 20 75 73  nce DLL users us
14a0: 75 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 68 61 76  ually do not hav
14b0: 65 0a 2a 2a 20 64 69 72 65 63 74 20 61 63 63 65  e.** direct acce
14c0: 73 73 20 74 6f 20 73 74 72 69 6e 67 20 63 6f 6e  ss to string con
14d0: 73 74 61 6e 74 73 20 77 69 74 68 69 6e 20 74 68  stants within th
14e0: 65 20 44 4c 4c 2e 20 20 5e 54 68 65 0a 2a 2a 20  e DLL.  ^The.** 
14f0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
1500: 6f 6e 5f 6e 75 6d 62 65 72 28 29 20 66 75 6e 63  on_number() func
1510: 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 61 6e 20  tion returns an 
1520: 69 6e 74 65 67 65 72 20 65 71 75 61 6c 20 74 6f  integer equal to
1530: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 56 45 52 53  .** [SQLITE_VERS
1540: 49 4f 4e 5f 4e 55 4d 42 45 52 5d 2e 20 20 5e 54  ION_NUMBER].  ^T
1550: 68 65 20 73 71 6c 69 74 65 33 5f 73 6f 75 72 63  he sqlite3_sourc
1560: 65 69 64 28 29 20 66 75 6e 63 74 69 6f 6e 20 72  eid() function r
1570: 65 74 75 72 6e 73 20 0a 2a 2a 20 61 20 70 6f 69  eturns .** a poi
1580: 6e 74 65 72 20 74 6f 20 61 20 73 74 72 69 6e 67  nter to a string
1590: 20 63 6f 6e 73 74 61 6e 74 20 77 68 6f 73 65 20   constant whose 
15a0: 76 61 6c 75 65 20 69 73 20 74 68 65 20 73 61 6d  value is the sam
15b0: 65 20 61 73 20 74 68 65 20 0a 2a 2a 20 5b 53 51  e as the .** [SQ
15c0: 4c 49 54 45 5f 53 4f 55 52 43 45 5f 49 44 5d 20  LITE_SOURCE_ID] 
15d0: 43 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d  C preprocessor m
15e0: 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  acro..**.** See 
15f0: 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 5f 76 65  also: [sqlite_ve
1600: 72 73 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  rsion()] and [sq
1610: 6c 69 74 65 5f 73 6f 75 72 63 65 5f 69 64 28 29  lite_source_id()
1620: 5d 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  ]..*/.SQLITE_EXT
1630: 45 52 4e 20 63 6f 6e 73 74 20 63 68 61 72 20 73  ERN const char s
1640: 71 6c 69 74 65 33 5f 76 65 72 73 69 6f 6e 5b 5d  qlite3_version[]
1650: 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  ;.const char *sq
1660: 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69 6f 6e  lite3_libversion
1670: 28 76 6f 69 64 29 3b 0a 63 6f 6e 73 74 20 63 68  (void);.const ch
1680: 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6f 75 72  ar *sqlite3_sour
1690: 63 65 69 64 28 76 6f 69 64 29 3b 0a 69 6e 74 20  ceid(void);.int 
16a0: 73 71 6c 69 74 65 33 5f 6c 69 62 76 65 72 73 69  sqlite3_libversi
16b0: 6f 6e 5f 6e 75 6d 62 65 72 28 76 6f 69 64 29 3b  on_number(void);
16c0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
16d0: 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69 62 72 61  : Run-Time Libra
16e0: 72 79 20 43 6f 6d 70 69 6c 61 74 69 6f 6e 20 4f  ry Compilation O
16f0: 70 74 69 6f 6e 73 20 44 69 61 67 6e 6f 73 74 69  ptions Diagnosti
1700: 63 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  cs.**.** ^The sq
1710: 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74  lite3_compileopt
1720: 69 6f 6e 5f 75 73 65 64 28 29 20 66 75 6e 63 74  ion_used() funct
1730: 69 6f 6e 20 72 65 74 75 72 6e 73 20 30 20 6f 72  ion returns 0 or
1740: 20 31 20 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e   1 .** indicatin
1750: 67 20 77 68 65 74 68 65 72 20 74 68 65 20 73 70  g whether the sp
1760: 65 63 69 66 69 65 64 20 6f 70 74 69 6f 6e 20 77  ecified option w
1770: 61 73 20 64 65 66 69 6e 65 64 20 61 74 20 0a 2a  as defined at .*
1780: 2a 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  * compile time. 
1790: 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 20 70 72   ^The SQLITE_ pr
17a0: 65 66 69 78 20 6d 61 79 20 62 65 20 6f 6d 69 74  efix may be omit
17b0: 74 65 64 20 66 72 6f 6d 20 74 68 65 20 0a 2a 2a  ted from the .**
17c0: 20 6f 70 74 69 6f 6e 20 6e 61 6d 65 20 70 61 73   option name pas
17d0: 73 65 64 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  sed to sqlite3_c
17e0: 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65  ompileoption_use
17f0: 64 28 29 2e 20 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  d().  .**.** ^Th
1800: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c  e sqlite3_compil
1810: 65 6f 70 74 69 6f 6e 5f 67 65 74 28 29 20 66 75  eoption_get() fu
1820: 6e 63 74 69 6f 6e 20 61 6c 6c 6f 77 73 20 69 74  nction allows it
1830: 65 72 61 74 69 6e 67 0a 2a 2a 20 6f 76 65 72 20  erating.** over 
1840: 74 68 65 20 6c 69 73 74 20 6f 66 20 6f 70 74 69  the list of opti
1850: 6f 6e 73 20 74 68 61 74 20 77 65 72 65 20 64 65  ons that were de
1860: 66 69 6e 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  fined at compile
1870: 20 74 69 6d 65 20 62 79 0a 2a 2a 20 72 65 74 75   time by.** retu
1880: 72 6e 69 6e 67 20 74 68 65 20 4e 2d 74 68 20 63  rning the N-th c
1890: 6f 6d 70 69 6c 65 20 74 69 6d 65 20 6f 70 74 69  ompile time opti
18a0: 6f 6e 20 73 74 72 69 6e 67 2e 20 20 5e 49 66 20  on string.  ^If 
18b0: 4e 20 69 73 20 6f 75 74 20 6f 66 20 72 61 6e 67  N is out of rang
18c0: 65 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f  e,.** sqlite3_co
18d0: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
18e0: 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  ) returns a NULL
18f0: 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20   pointer.  ^The 
1900: 53 51 4c 49 54 45 5f 20 0a 2a 2a 20 70 72 65 66  SQLITE_ .** pref
1910: 69 78 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  ix is omitted fr
1920: 6f 6d 20 61 6e 79 20 73 74 72 69 6e 67 73 20 72  om any strings r
1930: 65 74 75 72 6e 65 64 20 62 79 20 0a 2a 2a 20 73  eturned by .** s
1940: 71 6c 69 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70  qlite3_compileop
1950: 74 69 6f 6e 5f 67 65 74 28 29 2e 0a 2a 2a 0a 2a  tion_get()..**.*
1960: 2a 20 5e 53 75 70 70 6f 72 74 20 66 6f 72 20 74  * ^Support for t
1970: 68 65 20 64 69 61 67 6e 6f 73 74 69 63 20 66 75  he diagnostic fu
1980: 6e 63 74 69 6f 6e 73 20 73 71 6c 69 74 65 33 5f  nctions sqlite3_
1990: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
19a0: 65 64 28 29 0a 2a 2a 20 61 6e 64 20 73 71 6c 69  ed().** and sqli
19b0: 74 65 33 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f  te3_compileoptio
19c0: 6e 5f 67 65 74 28 29 20 6d 61 79 20 62 65 20 6f  n_get() may be o
19d0: 6d 69 74 74 65 64 20 62 79 20 73 70 65 63 69 66  mitted by specif
19e0: 79 69 6e 67 20 74 68 65 20 0a 2a 2a 20 5b 53 51  ying the .** [SQ
19f0: 4c 49 54 45 5f 4f 4d 49 54 5f 43 4f 4d 50 49 4c  LITE_OMIT_COMPIL
1a00: 45 4f 50 54 49 4f 4e 5f 44 49 41 47 53 5d 20 6f  EOPTION_DIAGS] o
1a10: 70 74 69 6f 6e 20 61 74 20 63 6f 6d 70 69 6c 65  ption at compile
1a20: 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65   time..**.** See
1a30: 20 61 6c 73 6f 3a 20 53 51 4c 20 66 75 6e 63 74   also: SQL funct
1a40: 69 6f 6e 73 20 5b 73 71 6c 69 74 65 5f 63 6f 6d  ions [sqlite_com
1a50: 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73 65 64 28  pileoption_used(
1a60: 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  )] and.** [sqlit
1a70: 65 5f 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f  e_compileoption_
1a80: 67 65 74 28 29 5d 20 61 6e 64 20 74 68 65 20 5b  get()] and the [
1a90: 63 6f 6d 70 69 6c 65 5f 6f 70 74 69 6f 6e 73 20  compile_options 
1aa0: 70 72 61 67 6d 61 5d 2e 0a 2a 2f 0a 23 69 66 6e  pragma]..*/.#ifn
1ab0: 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f  def SQLITE_OMIT_
1ac0: 43 4f 4d 50 49 4c 45 4f 50 54 49 4f 4e 5f 44 49  COMPILEOPTION_DI
1ad0: 41 47 53 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  AGS.int sqlite3_
1ae0: 63 6f 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 75 73  compileoption_us
1af0: 65 64 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  ed(const char *z
1b00: 4f 70 74 4e 61 6d 65 29 3b 0a 63 6f 6e 73 74 20  OptName);.const 
1b10: 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
1b20: 6d 70 69 6c 65 6f 70 74 69 6f 6e 5f 67 65 74 28  mpileoption_get(
1b30: 69 6e 74 20 4e 29 3b 0a 23 65 6e 64 69 66 0a 0a  int N);.#endif..
1b40: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1b50: 54 65 73 74 20 54 6f 20 53 65 65 20 49 66 20 54  Test To See If T
1b60: 68 65 20 4c 69 62 72 61 72 79 20 49 73 20 54 68  he Library Is Th
1b70: 72 65 61 64 73 61 66 65 0a 2a 2a 0a 2a 2a 20 5e  readsafe.**.** ^
1b80: 54 68 65 20 73 71 6c 69 74 65 33 5f 74 68 72 65  The sqlite3_thre
1b90: 61 64 73 61 66 65 28 29 20 66 75 6e 63 74 69 6f  adsafe() functio
1ba0: 6e 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 20 69  n returns zero i
1bb0: 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a 2a  f and only if.**
1bc0: 20 53 51 4c 69 74 65 20 77 61 73 20 63 6f 6d 70   SQLite was comp
1bd0: 69 6c 65 64 20 77 69 74 68 20 6d 75 74 65 78 69  iled with mutexi
1be0: 6e 67 20 63 6f 64 65 20 6f 6d 69 74 74 65 64 20  ng code omitted 
1bf0: 64 75 65 20 74 6f 20 74 68 65 0a 2a 2a 20 5b 53  due to the.** [S
1c00: 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
1c10: 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
1c20: 70 74 69 6f 6e 20 62 65 69 6e 67 20 73 65 74 20  ption being set 
1c30: 74 6f 20 30 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  to 0..**.** SQLi
1c40: 74 65 20 63 61 6e 20 62 65 20 63 6f 6d 70 69 6c  te can be compil
1c50: 65 64 20 77 69 74 68 20 6f 72 20 77 69 74 68 6f  ed with or witho
1c60: 75 74 20 6d 75 74 65 78 65 73 2e 20 20 57 68 65  ut mutexes.  Whe
1c70: 6e 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  n.** the [SQLITE
1c80: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 43 20 70  _THREADSAFE] C p
1c90: 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
1ca0: 6f 20 69 73 20 31 20 6f 72 20 32 2c 20 6d 75 74  o is 1 or 2, mut
1cb0: 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61 62  exes.** are enab
1cc0: 6c 65 64 20 61 6e 64 20 53 51 4c 69 74 65 20 69  led and SQLite i
1cd0: 73 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 57  s threadsafe.  W
1ce0: 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  hen the.** [SQLI
1cf0: 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20 6d  TE_THREADSAFE] m
1d00: 61 63 72 6f 20 69 73 20 30 2c 20 0a 2a 2a 20 74  acro is 0, .** t
1d10: 68 65 20 6d 75 74 65 78 65 73 20 61 72 65 20 6f  he mutexes are o
1d20: 6d 69 74 74 65 64 2e 20 20 57 69 74 68 6f 75 74  mitted.  Without
1d30: 20 74 68 65 20 6d 75 74 65 78 65 73 2c 20 69 74   the mutexes, it
1d40: 20 69 73 20 6e 6f 74 20 73 61 66 65 0a 2a 2a 20   is not safe.** 
1d50: 74 6f 20 75 73 65 20 53 51 4c 69 74 65 20 63 6f  to use SQLite co
1d60: 6e 63 75 72 72 65 6e 74 6c 79 20 66 72 6f 6d 20  ncurrently from 
1d70: 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20 74 68  more than one th
1d80: 72 65 61 64 2e 0a 2a 2a 0a 2a 2a 20 45 6e 61 62  read..**.** Enab
1d90: 6c 69 6e 67 20 6d 75 74 65 78 65 73 20 69 6e 63  ling mutexes inc
1da0: 75 72 73 20 61 20 6d 65 61 73 75 72 61 62 6c 65  urs a measurable
1db0: 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 70 65 6e   performance pen
1dc0: 61 6c 74 79 2e 0a 2a 2a 20 53 6f 20 69 66 20 73  alty..** So if s
1dd0: 70 65 65 64 20 69 73 20 6f 66 20 75 74 6d 6f 73  peed is of utmos
1de0: 74 20 69 6d 70 6f 72 74 61 6e 63 65 2c 20 69 74  t importance, it
1df0: 20 6d 61 6b 65 73 20 73 65 6e 73 65 20 74 6f 20   makes sense to 
1e00: 64 69 73 61 62 6c 65 0a 2a 2a 20 74 68 65 20 6d  disable.** the m
1e10: 75 74 65 78 65 73 2e 20 20 42 75 74 20 66 6f 72  utexes.  But for
1e20: 20 6d 61 78 69 6d 75 6d 20 73 61 66 65 74 79 2c   maximum safety,
1e30: 20 6d 75 74 65 78 65 73 20 73 68 6f 75 6c 64 20   mutexes should 
1e40: 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 5e  be enabled..** ^
1e50: 54 68 65 20 64 65 66 61 75 6c 74 20 62 65 68 61  The default beha
1e60: 76 69 6f 72 20 69 73 20 66 6f 72 20 6d 75 74 65  vior is for mute
1e70: 78 65 73 20 74 6f 20 62 65 20 65 6e 61 62 6c 65  xes to be enable
1e80: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e  d..**.** This in
1e90: 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
1ea0: 73 65 64 20 62 79 20 61 6e 20 61 70 70 6c 69 63  sed by an applic
1eb0: 61 74 69 6f 6e 20 74 6f 20 6d 61 6b 65 20 73 75  ation to make su
1ec0: 72 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 76  re that the.** v
1ed0: 65 72 73 69 6f 6e 20 6f 66 20 53 51 4c 69 74 65  ersion of SQLite
1ee0: 20 74 68 61 74 20 69 74 20 69 73 20 6c 69 6e 6b   that it is link
1ef0: 69 6e 67 20 61 67 61 69 6e 73 74 20 77 61 73 20  ing against was 
1f00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
1f10: 20 74 68 65 20 64 65 73 69 72 65 64 20 73 65 74   the desired set
1f20: 74 69 6e 67 20 6f 66 20 74 68 65 20 5b 53 51 4c  ting of the [SQL
1f30: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 5d 20  ITE_THREADSAFE] 
1f40: 6d 61 63 72 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 69  macro..**.** Thi
1f50: 73 20 69 6e 74 65 72 66 61 63 65 20 6f 6e 6c 79  s interface only
1f60: 20 72 65 70 6f 72 74 73 20 6f 6e 20 74 68 65 20   reports on the 
1f70: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6d 75 74  compile-time mut
1f80: 65 78 20 73 65 74 74 69 6e 67 0a 2a 2a 20 6f 66  ex setting.** of
1f90: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
1fa0: 45 41 44 53 41 46 45 5d 20 66 6c 61 67 2e 20 20  EADSAFE] flag.  
1fb0: 49 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d  If SQLite is com
1fc0: 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 53 51  piled with.** SQ
1fd0: 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
1fe0: 31 20 6f 72 20 3d 32 20 74 68 65 6e 20 6d 75 74  1 or =2 then mut
1ff0: 65 78 65 73 20 61 72 65 20 65 6e 61 62 6c 65 64  exes are enabled
2000: 20 62 79 20 64 65 66 61 75 6c 74 20 62 75 74 0a   by default but.
2010: 2a 2a 20 63 61 6e 20 62 65 20 66 75 6c 6c 79 20  ** can be fully 
2020: 6f 72 20 70 61 72 74 69 61 6c 6c 79 20 64 69 73  or partially dis
2030: 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 61  abled using a ca
2040: 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63  ll to [sqlite3_c
2050: 6f 6e 66 69 67 28 29 5d 0a 2a 2a 20 77 69 74 68  onfig()].** with
2060: 20 74 68 65 20 76 65 72 62 73 20 5b 53 51 4c 49   the verbs [SQLI
2070: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
2080: 54 48 52 45 41 44 5d 2c 20 5b 53 51 4c 49 54 45  THREAD], [SQLITE
2090: 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
20a0: 45 41 44 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c  EAD],.** or [SQL
20b0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58  ITE_CONFIG_MUTEX
20c0: 5d 2e 20 20 5e 28 54 68 65 20 72 65 74 75 72 6e  ].  ^(The return
20d0: 20 76 61 6c 75 65 20 6f 66 20 74 68 65 0a 2a 2a   value of the.**
20e0: 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73   sqlite3_threads
20f0: 61 66 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 73  afe() function s
2100: 68 6f 77 73 20 6f 6e 6c 79 20 74 68 65 20 63 6f  hows only the co
2110: 6d 70 69 6c 65 2d 74 69 6d 65 20 73 65 74 74 69  mpile-time setti
2120: 6e 67 20 6f 66 0a 2a 2a 20 74 68 72 65 61 64 20  ng of.** thread 
2130: 73 61 66 65 74 79 2c 20 6e 6f 74 20 61 6e 79 20  safety, not any 
2140: 72 75 6e 2d 74 69 6d 65 20 63 68 61 6e 67 65 73  run-time changes
2150: 20 74 6f 20 74 68 61 74 20 73 65 74 74 69 6e 67   to that setting
2160: 20 6d 61 64 65 20 62 79 0a 2a 2a 20 73 71 6c 69   made by.** sqli
2170: 74 65 33 5f 63 6f 6e 66 69 67 28 29 2e 20 49 6e  te3_config(). In
2180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
2190: 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
21a0: 72 6f 6d 20 73 71 6c 69 74 65 33 5f 74 68 72 65  rom sqlite3_thre
21b0: 61 64 73 61 66 65 28 29 0a 2a 2a 20 69 73 20 75  adsafe().** is u
21c0: 6e 63 68 61 6e 67 65 64 20 62 79 20 63 61 6c 6c  nchanged by call
21d0: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6e  s to sqlite3_con
21e0: 66 69 67 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53  fig().)^.**.** S
21f0: 65 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e  ee the [threadin
2200: 67 20 6d 6f 64 65 5d 20 64 6f 63 75 6d 65 6e 74  g mode] document
2210: 61 74 69 6f 6e 20 66 6f 72 20 61 64 64 69 74 69  ation for additi
2220: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
2230: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2240: 5f 74 68 72 65 61 64 73 61 66 65 28 76 6f 69 64  _threadsafe(void
2250: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2260: 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2270: 6e 65 63 74 69 6f 6e 20 48 61 6e 64 6c 65 0a 2a  nection Handle.*
2280: 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 64 61 74  * KEYWORDS: {dat
2290: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
22a0: 7d 20 7b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  } {database conn
22b0: 65 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45  ections}.**.** E
22c0: 61 63 68 20 6f 70 65 6e 20 53 51 4c 69 74 65 20  ach open SQLite 
22d0: 64 61 74 61 62 61 73 65 20 69 73 20 72 65 70 72  database is repr
22e0: 65 73 65 6e 74 65 64 20 62 79 20 61 20 70 6f 69  esented by a poi
22f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
2300: 6e 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6f 70  nce of.** the op
2310: 61 71 75 65 20 73 74 72 75 63 74 75 72 65 20 6e  aque structure n
2320: 61 6d 65 64 20 22 73 71 6c 69 74 65 33 22 2e 20  amed "sqlite3". 
2330: 20 49 74 20 69 73 20 75 73 65 66 75 6c 20 74 6f   It is useful to
2340: 20 74 68 69 6e 6b 20 6f 66 20 61 6e 20 73 71 6c   think of an sql
2350: 69 74 65 33 0a 2a 2a 20 70 6f 69 6e 74 65 72 20  ite3.** pointer 
2360: 61 73 20 61 6e 20 6f 62 6a 65 63 74 2e 20 20 54  as an object.  T
2370: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
2380: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
2390: 65 6e 31 36 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20  en16()], and.** 
23a0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
23b0: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 61  ()] interfaces a
23c0: 72 65 20 69 74 73 20 63 6f 6e 73 74 72 75 63 74  re its construct
23d0: 6f 72 73 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65  ors, and [sqlite
23e0: 33 5f 63 6c 6f 73 65 28 29 5d 0a 2a 2a 20 61 6e  3_close()].** an
23f0: 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  d [sqlite3_close
2400: 5f 76 32 28 29 5d 20 61 72 65 20 69 74 73 20 64  _v2()] are its d
2410: 65 73 74 72 75 63 74 6f 72 73 2e 20 20 54 68 65  estructors.  The
2420: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2430: 72 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  r.** interfaces 
2440: 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c  (such as.** [sql
2450: 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
2460: 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65  )], [sqlite3_cre
2470: 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c  ate_function()],
2480: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
2490: 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d  _busy_timeout()]
24a0: 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74 68 72   to name but thr
24b0: 65 65 29 20 74 68 61 74 20 61 72 65 20 6d 65 74  ee) that are met
24c0: 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71  hods on an.** sq
24d0: 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f  lite3 object..*/
24e0: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
24f0: 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65 33 3b  sqlite3 sqlite3;
2500: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2510: 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67 65 72  : 64-Bit Integer
2520: 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Types.** KEYWOR
2530: 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  DS: sqlite_int64
2540: 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a   sqlite_uint64.*
2550: 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68 65  *.** Because the
2560: 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70  re is no cross-p
2570: 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f 20 73  latform way to s
2580: 70 65 63 69 66 79 20 36 34 2d 62 69 74 20 69 6e  pecify 64-bit in
2590: 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a 20 53  teger types.** S
25a0: 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73 20 74  QLite includes t
25b0: 79 70 65 64 65 66 73 20 66 6f 72 20 36 34 2d 62  ypedefs for 64-b
25c0: 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20 75 6e  it signed and un
25d0: 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 73 2e  signed integers.
25e0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74  .**.** The sqlit
25f0: 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c  e3_int64 and sql
2600: 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72 65 20  ite3_uint64 are 
2610: 74 68 65 20 70 72 65 66 65 72 72 65 64 20 74 79  the preferred ty
2620: 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a  pe definitions..
2630: 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f 69 6e  ** The sqlite_in
2640: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2650: 69 6e 74 36 34 20 74 79 70 65 73 20 61 72 65 20  int64 types are 
2660: 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20 62 61  supported for ba
2670: 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61  ckwards.** compa
2680: 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a  tibility only..*
2690: 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
26a0: 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69  3_int64 and sqli
26b0: 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73 20 63  te_int64 types c
26c0: 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72  an store integer
26d0: 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65   values.** betwe
26e0: 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36 38 35  en -922337203685
26f0: 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39 32 32  4775808 and +922
2700: 33 33 37 32 30 33 36 38 35 34 37 37 35 38 30 37  3372036854775807
2710: 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e 54 68   inclusive.  ^Th
2720: 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e  e.** sqlite3_uin
2730: 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f 75  t64 and sqlite_u
2740: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
2750: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
2760: 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e  lues .** between
2770: 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37 34 34   0 and +18446744
2780: 30 37 33 37 30 39 35 35 31 36 31 35 20 69 6e 63  073709551615 inc
2790: 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65  lusive..*/.#ifde
27a0: 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54  f SQLITE_INT64_T
27b0: 59 50 45 0a 20 20 74 79 70 65 64 65 66 20 53 51  YPE.  typedef SQ
27c0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27d0: 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20  sqlite_int64;.  
27e0: 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e 65 64  typedef unsigned
27f0: 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59   SQLITE_INT64_TY
2800: 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  PE sqlite_uint64
2810: 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65 64 28  ;.#elif defined(
2820: 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64 65 66  _MSC_VER) || def
2830: 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f  ined(__BORLANDC_
2840: 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f 5f 69  _).  typedef __i
2850: 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e 74 36  nt64 sqlite_int6
2860: 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75 6e 73  4;.  typedef uns
2870: 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20 73 71  igned __int64 sq
2880: 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c  lite_uint64;.#el
2890: 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c 6f 6e  se.  typedef lon
28a0: 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74  g long int sqlit
28b0: 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70 65 64  e_int64;.  typed
28c0: 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67  ef unsigned long
28d0: 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65   long int sqlite
28e0: 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a  _uint64;.#endif.
28f0: 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f 69  typedef sqlite_i
2900: 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69 6e 74  nt64 sqlite3_int
2910: 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71 6c 69  64;.typedef sqli
2920: 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69 74 65  te_uint64 sqlite
2930: 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a  3_uint64;../*.**
2940: 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f   If compiling fo
2950: 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20 74 68  r a processor th
2960: 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e  at lacks floatin
2970: 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c  g point support,
2980: 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65 20 69  .** substitute i
2990: 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f 61 74  nteger for float
29a0: 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69  ing-point..*/.#i
29b0: 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54  fdef SQLITE_OMIT
29c0: 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a  _FLOATING_POINT.
29d0: 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c 65 20  # define double 
29e0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a 23 65  sqlite3_int64.#e
29f0: 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
2a00: 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20  3REF: Closing A 
2a10: 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2a20: 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
2a30: 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 61  qlite3_close() a
2a40: 6e 64 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nd sqlite3_close
2a50: 5f 76 32 28 29 20 72 6f 75 74 69 6e 65 73 20 61  _v2() routines a
2a60: 72 65 20 64 65 73 74 72 75 63 74 6f 72 73 0a 2a  re destructors.*
2a70: 2a 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  * for the [sqlit
2a80: 65 33 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e  e3] object..** ^
2a90: 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  Calls to sqlite3
2aa0: 5f 63 6c 6f 73 65 28 29 20 61 6e 64 20 73 71 6c  _close() and sql
2ab0: 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32 28 29 20  ite3_close_v2() 
2ac0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
2ad0: 4b 5d 20 69 66 0a 2a 2a 20 74 68 65 20 5b 73 71  K] if.** the [sq
2ae0: 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20 69 73  lite3] object is
2af0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2b00: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2b10: 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 72 65  associated.** re
2b20: 73 6f 75 72 63 65 73 20 61 72 65 20 64 65 61 6c  sources are deal
2b30: 6c 6f 63 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  located..**.** ^
2b40: 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20  If the database 
2b50: 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 61 73  connection is as
2b60: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 75 6e  sociated with un
2b70: 66 69 6e 61 6c 69 7a 65 64 20 70 72 65 70 61 72  finalized prepar
2b80: 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  ed.** statements
2b90: 20 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73   or unfinished s
2ba0: 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20 6f 62  qlite3_backup ob
2bb0: 6a 65 63 74 73 20 74 68 65 6e 20 73 71 6c 69 74  jects then sqlit
2bc0: 65 33 5f 63 6c 6f 73 65 28 29 0a 2a 2a 20 77 69  e3_close().** wi
2bd0: 6c 6c 20 6c 65 61 76 65 20 74 68 65 20 64 61 74  ll leave the dat
2be0: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2bf0: 20 6f 70 65 6e 20 61 6e 64 20 72 65 74 75 72 6e   open and return
2c00: 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 0a   [SQLITE_BUSY]..
2c10: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
2c20: 6c 6f 73 65 5f 76 32 28 29 20 69 73 20 63 61 6c  lose_v2() is cal
2c30: 6c 65 64 20 77 69 74 68 20 75 6e 66 69 6e 61 6c  led with unfinal
2c40: 69 7a 65 64 20 70 72 65 70 61 72 65 64 20 73 74  ized prepared st
2c50: 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 61 6e 64 2f  atements.** and/
2c60: 6f 72 20 75 6e 66 69 6e 69 73 68 65 64 20 73 71  or unfinished sq
2c70: 6c 69 74 65 33 5f 62 61 63 6b 75 70 73 2c 20 74  lite3_backups, t
2c80: 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
2c90: 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 65 63 6f   connection beco
2ca0: 6d 65 73 0a 2a 2a 20 61 6e 20 75 6e 75 73 61 62  mes.** an unusab
2cb0: 6c 65 20 22 7a 6f 6d 62 69 65 22 20 77 68 69 63  le "zombie" whic
2cc0: 68 20 77 69 6c 6c 20 61 75 74 6f 6d 61 74 69 63  h will automatic
2cd0: 61 6c 6c 79 20 62 65 20 64 65 61 6c 6c 6f 63 61  ally be dealloca
2ce0: 74 65 64 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20  ted when the.** 
2cf0: 6c 61 73 74 20 70 72 65 70 61 72 65 64 20 73 74  last prepared st
2d00: 61 74 65 6d 65 6e 74 20 69 73 20 66 69 6e 61 6c  atement is final
2d10: 69 7a 65 64 20 6f 72 20 74 68 65 20 6c 61 73 74  ized or the last
2d20: 20 73 71 6c 69 74 65 33 5f 62 61 63 6b 75 70 20   sqlite3_backup 
2d30: 69 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 2e 20  is.** finished. 
2d40: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6c 6f   The sqlite3_clo
2d50: 73 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  se_v2() interfac
2d60: 65 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  e is intended fo
2d70: 72 20 75 73 65 20 77 69 74 68 0a 2a 2a 20 68 6f  r use with.** ho
2d80: 73 74 20 6c 61 6e 67 75 61 67 65 73 20 74 68 61  st languages tha
2d90: 74 20 61 72 65 20 67 61 72 62 61 67 65 20 63 6f  t are garbage co
2da0: 6c 6c 65 63 74 65 64 2c 20 61 6e 64 20 77 68 65  llected, and whe
2db0: 72 65 20 74 68 65 20 6f 72 64 65 72 20 69 6e 20  re the order in 
2dc0: 77 68 69 63 68 0a 2a 2a 20 64 65 73 74 72 75 63  which.** destruc
2dd0: 74 6f 72 73 20 61 72 65 20 63 61 6c 6c 65 64 20  tors are called 
2de0: 69 73 20 61 72 62 69 74 72 61 72 79 2e 0a 2a 2a  is arbitrary..**
2df0: 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  .** Applications
2e00: 20 73 68 6f 75 6c 64 20 5b 73 71 6c 69 74 65 33   should [sqlite3
2e10: 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
2e20: 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70 61  lize] all [prepa
2e30: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 6c 6f  .** [sqlite3_blo
2e50: 62 5f 63 6c 6f 73 65 20 7c 20 63 6c 6f 73 65 5d  b_close | close]
2e60: 20 61 6c 6c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c   all [BLOB handl
2e70: 65 73 5d 2c 20 61 6e 64 20 0a 2a 2a 20 5b 73 71  es], and .** [sq
2e80: 6c 69 74 65 33 5f 62 61 63 6b 75 70 5f 66 69 6e  lite3_backup_fin
2e90: 69 73 68 20 7c 20 66 69 6e 69 73 68 5d 20 61 6c  ish | finish] al
2ea0: 6c 20 5b 73 71 6c 69 74 65 33 5f 62 61 63 6b 75  l [sqlite3_backu
2eb0: 70 5d 20 6f 62 6a 65 63 74 73 20 61 73 73 6f 63  p] objects assoc
2ec0: 69 61 74 65 64 0a 2a 2a 20 77 69 74 68 20 74 68  iated.** with th
2ed0: 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65  e [sqlite3] obje
2ee0: 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74 74 65  ct prior to atte
2ef0: 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20  mpting to close 
2f00: 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66  the object.  ^If
2f10: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  .** sqlite3_clos
2f20: 65 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65 64  e_v2() is called
2f30: 20 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20   on a [database 
2f40: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74  connection] that
2f50: 20 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75   still has.** ou
2f60: 74 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61  tstanding [prepa
2f70: 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 2c  red statements],
2f80: 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 2c   [BLOB handles],
2f90: 20 61 6e 64 2f 6f 72 0a 2a 2a 20 5b 73 71 6c 69   and/or.** [sqli
2fa0: 74 65 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65  te3_backup] obje
2fb0: 63 74 73 20 74 68 65 6e 20 69 74 20 72 65 74 75  cts then it retu
2fc0: 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
2fd0: 61 6e 64 20 74 68 65 20 64 65 61 6c 6c 6f 63 61  and the dealloca
2fe0: 74 69 6f 6e 0a 2a 2a 20 6f 66 20 72 65 73 6f 75  tion.** of resou
2ff0: 72 63 65 73 20 69 73 20 64 65 66 65 72 72 65 64  rces is deferred
3000: 20 75 6e 74 69 6c 20 61 6c 6c 20 5b 70 72 65 70   until all [prep
3010: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
3020: 2c 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  , [BLOB handles]
3030: 2c 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ,.** and [sqlite
3040: 33 5f 62 61 63 6b 75 70 5d 20 6f 62 6a 65 63 74  3_backup] object
3050: 73 20 61 72 65 20 61 6c 73 6f 20 64 65 73 74 72  s are also destr
3060: 6f 79 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  oyed..**.** ^If 
3070: 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  an [sqlite3] obj
3080: 65 63 74 20 69 73 20 64 65 73 74 72 6f 79 65 64  ect is destroyed
3090: 20 77 68 69 6c 65 20 61 20 74 72 61 6e 73 61 63   while a transac
30a0: 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c 0a 2a 2a  tion is open,.**
30b0: 20 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e   the transaction
30c0: 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c   is automaticall
30d0: 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
30e0: 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61 72 61 6d  *.** The C param
30f0: 65 74 65 72 20 74 6f 20 5b 73 71 6c 69 74 65 33  eter to [sqlite3
3100: 5f 63 6c 6f 73 65 28 43 29 5d 20 61 6e 64 20 5b  _close(C)] and [
3110: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3120: 28 43 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20  (C)].** must be 
3130: 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 0a 2a 2a  either a NULL.**
3140: 20 70 6f 69 6e 74 65 72 20 6f 72 20 61 6e 20 5b   pointer or an [
3150: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
3160: 70 6f 69 6e 74 65 72 20 6f 62 74 61 69 6e 65 64  pointer obtained
3170: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3180: 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
3190: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 20 6f  te3_open16()], o
31a0: 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70  r.** [sqlite3_op
31b0: 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 6e 6f  en_v2()], and no
31c0: 74 20 70 72 65 76 69 6f 75 73 6c 79 20 63 6c 6f  t previously clo
31d0: 73 65 64 2e 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67  sed..** ^Calling
31e0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
31f0: 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73   or sqlite3_clos
3200: 65 5f 76 32 28 29 20 77 69 74 68 20 61 20 4e 55  e_v2() with a NU
3210: 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 61 72  LL pointer.** ar
3220: 67 75 6d 65 6e 74 20 69 73 20 61 20 68 61 72 6d  gument is a harm
3230: 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a 69  less no-op..*/.i
3240: 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65  nt sqlite3_close
3250: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 69 6e 74 20  (sqlite3*);.int 
3260: 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 5f 76 32  sqlite3_close_v2
3270: 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
3280: 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f 72 20  ** The type for 
3290: 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  a callback funct
32a0: 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20  ion..** This is 
32b0: 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70 72 65  legacy and depre
32c0: 63 61 74 65 64 2e 20 20 49 74 20 69 73 20 69 6e  cated.  It is in
32d0: 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73 74 6f  cluded for histo
32e0: 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61 74 69  rical.** compati
32f0: 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20 6e 6f  bility and is no
3300: 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a 2a 2f  t documented..*/
3310: 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28 2a 73  .typedef int (*s
3320: 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63 6b 29  qlite3_callback)
3330: 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a  (void*,int,char*
3340: 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f 2a 0a  *, char**);../*.
3350: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 6e 65  ** CAPI3REF: One
3360: 2d 53 74 65 70 20 51 75 65 72 79 20 45 78 65 63  -Step Query Exec
3370: 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63 65 0a  ution Interface.
3380: 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
3390: 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72 66 61  3_exec() interfa
33a0: 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e 69 65  ce is a convenie
33b0: 6e 63 65 20 77 72 61 70 70 65 72 20 61 72 6f 75  nce wrapper arou
33c0: 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  nd.** [sqlite3_p
33d0: 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20 5b 73  repare_v2()], [s
33e0: 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20  qlite3_step()], 
33f0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  and [sqlite3_fin
3400: 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74 68 61  alize()],.** tha
3410: 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70 70 6c  t allows an appl
3420: 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e 20 6d  ication to run m
3430: 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d 65 6e  ultiple statemen
3440: 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77 69 74  ts of SQL.** wit
3450: 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f 20 75  hout having to u
3460: 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20 63 6f  se a lot of C co
3470: 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de. .**.** ^The 
3480: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69  sqlite3_exec() i
3490: 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20 7a 65  nterface runs ze
34a0: 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46 2d 38  ro or more UTF-8
34b0: 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73 65 6d   encoded,.** sem
34c0: 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65 20  icolon-separate 
34d0: 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 70  SQL statements p
34e0: 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73 20 32  assed into its 2
34f0: 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a 2a 20  nd argument,.** 
3500: 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74 20 6f  in the context o
3510: 66 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  f the [database 
3520: 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61 73 73  connection] pass
3530: 65 64 20 69 6e 20 61 73 20 69 74 73 20 31 73 74  ed in as its 1st
3540: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e  .** argument.  ^
3550: 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  If the callback 
3560: 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68 65 20  function of the 
3570: 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  3rd argument to.
3580: 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  ** sqlite3_exec(
3590: 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74  ) is not NULL, t
35a0: 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  hen it is invoke
35b0: 64 20 66 6f 72 20 65 61 63 68 20 72 65 73 75 6c  d for each resul
35c0: 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e 67 20  t row.** coming 
35d0: 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61 6c 75  out of the evalu
35e0: 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65  ated SQL stateme
35f0: 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68 20 61  nts.  ^The 4th a
3600: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 73 71  rgument to.** sq
3610: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3620: 72 65 6c 61 79 65 64 20 74 68 72 6f 75 67 68 20  relayed through 
3630: 74 6f 20 74 68 65 20 31 73 74 20 61 72 67 75 6d  to the 1st argum
3640: 65 6e 74 20 6f 66 20 65 61 63 68 0a 2a 2a 20 63  ent of each.** c
3650: 61 6c 6c 62 61 63 6b 20 69 6e 76 6f 63 61 74 69  allback invocati
3660: 6f 6e 2e 20 20 5e 49 66 20 74 68 65 20 63 61 6c  on.  ^If the cal
3670: 6c 62 61 63 6b 20 70 6f 69 6e 74 65 72 20 74 6f  lback pointer to
3680: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3690: 2a 2a 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ** is NULL, then
36a0: 20 6e 6f 20 63 61 6c 6c 62 61 63 6b 20 69 73 20   no callback is 
36b0: 65 76 65 72 20 69 6e 76 6f 6b 65 64 20 61 6e 64  ever invoked and
36c0: 20 72 65 73 75 6c 74 20 72 6f 77 73 20 61 72 65   result rows are
36d0: 0a 2a 2a 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  .** ignored..**.
36e0: 2a 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20  ** ^If an error 
36f0: 6f 63 63 75 72 73 20 77 68 69 6c 65 20 65 76 61  occurs while eva
3700: 6c 75 61 74 69 6e 67 20 74 68 65 20 53 51 4c 20  luating the SQL 
3710: 73 74 61 74 65 6d 65 6e 74 73 20 70 61 73 73 65  statements passe
3720: 64 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  d into.** sqlite
3730: 33 5f 65 78 65 63 28 29 2c 20 74 68 65 6e 20 65  3_exec(), then e
3740: 78 65 63 75 74 69 6f 6e 20 6f 66 20 74 68 65 20  xecution of the 
3750: 63 75 72 72 65 6e 74 20 73 74 61 74 65 6d 65 6e  current statemen
3760: 74 20 73 74 6f 70 73 20 61 6e 64 0a 2a 2a 20 73  t stops and.** s
3770: 75 62 73 65 71 75 65 6e 74 20 73 74 61 74 65 6d  ubsequent statem
3780: 65 6e 74 73 20 61 72 65 20 73 6b 69 70 70 65 64  ents are skipped
3790: 2e 20 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  .  ^If the 5th p
37a0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
37b0: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 69 73  te3_exec().** is
37c0: 20 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 61   not NULL then a
37d0: 6e 79 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  ny error message
37e0: 20 69 73 20 77 72 69 74 74 65 6e 20 69 6e 74 6f   is written into
37f0: 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
3800: 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  .** from [sqlite
3810: 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e 64 20  3_malloc()] and 
3820: 70 61 73 73 65 64 20 62 61 63 6b 20 74 68 72 6f  passed back thro
3830: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3840: 6d 65 74 65 72 2e 0a 2a 2a 20 54 6f 20 61 76 6f  meter..** To avo
3850: 69 64 20 6d 65 6d 6f 72 79 20 6c 65 61 6b 73 2c  id memory leaks,
3860: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
3870: 20 73 68 6f 75 6c 64 20 69 6e 76 6f 6b 65 20 5b   should invoke [
3880: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 0a  sqlite3_free()].
3890: 2a 2a 20 6f 6e 20 65 72 72 6f 72 20 6d 65 73 73  ** on error mess
38a0: 61 67 65 20 73 74 72 69 6e 67 73 20 72 65 74 75  age strings retu
38b0: 72 6e 65 64 20 74 68 72 6f 75 67 68 20 74 68 65  rned through the
38c0: 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 6f   5th parameter o
38d0: 66 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f  f.** of sqlite3_
38e0: 65 78 65 63 28 29 20 61 66 74 65 72 20 74 68 65  exec() after the
38f0: 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
3900: 74 72 69 6e 67 20 69 73 20 6e 6f 20 6c 6f 6e 67  tring is no long
3910: 65 72 20 6e 65 65 64 65 64 2e 0a 2a 2a 20 5e 49  er needed..** ^I
3920: 66 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  f the 5th parame
3930: 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65  ter to sqlite3_e
3940: 78 65 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  xec() is not NUL
3950: 4c 20 61 6e 64 20 6e 6f 20 65 72 72 6f 72 73 0a  L and no errors.
3960: 2a 2a 20 6f 63 63 75 72 2c 20 74 68 65 6e 20 73  ** occur, then s
3970: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 73 65  qlite3_exec() se
3980: 74 73 20 74 68 65 20 70 6f 69 6e 74 65 72 20 69  ts the pointer i
3990: 6e 20 69 74 73 20 35 74 68 20 70 61 72 61 6d 65  n its 5th parame
39a0: 74 65 72 20 74 6f 0a 2a 2a 20 4e 55 4c 4c 20 62  ter to.** NULL b
39b0: 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
39c0: 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 73 71  .**.** ^If an sq
39d0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
39e0: 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f  lback returns no
39f0: 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 73 71 6c 69  n-zero, the sqli
3a00: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 72 6f  te3_exec().** ro
3a10: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 53 51  utine returns SQ
3a20: 4c 49 54 45 5f 41 42 4f 52 54 20 77 69 74 68 6f  LITE_ABORT witho
3a30: 75 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  ut invoking the 
3a40: 63 61 6c 6c 62 61 63 6b 20 61 67 61 69 6e 20 61  callback again a
3a50: 6e 64 0a 2a 2a 20 77 69 74 68 6f 75 74 20 72 75  nd.** without ru
3a60: 6e 6e 69 6e 67 20 61 6e 79 20 73 75 62 73 65 71  nning any subseq
3a70: 75 65 6e 74 20 53 51 4c 20 73 74 61 74 65 6d 65  uent SQL stateme
3a80: 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  nts..**.** ^The 
3a90: 32 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  2nd argument to 
3aa0: 74 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63  the sqlite3_exec
3ab0: 28 29 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63  () callback func
3ac0: 74 69 6f 6e 20 69 73 20 74 68 65 0a 2a 2a 20 6e  tion is the.** n
3ad0: 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
3ae0: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 2e 20   in the result. 
3af0: 20 5e 54 68 65 20 33 72 64 20 61 72 67 75 6d 65   ^The 3rd argume
3b00: 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
3b10: 33 5f 65 78 65 63 28 29 0a 2a 2a 20 63 61 6c 6c  3_exec().** call
3b20: 62 61 63 6b 20 69 73 20 61 6e 20 61 72 72 61 79  back is an array
3b30: 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20   of pointers to 
3b40: 73 74 72 69 6e 67 73 20 6f 62 74 61 69 6e 65 64  strings obtained
3b50: 20 61 73 20 69 66 20 66 72 6f 6d 0a 2a 2a 20 5b   as if from.** [
3b60: 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
3b70: 65 78 74 28 29 5d 2c 20 6f 6e 65 20 66 6f 72 20  ext()], one for 
3b80: 65 61 63 68 20 63 6f 6c 75 6d 6e 2e 20 20 5e 49  each column.  ^I
3b90: 66 20 61 6e 20 65 6c 65 6d 65 6e 74 20 6f 66 20  f an element of 
3ba0: 61 0a 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20  a.** result row 
3bb0: 69 73 20 4e 55 4c 4c 20 74 68 65 6e 20 74 68 65  is NULL then the
3bc0: 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 73   corresponding s
3bd0: 74 72 69 6e 67 20 70 6f 69 6e 74 65 72 20 66 6f  tring pointer fo
3be0: 72 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33  r the.** sqlite3
3bf0: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3c00: 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
3c10: 65 72 2e 20 20 5e 54 68 65 20 34 74 68 20 61 72  er.  ^The 4th ar
3c20: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a  gument to the.**
3c30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3c40: 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 61  callback is an a
3c50: 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
3c60: 20 74 6f 20 73 74 72 69 6e 67 73 20 77 68 65 72   to strings wher
3c70: 65 20 65 61 63 68 0a 2a 2a 20 65 6e 74 72 79 20  e each.** entry 
3c80: 72 65 70 72 65 73 65 6e 74 73 20 74 68 65 20 6e  represents the n
3c90: 61 6d 65 20 6f 66 20 63 6f 72 72 65 73 70 6f 6e  ame of correspon
3ca0: 64 69 6e 67 20 72 65 73 75 6c 74 20 63 6f 6c 75  ding result colu
3cb0: 6d 6e 20 61 73 20 6f 62 74 61 69 6e 65 64 0a 2a  mn as obtained.*
3cc0: 2a 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  * from [sqlite3_
3cd0: 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 29 5d 2e 0a  column_name()]..
3ce0: 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 32 6e  **.** ^If the 2n
3cf0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
3d00: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3d10: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c   a NULL pointer,
3d20: 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
3d30: 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
3d40: 2c 20 6f 72 20 61 20 70 6f 69 6e 74 65 72 20 74  , or a pointer t
3d50: 68 61 74 20 63 6f 6e 74 61 69 6e 73 20 6f 6e 6c  hat contains onl
3d60: 79 20 77 68 69 74 65 73 70 61 63 65 20 61 6e 64  y whitespace and
3d70: 2f 6f 72 20 0a 2a 2a 20 53 51 4c 20 63 6f 6d 6d  /or .** SQL comm
3d80: 65 6e 74 73 2c 20 74 68 65 6e 20 6e 6f 20 53 51  ents, then no SQ
3d90: 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65  L statements are
3da0: 20 65 76 61 6c 75 61 74 65 64 20 61 6e 64 20 74   evaluated and t
3db0: 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 69  he database.** i
3dc0: 73 20 6e 6f 74 20 63 68 61 6e 67 65 64 2e 0a 2a  s not changed..*
3dd0: 2a 0a 2a 2a 20 52 65 73 74 72 69 63 74 69 6f 6e  *.** Restriction
3de0: 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
3df0: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e00: 61 74 69 6f 6e 20 6d 75 73 74 20 69 6e 73 75 72  ation must insur
3e10: 65 20 74 68 61 74 20 74 68 65 20 31 73 74 20 70  e that the 1st p
3e20: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3e30: 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a 20 20 20  te3_exec().**   
3e40: 20 20 20 69 73 20 61 20 76 61 6c 69 64 20 61 6e     is a valid an
3e50: 64 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65  d open [database
3e60: 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a   connection]..**
3e70: 20 3c 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63   <li> The applic
3e80: 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 63  ation must not c
3e90: 6c 6f 73 65 20 74 68 65 20 5b 64 61 74 61 62 61  lose the [databa
3ea0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
3eb0: 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20 20  pecified by.**  
3ec0: 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72 61      the 1st para
3ed0: 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
3ee0: 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73 71  _exec() while sq
3ef0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
3f00: 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69 3e  running..** <li>
3f10: 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   The application
3f20: 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66 79   must not modify
3f30: 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
3f40: 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20 69  nt text passed i
3f50: 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65 20  nto.**      the 
3f60: 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
3f70: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3f80: 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65 78  while sqlite3_ex
3f90: 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e  ec() is running.
3fa0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e 74  .** </ul>.*/.int
3fb0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a 20   sqlite3_exec(. 
3fc0: 20 73 71 6c 69 74 65 33 2a 2c 20 20 20 20 20 20   sqlite3*,      
3fd0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3fe0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41              /* A
3ff0: 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
4000: 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
4010: 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20 20  *sql,           
4020: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4030: 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61  /* SQL to be eva
4040: 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74 20  luated */.  int 
4050: 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69 64  (*callback)(void
4060: 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68 61  *,int,char**,cha
4070: 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62 61  r**),  /* Callba
4080: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20  ck function */. 
4090: 20 76 6f 69 64 20 2a 2c 20 20 20 20 20 20 20 20   void *,        
40a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
40b0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 31              /* 1
40c0: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 63  st argument to c
40d0: 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68 61  allback */.  cha
40e0: 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20 20  r **errmsg      
40f0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
4100: 20 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72          /* Error
4110: 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
4120: 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  e */.);../*.** C
4130: 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
4140: 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  Codes.** KEYWORD
4150: 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f 64 65 20  S: {result code 
4160: 64 65 66 69 6e 69 74 69 6f 6e 73 7d 0a 2a 2a 0a  definitions}.**.
4170: 2a 2a 20 4d 61 6e 79 20 53 51 4c 69 74 65 20 66  ** Many SQLite f
4180: 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20  unctions return 
4190: 61 6e 20 69 6e 74 65 67 65 72 20 72 65 73 75 6c  an integer resul
41a0: 74 20 63 6f 64 65 20 66 72 6f 6d 20 74 68 65 20  t code from the 
41b0: 73 65 74 20 73 68 6f 77 6e 0a 2a 2a 20 68 65 72  set shown.** her
41c0: 65 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 69 6e  e in order to in
41d0: 64 69 63 61 74 65 20 73 75 63 63 65 73 73 20 6f  dicate success o
41e0: 72 20 66 61 69 6c 75 72 65 2e 0a 2a 2a 0a 2a 2a  r failure..**.**
41f0: 20 4e 65 77 20 65 72 72 6f 72 20 63 6f 64 65 73   New error codes
4200: 20 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e   may be added in
4210: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
4220: 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a   of SQLite..**.*
4230: 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 65 78 74  * See also: [ext
4240: 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
4250: 65 20 64 65 66 69 6e 69 74 69 6f 6e 73 5d 0a 2a  e definitions].*
4260: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4270: 5f 4f 4b 20 20 20 20 20 20 20 20 20 20 20 30 20  _OK           0 
4280: 20 20 2f 2a 20 53 75 63 63 65 73 73 66 75 6c 20    /* Successful 
4290: 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20 62 65 67  result */./* beg
42a0: 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72 6f 72 2d  inning-of-error-
42b0: 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66 69 6e 65  codes */.#define
42c0: 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 20 20 20   SQLITE_ERROR   
42d0: 20 20 20 20 20 31 20 20 20 2f 2a 20 53 51 4c 20       1   /* SQL 
42e0: 65 72 72 6f 72 20 6f 72 20 6d 69 73 73 69 6e 67  error or missing
42f0: 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65   database */.#de
4300: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
4310: 52 4e 41 4c 20 20 20 20 20 32 20 20 20 2f 2a 20  RNAL     2   /* 
4320: 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69 63 20 65  Internal logic e
4330: 72 72 6f 72 20 69 6e 20 53 51 4c 69 74 65 20 2a  rror in SQLite *
4340: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4350: 5f 50 45 52 4d 20 20 20 20 20 20 20 20 20 33 20  _PERM         3 
4360: 20 20 2f 2a 20 41 63 63 65 73 73 20 70 65 72 6d    /* Access perm
4370: 69 73 73 69 6f 6e 20 64 65 6e 69 65 64 20 2a 2f  ission denied */
4380: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4390: 41 42 4f 52 54 20 20 20 20 20 20 20 20 34 20 20  ABORT        4  
43a0: 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20 72 6f 75   /* Callback rou
43b0: 74 69 6e 65 20 72 65 71 75 65 73 74 65 64 20 61  tine requested a
43c0: 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64 65 66 69  n abort */.#defi
43d0: 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59 20 20  ne SQLITE_BUSY  
43e0: 20 20 20 20 20 20 20 35 20 20 20 2f 2a 20 54 68         5   /* Th
43f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
4400: 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a 23 64 65  is locked */.#de
4410: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
4420: 45 44 20 20 20 20 20 20 20 36 20 20 20 2f 2a 20  ED       6   /* 
4430: 41 20 74 61 62 6c 65 20 69 6e 20 74 68 65 20 64  A table in the d
4440: 61 74 61 62 61 73 65 20 69 73 20 6c 6f 63 6b 65  atabase is locke
4450: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4460: 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20  ITE_NOMEM       
4470: 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c 6c 6f 63   7   /* A malloc
4480: 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a 23 64 65  () failed */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44  fine SQLITE_READ
44a0: 4f 4e 4c 59 20 20 20 20 20 38 20 20 20 2f 2a 20  ONLY     8   /* 
44b0: 41 74 74 65 6d 70 74 20 74 6f 20 77 72 69 74 65  Attempt to write
44c0: 20 61 20 72 65 61 64 6f 6e 6c 79 20 64 61 74 61   a readonly data
44d0: 62 61 73 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  base */.#define 
44e0: 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
44f0: 20 20 20 20 39 20 20 20 2f 2a 20 4f 70 65 72 61      9   /* Opera
4500: 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74 65 64 20  tion terminated 
4510: 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  by sqlite3_inter
4520: 72 75 70 74 28 29 2a 2f 0a 23 64 65 66 69 6e 65  rupt()*/.#define
4530: 20 53 51 4c 49 54 45 5f 49 4f 45 52 52 20 20 20   SQLITE_IOERR   
4540: 20 20 20 20 31 30 20 20 20 2f 2a 20 53 6f 6d 65      10   /* Some
4550: 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b 20 49 2f   kind of disk I/
4560: 4f 20 65 72 72 6f 72 20 6f 63 63 75 72 72 65 64  O error occurred
4570: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4580: 54 45 5f 43 4f 52 52 55 50 54 20 20 20 20 20 31  TE_CORRUPT     1
4590: 31 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  1   /* The datab
45a0: 61 73 65 20 64 69 73 6b 20 69 6d 61 67 65 20 69  ase disk image i
45b0: 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a 2f 0a 23  s malformed */.#
45c0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f  define SQLITE_NO
45d0: 54 46 4f 55 4e 44 20 20 20 20 31 32 20 20 20 2f  TFOUND    12   /
45e0: 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63 6f 64 65  * Unknown opcode
45f0: 20 69 6e 20 73 71 6c 69 74 65 33 5f 66 69 6c 65   in sqlite3_file
4600: 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f 0a 23 64  _control() */.#d
4610: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4c  efine SQLITE_FUL
4620: 4c 20 20 20 20 20 20 20 20 31 33 20 20 20 2f 2a  L        13   /*
4630: 20 49 6e 73 65 72 74 69 6f 6e 20 66 61 69 6c 65   Insertion faile
4640: 64 20 62 65 63 61 75 73 65 20 64 61 74 61 62 61  d because databa
4650: 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f 0a 23 64  se is full */.#d
4660: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
4670: 54 4f 50 45 4e 20 20 20 20 31 34 20 20 20 2f 2a  TOPEN    14   /*
4680: 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70 65 6e 20   Unable to open 
4690: 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
46a0: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
46b0: 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20 20 20 20  ITE_PROTOCOL    
46c0: 31 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  15   /* Database
46d0: 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f 6c 20 65   lock protocol e
46e0: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
46f0: 53 51 4c 49 54 45 5f 45 4d 50 54 59 20 20 20 20  SQLITE_EMPTY    
4700: 20 20 20 31 36 20 20 20 2f 2a 20 44 61 74 61 62     16   /* Datab
4710: 61 73 65 20 69 73 20 65 6d 70 74 79 20 2a 2f 0a  ase is empty */.
4720: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
4730: 43 48 45 4d 41 20 20 20 20 20 20 31 37 20 20 20  CHEMA      17   
4740: 2f 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20  /* The database 
4750: 73 63 68 65 6d 61 20 63 68 61 6e 67 65 64 20 2a  schema changed *
4760: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4770: 5f 54 4f 4f 42 49 47 20 20 20 20 20 20 31 38 20  _TOOBIG      18 
4780: 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f 72 20 42    /* String or B
4790: 4c 4f 42 20 65 78 63 65 65 64 73 20 73 69 7a 65  LOB exceeds size
47a0: 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65 66 69 6e   limit */.#defin
47b0: 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41  e SQLITE_CONSTRA
47c0: 49 4e 54 20 20 31 39 20 20 20 2f 2a 20 41 62 6f  INT  19   /* Abo
47d0: 72 74 20 64 75 65 20 74 6f 20 63 6f 6e 73 74 72  rt due to constr
47e0: 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f 6e 20 2a  aint violation *
47f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4800: 5f 4d 49 53 4d 41 54 43 48 20 20 20 20 32 30 20  _MISMATCH    20 
4810: 20 20 2f 2a 20 44 61 74 61 20 74 79 70 65 20 6d    /* Data type m
4820: 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64 65 66 69  ismatch */.#defi
4830: 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  ne SQLITE_MISUSE
4840: 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20 4c 69        21   /* Li
4850: 62 72 61 72 79 20 75 73 65 64 20 69 6e 63 6f 72  brary used incor
4860: 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65 66 69 6e  rectly */.#defin
4870: 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46 53 20 20  e SQLITE_NOLFS  
4880: 20 20 20 20 20 32 32 20 20 20 2f 2a 20 55 73 65       22   /* Use
4890: 73 20 4f 53 20 66 65 61 74 75 72 65 73 20 6e 6f  s OS features no
48a0: 74 20 73 75 70 70 6f 72 74 65 64 20 6f 6e 20 68  t supported on h
48b0: 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ost */.#define S
48c0: 51 4c 49 54 45 5f 41 55 54 48 20 20 20 20 20 20  QLITE_AUTH      
48d0: 20 20 32 33 20 20 20 2f 2a 20 41 75 74 68 6f 72    23   /* Author
48e0: 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65 64 20 2a  ization denied *
48f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4900: 5f 46 4f 52 4d 41 54 20 20 20 20 20 20 32 34 20  _FORMAT      24 
4910: 20 20 2f 2a 20 41 75 78 69 6c 69 61 72 79 20 64    /* Auxiliary d
4920: 61 74 61 62 61 73 65 20 66 6f 72 6d 61 74 20 65  atabase format e
4930: 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rror */.#define 
4940: 53 51 4c 49 54 45 5f 52 41 4e 47 45 20 20 20 20  SQLITE_RANGE    
4950: 20 20 20 32 35 20 20 20 2f 2a 20 32 6e 64 20 70     25   /* 2nd p
4960: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
4970: 74 65 33 5f 62 69 6e 64 20 6f 75 74 20 6f 66 20  te3_bind out of 
4980: 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66 69 6e 65  range */.#define
4990: 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44 42 20 20   SQLITE_NOTADB  
49a0: 20 20 20 20 32 36 20 20 20 2f 2a 20 46 69 6c 65      26   /* File
49b0: 20 6f 70 65 6e 65 64 20 74 68 61 74 20 69 73 20   opened that is 
49c0: 6e 6f 74 20 61 20 64 61 74 61 62 61 73 65 20 66  not a database f
49d0: 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ile */.#define S
49e0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 20 20 20  QLITE_NOTICE    
49f0: 20 20 32 37 20 20 20 2f 2a 20 4e 6f 74 69 66 69    27   /* Notifi
4a00: 63 61 74 69 6f 6e 73 20 66 72 6f 6d 20 73 71 6c  cations from sql
4a10: 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a 23 64  ite3_log() */.#d
4a20: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 57 41 52  efine SQLITE_WAR
4a30: 4e 49 4e 47 20 20 20 20 20 32 38 20 20 20 2f 2a  NING     28   /*
4a40: 20 57 61 72 6e 69 6e 67 73 20 66 72 6f 6d 20 73   Warnings from s
4a50: 71 6c 69 74 65 33 5f 6c 6f 67 28 29 20 2a 2f 0a  qlite3_log() */.
4a60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
4a70: 4f 57 20 20 20 20 20 20 20 20 20 31 30 30 20 20  OW         100  
4a80: 2f 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  /* sqlite3_step(
4a90: 29 20 68 61 73 20 61 6e 6f 74 68 65 72 20 72 6f  ) has another ro
4aa0: 77 20 72 65 61 64 79 20 2a 2f 0a 23 64 65 66 69  w ready */.#defi
4ab0: 6e 65 20 53 51 4c 49 54 45 5f 44 4f 4e 45 20 20  ne SQLITE_DONE  
4ac0: 20 20 20 20 20 20 31 30 31 20 20 2f 2a 20 73 71        101  /* sq
4ad0: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4ae0: 20 66 69 6e 69 73 68 65 64 20 65 78 65 63 75 74   finished execut
4af0: 69 6e 67 20 2a 2f 0a 2f 2a 20 65 6e 64 2d 6f 66  ing */./* end-of
4b00: 2d 65 72 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a  -error-codes */.
4b10: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
4b20: 20 45 78 74 65 6e 64 65 64 20 52 65 73 75 6c 74   Extended Result
4b30: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
4b40: 44 53 3a 20 7b 65 78 74 65 6e 64 65 64 20 72 65  DS: {extended re
4b50: 73 75 6c 74 20 63 6f 64 65 20 64 65 66 69 6e 69  sult code defini
4b60: 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  tions}.**.** In 
4b70: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4b80: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4b90: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4ba0: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 33 30 20  eturn one of 30 
4bb0: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 72 65 73 75  integer.** [resu
4bc0: 6c 74 20 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65  lt codes].  Howe
4bd0: 76 65 72 2c 20 65 78 70 65 72 69 65 6e 63 65 20  ver, experience 
4be0: 68 61 73 20 73 68 6f 77 6e 20 74 68 61 74 20 6d  has shown that m
4bf0: 61 6e 79 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20  any of.** these 
4c00: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4c10: 20 74 6f 6f 20 63 6f 61 72 73 65 2d 67 72 61 69   too coarse-grai
4c20: 6e 65 64 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f  ned.  They do no
4c30: 74 20 70 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20  t provide as.** 
4c40: 6d 75 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  much information
4c50: 20 61 62 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20   about problems 
4c60: 61 73 20 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d  as programmers m
4c70: 69 67 68 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61  ight like.  In a
4c80: 6e 20 65 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61  n effort to.** a
4c90: 64 64 72 65 73 73 20 74 68 69 73 2c 20 6e 65 77  ddress this, new
4ca0: 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
4cb0: 51 4c 69 74 65 20 28 76 65 72 73 69 6f 6e 20 33  QLite (version 3
4cc0: 2e 33 2e 38 20 61 6e 64 20 6c 61 74 65 72 29 20  .3.8 and later) 
4cd0: 69 6e 63 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f  include.** suppo
4ce0: 72 74 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  rt for additiona
4cf0: 6c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 74  l result codes t
4d00: 68 61 74 20 70 72 6f 76 69 64 65 20 6d 6f 72 65  hat provide more
4d10: 20 64 65 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d   detailed inform
4d20: 61 74 69 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65  ation.** about e
4d30: 72 72 6f 72 73 2e 20 54 68 65 73 65 20 5b 65 78  rrors. These [ex
4d40: 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f  tended result co
4d50: 64 65 73 5d 20 61 72 65 20 65 6e 61 62 6c 65 64  des] are enabled
4d60: 20 6f 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20   or disabled.** 
4d70: 6f 6e 20 61 20 70 65 72 20 64 61 74 61 62 61 73  on a per databas
4d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 61 73  e connection bas
4d90: 69 73 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  is using the.** 
4da0: 5b 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64 65  [sqlite3_extende
4db0: 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65 73 28 29  d_result_codes()
4dc0: 5d 20 41 50 49 2e 20 20 4f 72 2c 20 74 68 65 20  ] API.  Or, the 
4dd0: 65 78 74 65 6e 64 65 64 20 63 6f 64 65 20 66 6f  extended code fo
4de0: 72 0a 2a 2a 20 74 68 65 20 6d 6f 73 74 20 72 65  r.** the most re
4df0: 63 65 6e 74 20 65 72 72 6f 72 20 63 61 6e 20 62  cent error can b
4e00: 65 20 6f 62 74 61 69 6e 65 64 20 75 73 69 6e 67  e obtained using
4e10: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 78 74  .** [sqlite3_ext
4e20: 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 5d  ended_errcode()]
4e30: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4e40: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4e50: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4e60: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4e70: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4e80: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4e90: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4ea0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4eb0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ec0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4ed0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4ee0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4ef0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4f00: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4f10: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4f20: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4f30: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4f40: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4f50: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4f60: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4f70: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4f80: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4f90: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4fa0: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4fb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4fc0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4fd0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4fe0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
5000: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
5010: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
5020: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
5030: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5040: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
5050: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5060: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
5070: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5080: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
5090: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50a0: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
50b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
50c0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
50d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
50e0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
50f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5100: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
5110: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5120: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
5130: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5140: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
5150: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5160: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
5170: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5180: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
5190: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
51a0: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
51b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
51c0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
51d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
51e0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
51f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5200: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
5210: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5220: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
5230: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5240: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
5250: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5260: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
5270: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5280: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
5290: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52a0: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
52b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
52c0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
52d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
52e0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
52f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5300: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
5310: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5320: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5330: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5340: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5350: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5360: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5370: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5380: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5390: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53a0: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
53b0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
53c0: 5f 44 45 4c 45 54 45 5f 4e 4f 45 4e 54 20 20 20  _DELETE_NOENT   
53d0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
53e0: 20 7c 20 28 32 33 3c 3c 38 29 29 0a 23 64 65 66   | (23<<8)).#def
53f0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5400: 5f 4d 4d 41 50 20 20 20 20 20 20 20 20 20 20 20  _MMAP           
5410: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5420: 20 7c 20 28 32 34 3c 3c 38 29 29 0a 23 64 65 66   | (24<<8)).#def
5430: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5440: 5f 47 45 54 54 45 4d 50 50 41 54 48 20 20 20 20  _GETTEMPPATH    
5450: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5460: 20 7c 20 28 32 35 3c 3c 38 29 29 0a 23 64 65 66   | (25<<8)).#def
5470: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5480: 5f 43 4f 4e 56 50 41 54 48 20 20 20 20 20 20 20  _CONVPATH       
5490: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
54a0: 20 7c 20 28 32 36 3c 3c 38 29 29 0a 23 64 65 66   | (26<<8)).#def
54b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
54c0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
54d0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
54e0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
54f0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
5500: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
5510: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5520: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
5540: 59 5f 53 4e 41 50 53 48 4f 54 20 20 20 20 20 20  Y_SNAPSHOT      
5550: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5560: 59 20 20 20 7c 20 20 28 32 3c 3c 38 29 29 0a 23  Y   |  (2<<8)).#
5570: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5580: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5590: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
55a0: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
55d0: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
55e0: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
55f0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5600: 45 5f 43 41 4e 54 4f 50 45 4e 5f 46 55 4c 4c 50  E_CANTOPEN_FULLP
5610: 41 54 48 20 20 20 20 20 20 20 28 53 51 4c 49 54  ATH       (SQLIT
5620: 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28 33 3c  E_CANTOPEN | (3<
5630: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
5640: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5f 43 4f 4e  ITE_CANTOPEN_CON
5650: 56 50 41 54 48 20 20 20 20 20 20 20 28 53 51 4c  VPATH       (SQL
5660: 49 54 45 5f 43 41 4e 54 4f 50 45 4e 20 7c 20 28  ITE_CANTOPEN | (
5670: 34 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  4<<8)).#define S
5680: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5f 56 54  QLITE_CORRUPT_VT
5690: 41 42 20 20 20 20 20 20 20 20 20 20 20 20 28 53  AB            (S
56a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 7c 20  QLITE_CORRUPT | 
56b0: 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (1<<8)).#define 
56c0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f  SQLITE_READONLY_
56d0: 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20 28  RECOVERY       (
56e0: 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20  SQLITE_READONLY 
56f0: 7c 20 28 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e  | (1<<8)).#defin
5700: 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  e SQLITE_READONL
5710: 59 5f 43 41 4e 54 4c 4f 43 4b 20 20 20 20 20 20  Y_CANTLOCK      
5720: 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c   (SQLITE_READONL
5730: 59 20 7c 20 28 32 3c 3c 38 29 29 0a 23 64 65 66  Y | (2<<8)).#def
5740: 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 4f  ine SQLITE_READO
5750: 4e 4c 59 5f 52 4f 4c 4c 42 41 43 4b 20 20 20 20  NLY_ROLLBACK    
5760: 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41 44 4f     (SQLITE_READO
5770: 4e 4c 59 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64  NLY | (3<<8)).#d
5780: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 41  efine SQLITE_REA
5790: 44 4f 4e 4c 59 5f 44 42 4d 4f 56 45 44 20 20 20  DONLY_DBMOVED   
57a0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 52 45 41       (SQLITE_REA
57b0: 44 4f 4e 4c 59 20 7c 20 28 34 3c 3c 38 29 29 0a  DONLY | (4<<8)).
57c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
57d0: 42 4f 52 54 5f 52 4f 4c 4c 42 41 43 4b 20 20 20  BORT_ROLLBACK   
57e0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 41         (SQLITE_A
57f0: 42 4f 52 54 20 7c 20 28 32 3c 3c 38 29 29 0a 23  BORT | (2<<8)).#
5800: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5810: 4e 53 54 52 41 49 4e 54 5f 43 48 45 43 4b 20 20  NSTRAINT_CHECK  
5820: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5830: 4e 53 54 52 41 49 4e 54 20 7c 20 28 31 3c 3c 38  NSTRAINT | (1<<8
5840: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5850: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 43 4f 4d  E_CONSTRAINT_COM
5860: 4d 49 54 48 4f 4f 4b 20 20 20 28 53 51 4c 49 54  MITHOOK   (SQLIT
5870: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5880: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5890: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58a0: 5f 46 4f 52 45 49 47 4e 4b 45 59 20 20 20 28 53  _FOREIGNKEY   (S
58b0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
58c0: 20 7c 20 28 33 3c 3c 38 29 29 0a 23 64 65 66 69   | (3<<8)).#defi
58d0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
58e0: 41 49 4e 54 5f 46 55 4e 43 54 49 4f 4e 20 20 20  AINT_FUNCTION   
58f0: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5900: 41 49 4e 54 20 7c 20 28 34 3c 3c 38 29 29 0a 23  AINT | (4<<8)).#
5910: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5920: 4e 53 54 52 41 49 4e 54 5f 4e 4f 54 4e 55 4c 4c  NSTRAINT_NOTNULL
5930: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5940: 4e 53 54 52 41 49 4e 54 20 7c 20 28 35 3c 3c 38  NSTRAINT | (5<<8
5950: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5960: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 50 52 49  E_CONSTRAINT_PRI
5970: 4d 41 52 59 4b 45 59 20 20 20 28 53 51 4c 49 54  MARYKEY   (SQLIT
5980: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 20 28  E_CONSTRAINT | (
5990: 36 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  6<<8)).#define S
59a0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59b0: 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 28 53  _TRIGGER      (S
59c0: 51 4c 49 54 45 5f 43 4f 4e 53 54 52 41 49 4e 54  QLITE_CONSTRAINT
59d0: 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64 65 66 69   | (7<<8)).#defi
59e0: 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52  ne SQLITE_CONSTR
59f0: 41 49 4e 54 5f 55 4e 49 51 55 45 20 20 20 20 20  AINT_UNIQUE     
5a00: 20 20 28 53 51 4c 49 54 45 5f 43 4f 4e 53 54 52    (SQLITE_CONSTR
5a10: 41 49 4e 54 20 7c 20 28 38 3c 3c 38 29 29 0a 23  AINT | (8<<8)).#
5a20: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
5a30: 4e 53 54 52 41 49 4e 54 5f 56 54 41 42 20 20 20  NSTRAINT_VTAB   
5a40: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 4f        (SQLITE_CO
5a50: 4e 53 54 52 41 49 4e 54 20 7c 20 28 39 3c 3c 38  NSTRAINT | (9<<8
5a60: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
5a70: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 52 4f 57  E_CONSTRAINT_ROW
5a80: 49 44 20 20 20 20 20 20 20 20 28 53 51 4c 49 54  ID        (SQLIT
5a90: 45 5f 43 4f 4e 53 54 52 41 49 4e 54 20 7c 28 31  E_CONSTRAINT |(1
5aa0: 30 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  0<<8)).#define S
5ab0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5ac0: 4f 56 45 52 5f 57 41 4c 20 20 20 20 20 20 28 53  OVER_WAL      (S
5ad0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5ae0: 31 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  1<<8)).#define S
5af0: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 5f 52 45 43  QLITE_NOTICE_REC
5b00: 4f 56 45 52 5f 52 4f 4c 4c 42 41 43 4b 20 28 53  OVER_ROLLBACK (S
5b10: 51 4c 49 54 45 5f 4e 4f 54 49 43 45 20 7c 20 28  QLITE_NOTICE | (
5b20: 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53  2<<8)).#define S
5b30: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 5f 41 55  QLITE_WARNING_AU
5b40: 54 4f 49 4e 44 45 58 20 20 20 20 20 20 20 28 53  TOINDEX       (S
5b50: 51 4c 49 54 45 5f 57 41 52 4e 49 4e 47 20 7c 20  QLITE_WARNING | 
5b60: 28 31 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43  (1<<8))../*.** C
5b70: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46  API3REF: Flags F
5b80: 6f 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65  or File Open Ope
5b90: 72 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68  rations.**.** Th
5ba0: 65 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61  ese bit values a
5bb0: 72 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20  re intended for 
5bc0: 75 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72  use in the.** 3r
5bd0: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  d parameter to t
5be0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  he [sqlite3_open
5bf0: 5f 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65  _v2()] interface
5c00: 20 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34   and.** in the 4
5c10: 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
5c20: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  the [sqlite3_vfs
5c30: 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a  .xOpen] method..
5c40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5c50: 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20  E_OPEN_READONLY 
5c60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5c70: 30 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  01  /* Ok for sq
5c80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5c90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ca0: 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45  E_OPEN_READWRITE
5cb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5cc0: 30 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  02  /* Ok for sq
5cd0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5ce0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5cf0: 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20  E_OPEN_CREATE   
5d00: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5d10: 30 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  04  /* Ok for sq
5d20: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5d30: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d40: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
5d50: 4c 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30  LOSE    0x000000
5d60: 30 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  08  /* VFS only 
5d70: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5d80: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
5d90: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5da0: 31 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  10  /* VFS only 
5db0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5dc0: 45 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59  E_OPEN_AUTOPROXY
5dd0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5de0: 32 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  20  /* VFS only 
5df0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e00: 45 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20  E_OPEN_URI      
5e10: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e20: 34 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  40  /* Ok for sq
5e30: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e40: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5e50: 45 5f 4f 50 45 4e 5f 4d 45 4d 4f 52 59 20 20 20  E_OPEN_MEMORY   
5e60: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30          0x000000
5e70: 38 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  80  /* Ok for sq
5e80: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
5e90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ea0: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20  E_OPEN_MAIN_DB  
5eb0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31          0x000001
5ec0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5ed0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5ee0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20  E_OPEN_TEMP_DB  
5ef0: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32          0x000002
5f00: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f10: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f20: 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54  E_OPEN_TRANSIENT
5f30: 5f 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34  _DB     0x000004
5f40: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f50: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5f60: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
5f70: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38  NAL     0x000008
5f80: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5f90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fa0: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52  E_OPEN_TEMP_JOUR
5fb0: 4e 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30  NAL     0x000010
5fc0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
5fd0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
5fe0: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
5ff0: 4c 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30  L       0x000020
6000: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6010: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6020: 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f  E_OPEN_MASTER_JO
6030: 55 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30  URNAL   0x000040
6040: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
6050: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6060: 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20  E_OPEN_NOMUTEX  
6070: 20 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30          0x000080
6080: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6090: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60a0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
60b0: 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
60c0: 20 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30          0x000100
60d0: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
60e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
60f0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6100: 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
6110: 48 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30  HE      0x000200
6120: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6130: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6140: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
6150: 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41  E_OPEN_PRIVATECA
6160: 43 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30  CHE     0x000400
6170: 30 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71  00  /* Ok for sq
6180: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
6190: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
61a0: 45 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20  E_OPEN_WAL      
61b0: 20 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30          0x000800
61c0: 30 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20  00  /* VFS only 
61d0: 2a 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a  */../* 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 20 20 20 30 78 30 30 46 30 30           0x00F00
6200: 30 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  000 */../*.** CA
6210: 50 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43  PI3REF: Device C
6220: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a  haracteristics.*
6230: 2a 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65  *.** The xDevice
6240: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20  Characteristics 
6250: 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73  method of the [s
6260: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
6270: 73 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74  s].** object ret
6280: 75 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20  urns an integer 
6290: 77 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f  which is a vecto
62a0: 72 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 62 69  r of these.** bi
62b0: 74 20 76 61 6c 75 65 73 20 65 78 70 72 65 73 73  t values express
62c0: 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63 74 65  ing I/O characte
62d0: 72 69 73 74 69 63 73 20 6f 66 20 74 68 65 20 6d  ristics of the m
62e0: 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a 20 64  ass storage.** d
62f0: 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c 64 73  evice that holds
6300: 20 74 68 65 20 66 69 6c 65 20 74 68 61 74 20 74   the file that t
6310: 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  he [sqlite3_io_m
6320: 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66 65 72  ethods].** refer
6330: 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  s to..**.** The 
6340: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
6350: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
6360: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
6370: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
6380: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
6390: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
63a0: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
63b0: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
63c0: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
63d0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
63e0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
63f0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
6400: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
6410: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
6420: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
6430: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
6440: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
6450: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
6460: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
6470: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
6480: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
6490: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
64a0: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
64b0: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
64c0: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
64d0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
64e0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
64f0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
6500: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
6510: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
6520: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
6530: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
6540: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
6550: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
6560: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
6570: 29 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49  ).  The SQLITE_I
6580: 4f 43 41 50 5f 50 4f 57 45 52 53 41 46 45 5f 4f  OCAP_POWERSAFE_O
6590: 56 45 52 57 52 49 54 45 20 70 72 6f 70 65 72 74  VERWRITE propert
65a0: 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20  y means that.** 
65b0: 61 66 74 65 72 20 72 65 62 6f 6f 74 20 66 6f 6c  after reboot fol
65c0: 6c 6f 77 69 6e 67 20 61 20 63 72 61 73 68 20 6f  lowing a crash o
65d0: 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c 20 74 68  r power loss, th
65e0: 65 20 6f 6e 6c 79 20 62 79 74 65 73 20 69 6e 20  e only bytes in 
65f0: 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61 74 20 77  a.** file that w
6600: 65 72 65 20 77 72 69 74 74 65 6e 20 61 74 20 74  ere written at t
6610: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6c  he application l
6620: 65 76 65 6c 20 6d 69 67 68 74 20 68 61 76 65 20  evel might have 
6630: 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e 64 20 74  changed.** and t
6640: 68 61 74 20 61 64 6a 61 63 65 6e 74 20 62 79 74  hat adjacent byt
6650: 65 73 2c 20 65 76 65 6e 20 62 79 74 65 73 20 77  es, even bytes w
6660: 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20 73  ithin the same s
6670: 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20 67 75 61  ector are.** gua
6680: 72 61 6e 74 65 65 64 20 74 6f 20 62 65 20 75 6e  ranteed to be un
6690: 63 68 61 6e 67 65 64 2e 20 20 54 68 65 20 53 51  changed.  The SQ
66a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c  LITE_IOCAP_UNDEL
66b0: 45 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e  ETABLE_WHEN_OPEN
66c0: 0a 2a 2a 20 66 6c 61 67 20 69 6e 64 69 63 61 74  .** flag indicat
66d0: 65 20 74 68 61 74 20 61 20 66 69 6c 65 20 63 61  e that a file ca
66e0: 6e 6e 6f 74 20 62 65 20 64 65 6c 65 74 65 64 20  nnot be deleted 
66f0: 77 68 65 6e 20 6f 70 65 6e 2e 20 20 54 68 65 0a  when open.  The.
6700: 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ** SQLITE_IOCAP_
6710: 49 4d 4d 55 54 41 42 4c 45 20 66 6c 61 67 20 69  IMMUTABLE flag i
6720: 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74 68  ndicates that th
6730: 65 20 66 69 6c 65 20 69 73 20 6f 6e 0a 2a 2a 20  e file is on.** 
6740: 72 65 61 64 2d 6f 6e 6c 79 20 6d 65 64 69 61 20  read-only media 
6750: 61 6e 64 20 63 61 6e 6e 6f 74 20 62 65 20 63 68  and cannot be ch
6760: 61 6e 67 65 64 20 65 76 65 6e 20 62 79 20 70 72  anged even by pr
6770: 6f 63 65 73 73 65 73 20 77 69 74 68 0a 2a 2a 20  ocesses with.** 
6780: 65 6c 65 76 61 74 65 64 20 70 72 69 76 69 6c 65  elevated privile
6790: 67 65 73 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  ges..*/.#define 
67a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
67b0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
67c0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
67d0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
67e0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
67f0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
6800: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
6810: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
6820: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
6830: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
6840: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
6850: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
6860: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
6870: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
6880: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
6890: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
68a0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
68b0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
68c0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
68d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
68e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
68f0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
6900: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
6910: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
6920: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
6930: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
6940: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
6950: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
6960: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
6970: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
6980: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
6990: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
69a0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
69b0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
69c0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
69d0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
69e0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
69f0: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
6a00: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
6a10: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
6a20: 20 30 78 30 30 30 30 30 38 30 30 0a 23 64 65 66   0x00000800.#def
6a30: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
6a40: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
6a50: 52 49 54 45 20 20 20 20 30 78 30 30 30 30 31 30  RITE    0x000010
6a60: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6a70: 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
6a80: 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30  E              0
6a90: 78 30 30 30 30 32 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00002000../*.**
6aa0: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6ab0: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6ac0: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6ad0: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6ae0: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
6af0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
6b00: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
6b10: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
6b20: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
6b30: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
6b40: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6b50: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6b60: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6b70: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6b80: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6b90: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6ba0: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6bb0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6bc0: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6bd0: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6be0: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
6bf0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
6c00: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
6c10: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
6c20: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
6c30: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
6c40: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6c50: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6c60: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6c70: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6c80: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6c90: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6ca0: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6cb0: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6cc0: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6cd0: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6ce0: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
6cf0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
6d00: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
6d10: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
6d20: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
6d30: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
6d40: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6d50: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6d60: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6d70: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6d80: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6d90: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6da0: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6db0: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6dc0: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6dd0: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6de0: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
6df0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
6e00: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
6e10: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
6e20: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
6e30: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
6e40: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6e50: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6e60: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6e70: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6e80: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6e90: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6ea0: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6eb0: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6ec0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6ed0: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6ee0: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6ef0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
6f00: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
6f10: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
6f20: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
6f30: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
6f40: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6f50: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6f60: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6f70: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6f80: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6f90: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6fa0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6fb0: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6fc0: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6fd0: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
6fe0: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
6ff0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
7000: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
7010: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
7020: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
7030: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
7040: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
7050: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
7060: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
7070: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
7080: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
7090: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
70a0: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
70b0: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
70c0: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
70d0: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
70e0: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
70f0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
7100: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
7110: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
7120: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
7130: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
7140: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
7150: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
7160: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
7170: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
7180: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
7190: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
71a0: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
71b0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
71c0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
71d0: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
71e0: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
71f0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
7200: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
7210: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
7220: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
7230: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
7240: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
7250: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
7260: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
7270: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
7280: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
7290: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
72a0: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
72b0: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
72c0: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
72d0: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
72e0: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
72f0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
7300: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
7310: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
7320: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
7330: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
7340: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
7350: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
7360: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
7370: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
7380: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
7390: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
73a0: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
73b0: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
73c0: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
73d0: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
73e0: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
73f0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
7400: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
7410: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
7420: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
7430: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
7440: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
7450: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
7460: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
7470: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
7480: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
7490: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
74a0: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
74b0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
74c0: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
74d0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
74e0: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
74f0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
7500: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
7510: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
7520: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
7530: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
7540: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
7550: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
7560: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
7570: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
7580: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
7590: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
75a0: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
75b0: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
75c0: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
75d0: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
75e0: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
75f0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7600: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
7610: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
7620: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
7630: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
7640: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
7650: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
7660: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
7670: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
7680: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
7690: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
76a0: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
76b0: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
76c0: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
76d0: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
76e0: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
76f0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
7700: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
7710: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
7720: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
7730: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
7740: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
7750: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
7760: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
7770: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
7780: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
7790: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
77a0: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
77b0: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
77c0: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
77d0: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
77e0: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
77f0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
7800: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
7810: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
7820: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
7830: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
7840: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
7850: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
7860: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
7870: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
7880: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
7890: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
78a0: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
78b0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
78c0: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
78d0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
78e0: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
78f0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
7900: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
7910: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
7920: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
7930: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
7940: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
7950: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
7960: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
7970: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
7980: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
7990: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
79a0: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
79b0: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
79c0: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
79d0: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
79e0: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
79f0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
7a00: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
7a10: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
7a20: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
7a30: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
7a40: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7a50: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7a60: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7a70: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7a80: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7a90: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7aa0: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7ab0: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7ac0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7ad0: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7ae0: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
7af0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
7b00: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
7b10: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
7b20: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
7b30: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
7b40: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7b50: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7b60: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7b70: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7b80: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7b90: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7ba0: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7bb0: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7bc0: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7bd0: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7be0: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
7bf0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
7c00: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
7c10: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
7c20: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
7c30: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
7c40: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7c50: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7c60: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7c70: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7c80: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7c90: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7ca0: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7cb0: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7cc0: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7cd0: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7ce0: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
7cf0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
7d00: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
7d10: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
7d20: 2a 20 41 20 5b 66 69 6c 65 20 63 6f 6e 74 72 6f  * A [file contro
7d30: 6c 20 6f 70 63 6f 64 65 73 20 7c 20 6c 69 73 74  l opcodes | list
7d40: 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c 65 73   of opcodes] les
7d50: 73 20 74 68 61 6e 20 31 30 30 20 69 73 20 61 76  s than 100 is av
7d60: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70 70 6c  ailable..** Appl
7d70: 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 64 65  ications that de
7d80: 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20 78 46  fine a custom xF
7d90: 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f  ileControl metho
7da0: 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f 70 63  d should use opc
7db0: 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65 72 20  odes.** greater 
7dc0: 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76 6f 69  than 100 to avoi
7dd0: 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20 56 46  d conflicts.  VF
7de0: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7df0: 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75  s should.** retu
7e00: 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f  rn [SQLITE_NOTFO
7e10: 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20 63 6f  UND] for file co
7e20: 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20 74 68  ntrol opcodes th
7e30: 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a  at they do not.*
7e40: 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a 2a 0a  * recognize..**.
7e50: 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72 53 69  ** The xSectorSi
7e60: 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65 74 75  ze() method retu
7e70: 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72 20 73  rns the sector s
7e80: 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20 64 65  ize of the.** de
7e90: 76 69 63 65 20 74 68 61 74 20 75 6e 64 65 72 6c  vice that underl
7ea0: 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20 20 54  ies the file.  T
7eb0: 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65 20 69  he sector size i
7ec0: 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d 75 6d  s the.** minimum
7ed0: 20 77 72 69 74 65 20 74 68 61 74 20 63 61 6e 20   write that can 
7ee0: 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77 69 74  be performed wit
7ef0: 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e 67 0a  hout disturbing.
7f00: 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73 20 69  ** other bytes i
7f10: 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54 68 65  n the file.  The
7f20: 20 78 44 65 76 69 63 65 43 68 61 72 61 63 74 65   xDeviceCharacte
7f30: 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d 65 74  ristics().** met
7f40: 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20 62 69  hod returns a bi
7f50: 74 20 76 65 63 74 6f 72 20 64 65 73 63 72 69 62  t vector describ
7f60: 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20 6f 66  ing behaviors of
7f70: 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c 79 69   the.** underlyi
7f80: 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a 2a 2a  ng device:.**.**
7f90: 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
7fa0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7fb0: 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  IC].** <li> [SQL
7fc0: 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43  ITE_IOCAP_ATOMIC
7fd0: 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  512].** <li> [SQ
7fe0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
7ff0: 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C1K].** <li> [SQ
8000: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8010: 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C2K].** <li> [SQ
8020: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8030: 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C4K].** <li> [SQ
8040: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8050: 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  C8K].** <li> [SQ
8060: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
8070: 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  C16K].** <li> [S
8080: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
8090: 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC32K].** <li> [
80a0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
80b0: 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC64K].** <li> 
80c0: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41  [SQLITE_IOCAP_SA
80d0: 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20 3c 6c  FE_APPEND].** <l
80e0: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
80f0: 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a 2a 20  _SEQUENTIAL].** 
8100: 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  </ul>.**.** The 
8110: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
8120: 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d 65 61  MIC property mea
8130: 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72 69 74  ns that all writ
8140: 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73 69 7a  es of.** any siz
8150: 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  e are atomic.  T
8160: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8170: 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75 65 73  ATOMICnnn values
8180: 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20 77 72  .** mean that wr
8190: 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73 20 74  ites of blocks t
81a0: 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79 74 65  hat are nnn byte
81b0: 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a 2a 2a  s in size and.**
81c0: 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74 6f 20   are aligned to 
81d0: 61 6e 20 61 64 64 72 65 73 73 20 77 68 69 63 68  an address which
81e0: 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6d   is an integer m
81f0: 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20 6e 6e  ultiple of.** nn
8200: 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20 20 54  n are atomic.  T
8210: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
8220: 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61 6c 75  SAFE_APPEND valu
8230: 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61 74 20  e means.** that 
8240: 77 68 65 6e 20 64 61 74 61 20 69 73 20 61 70 70  when data is app
8250: 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c 65 2c  ended to a file,
8260: 20 74 68 65 20 64 61 74 61 20 69 73 20 61 70 70   the data is app
8270: 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74 20 74  ended.** first t
8280: 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20  hen the size of 
8290: 74 68 65 20 66 69 6c 65 20 69 73 20 65 78 74 65  the file is exte
82a0: 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68 65 20  nded, never the 
82b0: 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61 72 6f  other.** way aro
82c0: 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49 54 45  und.  The SQLITE
82d0: 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41  _IOCAP_SEQUENTIA
82e0: 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61 6e 73  L property means
82f0: 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72 6d 61   that.** informa
8300: 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65 6e 20  tion is written 
8310: 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65 20 73  to disk in the s
8320: 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63 61 6c  ame order as cal
8330: 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74 65 28  ls.** to xWrite(
8340: 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52 65 61  )..**.** If xRea
8350: 64 28 29 20 72 65 74 75 72 6e 73 20 53 51 4c 49  d() returns SQLI
8360: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
8370: 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c 73 6f  EAD it must also
8380: 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68 65 20   fill.** in the 
8390: 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e 73 20  unread portions 
83a0: 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 77 69  of the buffer wi
83b0: 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56 46 53  th zeros.  A VFS
83c0: 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73 20 74   that.** fails t
83d0: 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68 6f 72  o zero-fill shor
83e0: 74 20 72 65 61 64 73 20 6d 69 67 68 74 20 73 65  t reads might se
83f0: 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48 6f 77  em to work.  How
8400: 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75 72 65  ever,.** failure
8410: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
8420: 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c 20 65  ort reads will e
8430: 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64 20 74  ventually lead t
8440: 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  o.** database co
8450: 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70  rruption..*/.typ
8460: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
8470: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 73  te3_io_methods s
8480: 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64  qlite3_io_method
8490: 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74 65  s;.struct sqlite
84a0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b 0a 20  3_io_methods {. 
84b0: 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 0a 20   int iVersion;. 
84c0: 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29 28 73   int (*xClose)(s
84d0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
84e0: 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28 73 71   int (*xRead)(sq
84f0: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76 6f 69  lite3_file*, voi
8500: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
8510: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
8520: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57 72 69  t);.  int (*xWri
8530: 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  te)(sqlite3_file
8540: 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
8550: 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69 74 65  int iAmt, sqlite
8560: 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a  3_int64 iOfst);.
8570: 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63 61 74    int (*xTruncat
8580: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
8590: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
85a0: 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28 2a 78  size);.  int (*x
85b0: 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f 66 69  Sync)(sqlite3_fi
85c0: 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b  le*, int flags);
85d0: 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 53 69  .  int (*xFileSi
85e0: 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ze)(sqlite3_file
85f0: 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  *, sqlite3_int64
8600: 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e 74 20   *pSize);.  int 
8610: 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  (*xLock)(sqlite3
8620: 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20  _file*, int);.  
8630: 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29 28 73  int (*xUnlock)(s
8640: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
8650: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 68 65  t);.  int (*xChe
8660: 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b 29 28  ckReservedLock)(
8670: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
8680: 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20  nt *pResOut);.  
8690: 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e 74 72  int (*xFileContr
86a0: 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ol)(sqlite3_file
86b0: 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69 64 20  *, int op, void 
86c0: 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a  *pArg);.  int (*
86d0: 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73 71 6c  xSectorSize)(sql
86e0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
86f0: 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68 61 72  nt (*xDeviceChar
8700: 61 63 74 65 72 69 73 74 69 63 73 29 28 73 71 6c  acteristics)(sql
8710: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 2f  ite3_file*);.  /
8720: 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  * Methods above 
8730: 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76 65  are valid for ve
8740: 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69 6e 74  rsion 1 */.  int
8750: 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71 6c 69   (*xShmMap)(sqli
8760: 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 69  te3_file*, int i
8770: 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20 69 6e  Pg, int pgsz, in
8780: 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69 6c 65  t, void volatile
8790: 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68  **);.  int (*xSh
87a0: 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f 66  mLock)(sqlite3_f
87b0: 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73 65 74  ile*, int offset
87c0: 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66 6c 61  , int n, int fla
87d0: 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 53  gs);.  void (*xS
87e0: 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c 69 74  hmBarrier)(sqlit
87f0: 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74  e3_file*);.  int
8800: 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28 73 71   (*xShmUnmap)(sq
8810: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
8820: 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a 20 20   deleteFlag);.  
8830: 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76 65  /* Methods above
8840: 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20 76   are valid for v
8850: 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20 69 6e  ersion 2 */.  in
8860: 74 20 28 2a 78 46 65 74 63 68 29 28 73 71 6c 69  t (*xFetch)(sqli
8870: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
8880: 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 2c 20  e3_int64 iOfst, 
8890: 69 6e 74 20 69 41 6d 74 2c 20 76 6f 69 64 20 2a  int iAmt, void *
88a0: 2a 70 70 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55  *pp);.  int (*xU
88b0: 6e 66 65 74 63 68 29 28 73 71 6c 69 74 65 33 5f  nfetch)(sqlite3_
88c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
88d0: 6e 74 36 34 20 69 4f 66 73 74 2c 20 76 6f 69 64  nt64 iOfst, void
88e0: 20 2a 70 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f   *p);.  /* Metho
88f0: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
8900: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33  id for version 3
8910: 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69 6f   */.  /* Additio
8920: 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79 20  nal methods may 
8930: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
8940: 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a 7d  re releases */.}
8950: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
8960: 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c 65  F: Standard File
8970: 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65 73   Control Opcodes
8980: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 66  .** KEYWORDS: {f
8990: 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f  ile control opco
89a0: 64 65 73 7d 20 7b 66 69 6c 65 20 63 6f 6e 74 72  des} {file contr
89b0: 6f 6c 20 6f 70 63 6f 64 65 7d 0a 2a 2a 0a 2a 2a  ol opcode}.**.**
89c0: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
89d0: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
89e0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
89f0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
8a00: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
8a10: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
8a20: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
8a30: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
8a40: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
8a50: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
8a60: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
8a70: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
8a80: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
8a90: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
8aa0: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
8ab0: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
8ac0: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
8ad0: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
8ae0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
8af0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
8b00: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
8b10: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
8b20: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
8b30: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8b40: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8b50: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8b60: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8b70: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8b80: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8b90: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8ba0: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8bb0: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8bc0: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8bd0: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
8be0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
8bf0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
8c00: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
8c10: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
8c20: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
8c30: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8c40: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8c50: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8c60: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8c70: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8c80: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8c90: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8ca0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8cb0: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8cc0: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8cd0: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
8ce0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
8cf0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
8d00: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
8d10: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
8d20: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
8d30: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8d40: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8d50: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8d60: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8d70: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8d80: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8d90: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8da0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8db0: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8dc0: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8dd0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
8de0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
8df0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
8e00: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
8e10: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
8e20: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
8e30: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8e40: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8e50: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8e60: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8e70: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8e80: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8e90: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8ea0: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8eb0: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8ec0: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8ed0: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
8ee0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
8ef0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
8f00: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
8f10: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
8f20: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
8f30: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8f40: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8f50: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8f60: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8f70: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8f80: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8f90: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8fa0: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8fb0: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
8fc0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8fd0: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8fe0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
8ff0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
9000: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
9010: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
9020: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
9030: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
9040: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
9050: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
9060: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
9070: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
9080: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
9090: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
90a0: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
90b0: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
90c0: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
90d0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
90e0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
90f0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 4e 6f 20  OMITTED]].** No 
9100: 6c 6f 6e 67 65 72 20 69 6e 20 75 73 65 2e 0a 2a  longer in use..*
9110: 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54  *.** <li>[[SQLIT
9120: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5d 5d 0a 2a  E_FCNTL_SYNC]].*
9130: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
9140: 4e 54 4c 5f 53 59 4e 43 5d 20 6f 70 63 6f 64 65  NTL_SYNC] opcode
9150: 20 69 73 20 67 65 6e 65 72 61 74 65 64 20 69 6e   is generated in
9160: 74 65 72 6e 61 6c 6c 79 20 62 79 20 53 51 4c 69  ternally by SQLi
9170: 74 65 20 61 6e 64 0a 2a 2a 20 73 65 6e 74 20 74  te and.** sent t
9180: 6f 20 74 68 65 20 56 46 53 20 69 6d 6d 65 64 69  o the VFS immedi
9190: 61 74 65 6c 79 20 62 65 66 6f 72 65 20 74 68 65  ately before the
91a0: 20 78 53 79 6e 63 20 6d 65 74 68 6f 64 20 69 73   xSync method is
91b0: 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 0a 2a 2a   invoked on a.**
91c0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 64   database file d
91d0: 65 73 63 72 69 70 74 6f 72 2e 20 4f 72 2c 20 69  escriptor. Or, i
91e0: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
91f0: 6f 64 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  od is not invoke
9200: 64 20 0a 2a 2a 20 62 65 63 61 75 73 65 20 74 68  d .** because th
9210: 65 20 75 73 65 72 20 68 61 73 20 63 6f 6e 66 69  e user has confi
9220: 67 75 72 65 64 20 53 51 4c 69 74 65 20 77 69 74  gured SQLite wit
9230: 68 20 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 73 79  h .** [PRAGMA sy
9240: 6e 63 68 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47  nchronous | PRAG
9250: 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f  MA synchronous=O
9260: 46 46 5d 20 69 74 20 69 73 20 69 6e 76 6f 6b 65  FF] it is invoke
9270: 64 20 69 6e 20 70 6c 61 63 65 20 0a 2a 2a 20 6f  d in place .** o
9280: 66 20 74 68 65 20 78 53 79 6e 63 20 6d 65 74 68  f the xSync meth
9290: 6f 64 2e 20 49 6e 20 6d 6f 73 74 20 63 61 73 65  od. In most case
92a0: 73 2c 20 74 68 65 20 70 6f 69 6e 74 65 72 20 61  s, the pointer a
92b0: 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20 77  rgument passed w
92c0: 69 74 68 0a 2a 2a 20 74 68 69 73 20 66 69 6c 65  ith.** this file
92d0: 2d 63 6f 6e 74 72 6f 6c 20 69 73 20 4e 55 4c 4c  -control is NULL
92e0: 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
92f0: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9300: 69 73 20 62 65 69 6e 67 20 73 79 6e 63 65 64 0a  is being synced.
9310: 2a 2a 20 61 73 20 70 61 72 74 20 6f 66 20 61 20  ** as part of a 
9320: 6d 75 6c 74 69 2d 64 61 74 61 62 61 73 65 20 63  multi-database c
9330: 6f 6d 6d 69 74 2c 20 74 68 65 20 61 72 67 75 6d  ommit, the argum
9340: 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 20 61 20  ent points to a 
9350: 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
9360: 2a 20 73 74 72 69 6e 67 20 63 6f 6e 74 61 69 6e  * string contain
9370: 69 6e 67 20 74 68 65 20 74 72 61 6e 73 61 63 74  ing the transact
9380: 69 6f 6e 73 20 6d 61 73 74 65 72 2d 6a 6f 75 72  ions master-jour
9390: 6e 61 6c 20 66 69 6c 65 20 6e 61 6d 65 2e 20 56  nal file name. V
93a0: 46 53 65 73 20 74 68 61 74 20 0a 2a 2a 20 64 6f  FSes that .** do
93b0: 20 6e 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73   not need this s
93c0: 69 67 6e 61 6c 20 73 68 6f 75 6c 64 20 73 69 6c  ignal should sil
93d0: 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69  ently ignore thi
93e0: 73 20 6f 70 63 6f 64 65 2e 20 41 70 70 6c 69 63  s opcode. Applic
93f0: 61 74 69 6f 6e 73 20 0a 2a 2a 20 73 68 6f 75 6c  ations .** shoul
9400: 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69  d not call [sqli
9410: 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c  te3_file_control
9420: 28 29 5d 20 77 69 74 68 20 74 68 69 73 20 6f 70  ()] with this op
9430: 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f  code as doing so
9440: 20 6d 61 79 20 0a 2a 2a 20 64 69 73 72 75 70 74   may .** disrupt
9450: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
9460: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
9470: 64 20 56 46 53 65 73 20 74 68 61 74 20 64 6f 20  d VFSes that do 
9480: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
9490: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
94a0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
94b0: 41 53 45 54 57 4f 5d 5d 0a 2a 2a 20 54 68 65 20  ASETWO]].** The 
94c0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 4f  [SQLITE_FCNTL_CO
94d0: 4d 4d 49 54 5f 50 48 41 53 45 54 57 4f 5d 20 6f  MMIT_PHASETWO] o
94e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
94f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
9500: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 73   SQLite.** and s
9510: 65 6e 74 20 74 6f 20 74 68 65 20 56 46 53 20 61  ent to the VFS a
9520: 66 74 65 72 20 61 20 74 72 61 6e 73 61 63 74 69  fter a transacti
9530: 6f 6e 20 68 61 73 20 62 65 65 6e 20 63 6f 6d 6d  on has been comm
9540: 69 74 74 65 64 20 69 6d 6d 65 64 69 61 74 65 6c  itted immediatel
9550: 79 0a 2a 2a 20 62 75 74 20 62 65 66 6f 72 65 20  y.** but before 
9560: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
9570: 75 6e 6c 6f 63 6b 65 64 2e 20 56 46 53 65 73 20  unlocked. VFSes 
9580: 74 68 61 74 20 64 6f 20 6e 6f 74 20 6e 65 65 64  that do not need
9590: 20 74 68 69 73 20 73 69 67 6e 61 6c 0a 2a 2a 20   this signal.** 
95a0: 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74 6c 79 20  should silently 
95b0: 69 67 6e 6f 72 65 20 74 68 69 73 20 6f 70 63 6f  ignore this opco
95c0: 64 65 2e 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  de. Applications
95d0: 20 73 68 6f 75 6c 64 20 6e 6f 74 20 63 61 6c 6c   should not call
95e0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  .** [sqlite3_fil
95f0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 77 69 74  e_control()] wit
9600: 68 20 74 68 69 73 20 6f 70 63 6f 64 65 20 61 73  h this opcode as
9610: 20 64 6f 69 6e 67 20 73 6f 20 6d 61 79 20 64 69   doing so may di
9620: 73 72 75 70 74 20 74 68 65 20 0a 2a 2a 20 6f 70  srupt the .** op
9630: 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  eration of the s
9640: 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53 65 73  pecialized VFSes
9650: 20 74 68 61 74 20 64 6f 20 72 65 71 75 69 72 65   that do require
9660: 20 69 74 2e 20 20 0a 2a 2a 0a 2a 2a 20 3c 6c 69   it.  .**.** <li
9670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9680: 57 49 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 5d  WIN32_AV_RETRY]]
9690: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
96a0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
96b0: 52 45 54 52 59 5d 20 6f 70 63 6f 64 65 20 69 73  RETRY] opcode is
96c0: 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69 67 75   used to configu
96d0: 72 65 20 61 75 74 6f 6d 61 74 69 63 0a 2a 2a 20  re automatic.** 
96e0: 72 65 74 72 79 20 63 6f 75 6e 74 73 20 61 6e 64  retry counts and
96f0: 20 69 6e 74 65 72 76 61 6c 73 20 66 6f 72 20 63   intervals for c
9700: 65 72 74 61 69 6e 20 64 69 73 6b 20 49 2f 4f 20  ertain disk I/O 
9710: 6f 70 65 72 61 74 69 6f 6e 73 20 66 6f 72 20 74  operations for t
9720: 68 65 0a 2a 2a 20 77 69 6e 64 6f 77 73 20 5b 56  he.** windows [V
9730: 46 53 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  FS] in order to 
9740: 70 72 6f 76 69 64 65 20 72 6f 62 75 73 74 6e 65  provide robustne
9750: 73 73 20 69 6e 20 74 68 65 20 70 72 65 73 65 6e  ss in the presen
9760: 63 65 20 6f 66 0a 2a 2a 20 61 6e 74 69 2d 76 69  ce of.** anti-vi
9770: 72 75 73 20 70 72 6f 67 72 61 6d 73 2e 20 20 42  rus programs.  B
9780: 79 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 77  y default, the w
9790: 69 6e 64 6f 77 73 20 56 46 53 20 77 69 6c 6c 20  indows VFS will 
97a0: 72 65 74 72 79 20 66 69 6c 65 20 72 65 61 64 2c  retry file read,
97b0: 0a 2a 2a 20 66 69 6c 65 20 77 72 69 74 65 2c 20  .** file write, 
97c0: 61 6e 64 20 66 69 6c 65 20 64 65 6c 65 74 65 20  and file delete 
97d0: 6f 70 65 72 61 74 69 6f 6e 73 20 75 70 20 74 6f  operations up to
97e0: 20 31 30 20 74 69 6d 65 73 2c 20 77 69 74 68 20   10 times, with 
97f0: 61 20 64 65 6c 61 79 0a 2a 2a 20 6f 66 20 32 35  a delay.** of 25
9800: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 62 65   milliseconds be
9810: 66 6f 72 65 20 74 68 65 20 66 69 72 73 74 20 72  fore the first r
9820: 65 74 72 79 20 61 6e 64 20 77 69 74 68 20 74 68  etry and with th
9830: 65 20 64 65 6c 61 79 20 69 6e 63 72 65 61 73 69  e delay increasi
9840: 6e 67 0a 2a 2a 20 62 79 20 61 6e 20 61 64 64 69  ng.** by an addi
9850: 74 69 6f 6e 61 6c 20 32 35 20 6d 69 6c 6c 69 73  tional 25 millis
9860: 65 63 6f 6e 64 73 20 77 69 74 68 20 65 61 63 68  econds with each
9870: 20 73 75 62 73 65 71 75 65 6e 74 20 72 65 74 72   subsequent retr
9880: 79 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f  y.  This.** opco
9890: 64 65 20 61 6c 6c 6f 77 73 20 74 68 65 73 65 20  de allows these 
98a0: 74 77 6f 20 76 61 6c 75 65 73 20 28 31 30 20 72  two values (10 r
98b0: 65 74 72 69 65 73 20 61 6e 64 20 32 35 20 6d 69  etries and 25 mi
98c0: 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 64 65  lliseconds of de
98d0: 6c 61 79 29 0a 2a 2a 20 74 6f 20 62 65 20 61 64  lay).** to be ad
98e0: 6a 75 73 74 65 64 2e 20 20 54 68 65 20 76 61 6c  justed.  The val
98f0: 75 65 73 20 61 72 65 20 63 68 61 6e 67 65 64 20  ues are changed 
9900: 66 6f 72 20 61 6c 6c 20 64 61 74 61 62 61 73 65  for all database
9910: 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 20   connections.** 
9920: 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65 20  within the same 
9930: 70 72 6f 63 65 73 73 2e 20 20 54 68 65 20 61 72  process.  The ar
9940: 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e  gument is a poin
9950: 74 65 72 20 74 6f 20 61 6e 20 61 72 72 61 79 20  ter to an array 
9960: 6f 66 20 74 77 6f 0a 2a 2a 20 69 6e 74 65 67 65  of two.** intege
9970: 72 73 20 77 68 65 72 65 20 74 68 65 20 66 69 72  rs where the fir
9980: 73 74 20 69 6e 74 65 67 65 72 20 69 20 74 68 65  st integer i the
9990: 20 6e 65 77 20 72 65 74 72 79 20 63 6f 75 6e 74   new retry count
99a0: 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 0a   and the second.
99b0: 2a 2a 20 69 6e 74 65 67 65 72 20 69 73 20 74 68  ** integer is th
99c0: 65 20 64 65 6c 61 79 2e 20 20 49 66 20 65 69 74  e delay.  If eit
99d0: 68 65 72 20 69 6e 74 65 67 65 72 20 69 73 20 6e  her integer is n
99e0: 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68  egative, then th
99f0: 65 20 73 65 74 74 69 6e 67 0a 2a 2a 20 69 73 20  e setting.** is 
9a00: 6e 6f 74 20 63 68 61 6e 67 65 64 20 62 75 74 20  not changed but 
9a10: 69 6e 73 74 65 61 64 20 74 68 65 20 70 72 69 6f  instead the prio
9a20: 72 20 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20  r value of that 
9a30: 73 65 74 74 69 6e 67 20 69 73 20 77 72 69 74 74  setting is writt
9a40: 65 6e 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 61  en.** into the a
9a50: 72 72 61 79 20 65 6e 74 72 79 2c 20 61 6c 6c 6f  rray entry, allo
9a60: 77 69 6e 67 20 74 68 65 20 63 75 72 72 65 6e 74  wing the current
9a70: 20 72 65 74 72 79 20 73 65 74 74 69 6e 67 73 20   retry settings 
9a80: 74 6f 20 62 65 0a 2a 2a 20 69 6e 74 65 72 72 6f  to be.** interro
9a90: 67 61 74 65 64 2e 20 20 54 68 65 20 7a 44 62 4e  gated.  The zDbN
9aa0: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  ame parameter is
9ab0: 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20   ignored..**.** 
9ac0: 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e  <li>[[SQLITE_FCN
9ad0: 54 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 5d 5d  TL_PERSIST_WAL]]
9ae0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9af0: 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57  _FCNTL_PERSIST_W
9b00: 41 4c 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  AL] opcode is us
9b10: 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75 65  ed to set or que
9b20: 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69 73  ry the.** persis
9b30: 74 65 6e 74 20 5b 57 41 4c 20 7c 20 57 72 69 74  tent [WAL | Writ
9b40: 65 20 41 68 65 61 64 20 4c 6f 67 5d 20 73 65 74  e Ahead Log] set
9b50: 74 69 6e 67 2e 20 20 42 79 20 64 65 66 61 75 6c  ting.  By defaul
9b60: 74 2c 20 74 68 65 20 61 75 78 69 6c 69 61 72 79  t, the auxiliary
9b70: 0a 2a 2a 20 77 72 69 74 65 20 61 68 65 61 64 20  .** write ahead 
9b80: 6c 6f 67 20 61 6e 64 20 73 68 61 72 65 64 20 6d  log and shared m
9b90: 65 6d 6f 72 79 20 66 69 6c 65 73 20 75 73 65 64  emory files used
9ba0: 20 66 6f 72 20 74 72 61 6e 73 61 63 74 69 6f 6e   for transaction
9bb0: 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 61 72 65 20   control.** are 
9bc0: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
9bd0: 6c 65 74 65 64 20 77 68 65 6e 20 74 68 65 20 6c  leted when the l
9be0: 61 74 65 73 74 20 63 6f 6e 6e 65 63 74 69 6f 6e  atest connection
9bf0: 20 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65   to the database
9c00: 0a 2a 2a 20 63 6c 6f 73 65 73 2e 20 20 53 65 74  .** closes.  Set
9c10: 74 69 6e 67 20 70 65 72 73 69 73 74 65 6e 74 20  ting persistent 
9c20: 57 41 4c 20 6d 6f 64 65 20 63 61 75 73 65 73 20  WAL mode causes 
9c30: 74 68 6f 73 65 20 66 69 6c 65 73 20 74 6f 20 70  those files to p
9c40: 65 72 73 69 73 74 20 61 66 74 65 72 0a 2a 2a 20  ersist after.** 
9c50: 63 6c 6f 73 65 2e 20 20 50 65 72 73 69 73 74 69  close.  Persisti
9c60: 6e 67 20 74 68 65 20 66 69 6c 65 73 20 69 73 20  ng the files is 
9c70: 75 73 65 66 75 6c 20 77 68 65 6e 20 6f 74 68 65  useful when othe
9c80: 72 20 70 72 6f 63 65 73 73 65 73 20 74 68 61 74  r processes that
9c90: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 68 61 76 65 20   do not.** have 
9ca0: 77 72 69 74 65 20 70 65 72 6d 69 73 73 69 6f 6e  write permission
9cb0: 20 6f 6e 20 74 68 65 20 64 69 72 65 63 74 6f 72   on the director
9cc0: 79 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  y containing the
9cd0: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
9ce0: 61 6e 74 0a 2a 2a 20 74 6f 20 72 65 61 64 20 74  ant.** to read t
9cf0: 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
9d00: 2c 20 61 73 20 74 68 65 20 57 41 4c 20 61 6e 64  , as the WAL and
9d10: 20 73 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66   shared memory f
9d20: 69 6c 65 73 20 6d 75 73 74 20 65 78 69 73 74 0a  iles must exist.
9d30: 2a 2a 20 69 6e 20 6f 72 64 65 72 20 66 6f 72 20  ** in order for 
9d40: 74 68 65 20 64 61 74 61 62 61 73 65 20 74 6f 20  the database to 
9d50: 62 65 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  be readable.  Th
9d60: 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  e fourth paramet
9d70: 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  er to.** [sqlite
9d80: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
9d90: 5d 20 66 6f 72 20 74 68 69 73 20 6f 70 63 6f 64  ] for this opcod
9da0: 65 20 73 68 6f 75 6c 64 20 62 65 20 61 20 70 6f  e should be a po
9db0: 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65  inter to an inte
9dc0: 67 65 72 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74  ger..** That int
9dd0: 65 67 65 72 20 69 73 20 30 20 74 6f 20 64 69 73  eger is 0 to dis
9de0: 61 62 6c 65 20 70 65 72 73 69 73 74 65 6e 74 20  able persistent 
9df0: 57 41 4c 20 6d 6f 64 65 20 6f 72 20 31 20 74 6f  WAL mode or 1 to
9e00: 20 65 6e 61 62 6c 65 20 70 65 72 73 69 73 74 65   enable persiste
9e10: 6e 74 0a 2a 2a 20 57 41 4c 20 6d 6f 64 65 2e 20  nt.** WAL mode. 
9e20: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
9e30: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
9e40: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
9e50: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
9e60: 2a 20 57 41 4c 20 70 65 72 73 69 73 74 65 6e 63  * WAL persistenc
9e70: 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a 2a  e setting..**.**
9e80: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
9e90: 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56  NTL_POWERSAFE_OV
9ea0: 45 52 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68  ERWRITE]].** ^Th
9eb0: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
9ec0: 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52  POWERSAFE_OVERWR
9ed0: 49 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75  ITE] opcode is u
9ee0: 73 65 64 20 74 6f 20 73 65 74 20 6f 72 20 71 75  sed to set or qu
9ef0: 65 72 79 20 74 68 65 0a 2a 2a 20 70 65 72 73 69  ery the.** persi
9f00: 73 74 65 6e 74 20 22 70 6f 77 65 72 73 61 66 65  stent "powersafe
9f10: 2d 6f 76 65 72 77 72 69 74 65 22 20 6f 72 20 22  -overwrite" or "
9f20: 50 53 4f 57 22 20 73 65 74 74 69 6e 67 2e 20 20  PSOW" setting.  
9f30: 54 68 65 20 50 53 4f 57 20 73 65 74 74 69 6e 67  The PSOW setting
9f40: 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65 73 20 74  .** determines t
9f50: 68 65 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  he [SQLITE_IOCAP
9f60: 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57  _POWERSAFE_OVERW
9f70: 52 49 54 45 5d 20 62 69 74 20 6f 66 20 74 68 65  RITE] bit of the
9f80: 0a 2a 2a 20 78 44 65 76 69 63 65 43 68 61 72 61  .** xDeviceChara
9f90: 63 74 65 72 69 73 74 69 63 73 20 6d 65 74 68 6f  cteristics metho
9fa0: 64 73 2e 20 54 68 65 20 66 6f 75 72 74 68 20 70  ds. The fourth p
9fb0: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 5b  arameter to.** [
9fc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
9fd0: 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69 73  trol()] for this
9fe0: 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20 62   opcode should b
9ff0: 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  e a pointer to a
a000: 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54 68  n integer..** Th
a010: 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30 20  at integer is 0 
a020: 74 6f 20 64 69 73 61 62 6c 65 20 7a 65 72 6f 2d  to disable zero-
a030: 64 61 6d 61 67 65 20 6d 6f 64 65 20 6f 72 20 31  damage mode or 1
a040: 20 74 6f 20 65 6e 61 62 6c 65 20 7a 65 72 6f 2d   to enable zero-
a050: 64 61 6d 61 67 65 0a 2a 2a 20 6d 6f 64 65 2e 20  damage.** mode. 
a060: 20 49 66 20 74 68 65 20 69 6e 74 65 67 65 72 20   If the integer 
a070: 69 73 20 2d 31 2c 20 74 68 65 6e 20 69 74 20 69  is -1, then it i
a080: 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77 69  s overwritten wi
a090: 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  th the current.*
a0a0: 2a 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  * zero-damage mo
a0b0: 64 65 20 73 65 74 74 69 6e 67 2e 0a 2a 2a 0a 2a  de setting..**.*
a0c0: 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46  * <li>[[SQLITE_F
a0d0: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 5d 5d  CNTL_OVERWRITE]]
a0e0: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
a0f0: 5f 46 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45  _FCNTL_OVERWRITE
a100: 5d 20 6f 70 63 6f 64 65 20 69 73 20 69 6e 76 6f  ] opcode is invo
a110: 6b 65 64 20 62 79 20 53 51 4c 69 74 65 20 61 66  ked by SQLite af
a120: 74 65 72 20 6f 70 65 6e 69 6e 67 0a 2a 2a 20 61  ter opening.** a
a130: 20 77 72 69 74 65 20 74 72 61 6e 73 61 63 74 69   write transacti
a140: 6f 6e 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  on to indicate t
a150: 68 61 74 2c 20 75 6e 6c 65 73 73 20 69 74 20 69  hat, unless it i
a160: 73 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 66 6f  s rolled back fo
a170: 72 20 73 6f 6d 65 0a 2a 2a 20 72 65 61 73 6f 6e  r some.** reason
a180: 2c 20 74 68 65 20 65 6e 74 69 72 65 20 64 61 74  , the entire dat
a190: 61 62 61 73 65 20 66 69 6c 65 20 77 69 6c 6c 20  abase file will 
a1a0: 62 65 20 6f 76 65 72 77 72 69 74 74 65 6e 20 62  be overwritten b
a1b0: 79 20 74 68 65 20 63 75 72 72 65 6e 74 20 0a 2a  y the current .*
a1c0: 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 2e 20 54  * transaction. T
a1d0: 68 69 73 20 69 73 20 75 73 65 64 20 62 79 20 56  his is used by V
a1e0: 41 43 55 55 4d 20 6f 70 65 72 61 74 69 6f 6e 73  ACUUM operations
a1f0: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
a200: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a210: 4d 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ME]].** ^The [SQ
a220: 4c 49 54 45 5f 46 43 4e 54 4c 5f 56 46 53 4e 41  LITE_FCNTL_VFSNA
a230: 4d 45 5d 20 6f 70 63 6f 64 65 20 63 61 6e 20 62  ME] opcode can b
a240: 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
a250: 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 0a 2a 2a   the names of.**
a260: 20 61 6c 6c 20 5b 56 46 53 65 73 5d 20 69 6e 20   all [VFSes] in 
a270: 74 68 65 20 56 46 53 20 73 74 61 63 6b 2e 20 20  the VFS stack.  
a280: 54 68 65 20 6e 61 6d 65 73 20 61 72 65 20 6f 66  The names are of
a290: 20 61 6c 6c 20 56 46 53 20 73 68 69 6d 73 20 61   all VFS shims a
a2a0: 6e 64 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  nd the.** final 
a2b0: 62 6f 74 74 6f 6d 2d 6c 65 76 65 6c 20 56 46 53  bottom-level VFS
a2c0: 20 61 72 65 20 77 72 69 74 74 65 6e 20 69 6e 74   are written int
a2d0: 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
a2e0: 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c 69  d from .** [sqli
a2f0: 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 61 6e  te3_malloc()] an
a300: 64 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  d the result is 
a310: 73 74 6f 72 65 64 20 69 6e 20 74 68 65 20 63 68  stored in the ch
a320: 61 72 2a 20 76 61 72 69 61 62 6c 65 0a 2a 2a 20  ar* variable.** 
a330: 74 68 61 74 20 74 68 65 20 66 6f 75 72 74 68 20  that the fourth 
a340: 70 61 72 61 6d 65 74 65 72 20 6f 66 20 5b 73 71  parameter of [sq
a350: 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72  lite3_file_contr
a360: 6f 6c 28 29 5d 20 70 6f 69 6e 74 73 20 74 6f 2e  ol()] points to.
a370: 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 65 72 20 69  .** The caller i
a380: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
a390: 72 20 66 72 65 65 69 6e 67 20 74 68 65 20 6d 65  r freeing the me
a3a0: 6d 6f 72 79 20 77 68 65 6e 20 64 6f 6e 65 2e 20  mory when done. 
a3b0: 20 41 73 20 77 69 74 68 0a 2a 2a 20 61 6c 6c 20   As with.** all 
a3c0: 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20 61 63 74  file-control act
a3d0: 69 6f 6e 73 2c 20 74 68 65 72 65 20 69 73 20 6e  ions, there is n
a3e0: 6f 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74  o guarantee that
a3f0: 20 74 68 69 73 20 77 69 6c 6c 20 61 63 74 75 61   this will actua
a400: 6c 6c 79 0a 2a 2a 20 64 6f 20 61 6e 79 74 68 69  lly.** do anythi
a410: 6e 67 2e 20 20 43 61 6c 6c 65 72 73 20 73 68 6f  ng.  Callers sho
a420: 75 6c 64 20 69 6e 69 74 69 61 6c 69 7a 65 20 74  uld initialize t
a430: 68 65 20 63 68 61 72 2a 20 76 61 72 69 61 62 6c  he char* variabl
a440: 65 20 74 6f 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70  e to a NULL.** p
a450: 6f 69 6e 74 65 72 20 69 6e 20 63 61 73 65 20 74  ointer in case t
a460: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
a470: 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e   is not implemen
a480: 74 65 64 2e 20 20 54 68 69 73 20 66 69 6c 65 2d  ted.  This file-
a490: 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 69 73 20 69 6e  control.** is in
a4a0: 74 65 6e 64 65 64 20 66 6f 72 20 64 69 61 67 6e  tended for diagn
a4b0: 6f 73 74 69 63 20 75 73 65 20 6f 6e 6c 79 2e 0a  ostic use only..
a4c0: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
a4d0: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
a4e0: 5d 0a 2a 2a 20 5e 57 68 65 6e 65 76 65 72 20 61  ].** ^Whenever a
a4f0: 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65 6d   [PRAGMA] statem
a500: 65 6e 74 20 69 73 20 70 61 72 73 65 64 2c 20 61  ent is parsed, a
a510: 6e 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  n [SQLITE_FCNTL_
a520: 50 52 41 47 4d 41 5d 20 0a 2a 2a 20 66 69 6c 65  PRAGMA] .** file
a530: 20 63 6f 6e 74 72 6f 6c 20 69 73 20 73 65 6e 74   control is sent
a540: 20 74 6f 20 74 68 65 20 6f 70 65 6e 20 5b 73 71   to the open [sq
a550: 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65  lite3_file] obje
a560: 63 74 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  ct corresponding
a570: 0a 2a 2a 20 74 6f 20 74 68 65 20 64 61 74 61 62  .** to the datab
a580: 61 73 65 20 66 69 6c 65 20 74 6f 20 77 68 69 63  ase file to whic
a590: 68 20 74 68 65 20 70 72 61 67 6d 61 20 73 74 61  h the pragma sta
a5a0: 74 65 6d 65 6e 74 20 72 65 66 65 72 73 2e 20 5e  tement refers. ^
a5b0: 54 68 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  The argument.** 
a5c0: 74 6f 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46  to the [SQLITE_F
a5d0: 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c  CNTL_PRAGMA] fil
a5e0: 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 61 6e 20  e control is an 
a5f0: 61 72 72 61 79 20 6f 66 0a 2a 2a 20 70 6f 69 6e  array of.** poin
a600: 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20  ters to strings 
a610: 28 63 68 61 72 2a 2a 29 20 69 6e 20 77 68 69 63  (char**) in whic
a620: 68 20 74 68 65 20 73 65 63 6f 6e 64 20 65 6c 65  h the second ele
a630: 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 72 72 61  ment of the arra
a640: 79 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65  y.** is the name
a650: 20 6f 66 20 74 68 65 20 70 72 61 67 6d 61 20 61   of the pragma a
a660: 6e 64 20 74 68 65 20 74 68 69 72 64 20 65 6c 65  nd the third ele
a670: 6d 65 6e 74 20 69 73 20 74 68 65 20 61 72 67 75  ment is the argu
a680: 6d 65 6e 74 20 74 6f 20 74 68 65 0a 2a 2a 20 70  ment to the.** p
a690: 72 61 67 6d 61 20 6f 72 20 4e 55 4c 4c 20 69 66  ragma or NULL if
a6a0: 20 74 68 65 20 70 72 61 67 6d 61 20 68 61 73 20   the pragma has 
a6b0: 6e 6f 20 61 72 67 75 6d 65 6e 74 2e 20 20 5e 54  no argument.  ^T
a6c0: 68 65 20 68 61 6e 64 6c 65 72 20 66 6f 72 20 61  he handler for a
a6d0: 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  n.** [SQLITE_FCN
a6e0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
a6f0: 63 6f 6e 74 72 6f 6c 20 63 61 6e 20 6f 70 74 69  control can opti
a700: 6f 6e 61 6c 6c 79 20 6d 61 6b 65 20 74 68 65 20  onally make the 
a710: 66 69 72 73 74 20 65 6c 65 6d 65 6e 74 0a 2a 2a  first element.**
a720: 20 6f 66 20 74 68 65 20 63 68 61 72 2a 2a 20 61   of the char** a
a730: 72 67 75 6d 65 6e 74 20 70 6f 69 6e 74 20 74 6f  rgument point to
a740: 20 61 20 73 74 72 69 6e 67 20 6f 62 74 61 69 6e   a string obtain
a750: 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
a760: 5f 6d 70 72 69 6e 74 66 28 29 5d 0a 2a 2a 20 6f  _mprintf()].** o
a770: 72 20 74 68 65 20 65 71 75 69 76 61 6c 65 6e 74  r the equivalent
a780: 20 61 6e 64 20 74 68 61 74 20 73 74 72 69 6e 67   and that string
a790: 20 77 69 6c 6c 20 62 65 63 6f 6d 65 20 74 68 65   will become the
a7a0: 20 72 65 73 75 6c 74 20 6f 66 20 74 68 65 20 70   result of the p
a7b0: 72 61 67 6d 61 20 6f 72 0a 2a 2a 20 74 68 65 20  ragma or.** the 
a7c0: 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 69 66  error message if
a7d0: 20 74 68 65 20 70 72 61 67 6d 61 20 66 61 69 6c   the pragma fail
a7e0: 73 2e 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  s. ^If the.** [S
a7f0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
a800: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
a810: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
a820: 5f 4e 4f 54 46 4f 55 4e 44 5d 2c 20 74 68 65 6e  _NOTFOUND], then
a830: 20 6e 6f 72 6d 61 6c 20 0a 2a 2a 20 5b 50 52 41   normal .** [PRA
a840: 47 4d 41 5d 20 70 72 6f 63 65 73 73 69 6e 67 20  GMA] processing 
a850: 63 6f 6e 74 69 6e 75 65 73 2e 20 20 5e 49 66 20  continues.  ^If 
a860: 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  the [SQLITE_FCNT
a870: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
a880: 65 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e  e control return
a890: 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
a8a0: 68 65 6e 20 74 68 65 20 70 61 72 73 65 72 20 61  hen the parser a
a8b0: 73 73 75 6d 65 73 20 74 68 61 74 20 74 68 65 0a  ssumes that the.
a8c0: 2a 2a 20 56 46 53 20 68 61 73 20 68 61 6e 64 6c  ** VFS has handl
a8d0: 65 64 20 74 68 65 20 50 52 41 47 4d 41 20 69 74  ed the PRAGMA it
a8e0: 73 65 6c 66 20 61 6e 64 20 74 68 65 20 70 61 72  self and the par
a8f0: 73 65 72 20 67 65 6e 65 72 61 74 65 73 20 61 20  ser generates a 
a900: 6e 6f 2d 6f 70 0a 2a 2a 20 70 72 65 70 61 72 65  no-op.** prepare
a910: 64 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 49  d statement.  ^I
a920: 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  f the [SQLITE_FC
a930: 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65  NTL_PRAGMA] file
a940: 20 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73   control returns
a950: 0a 2a 2a 20 61 6e 79 20 72 65 73 75 6c 74 20 63  .** any result c
a960: 6f 64 65 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  ode other than [
a970: 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 5b 53  SQLITE_OK] or [S
a980: 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 2c  QLITE_NOTFOUND],
a990: 20 74 68 61 74 20 6d 65 61 6e 73 0a 2a 2a 20 74   that means.** t
a9a0: 68 61 74 20 74 68 65 20 56 46 53 20 65 6e 63 6f  hat the VFS enco
a9b0: 75 6e 74 65 72 65 64 20 61 6e 20 65 72 72 6f 72  untered an error
a9c0: 20 77 68 69 6c 65 20 68 61 6e 64 6c 69 6e 67 20   while handling 
a9d0: 74 68 65 20 5b 50 52 41 47 4d 41 5d 20 61 6e 64  the [PRAGMA] and
a9e0: 20 74 68 65 0a 2a 2a 20 63 6f 6d 70 69 6c 61 74   the.** compilat
a9f0: 69 6f 6e 20 6f 66 20 74 68 65 20 50 52 41 47 4d  ion of the PRAGM
aa00: 41 20 66 61 69 6c 73 20 77 69 74 68 20 61 6e 20  A fails with an 
aa10: 65 72 72 6f 72 2e 20 20 5e 54 68 65 20 5b 53 51  error.  ^The [SQ
aa20: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
aa30: 41 5d 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72  A].** file contr
aa40: 6f 6c 20 6f 63 63 75 72 73 20 61 74 20 74 68 65  ol occurs at the
aa50: 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 70 72   beginning of pr
aa60: 61 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 61  agma statement a
aa70: 6e 61 6c 79 73 69 73 20 61 6e 64 20 73 6f 0a 2a  nalysis and so.*
aa80: 2a 20 69 74 20 69 73 20 61 62 6c 65 20 74 6f 20  * it is able to 
aa90: 6f 76 65 72 72 69 64 65 20 62 75 69 6c 74 2d 69  override built-i
aaa0: 6e 20 5b 50 52 41 47 4d 41 5d 20 73 74 61 74 65  n [PRAGMA] state
aab0: 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  ments..**.** <li
aac0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
aad0: 42 55 53 59 48 41 4e 44 4c 45 52 5d 5d 0a 2a 2a  BUSYHANDLER]].**
aae0: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43   ^The [SQLITE_FC
aaf0: 4e 54 4c 5f 42 55 53 59 48 41 4e 44 4c 45 52 5d  NTL_BUSYHANDLER]
ab00: 0a 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  .** file-control
ab10: 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b 65 64 20   may be invoked 
ab20: 62 79 20 53 51 4c 69 74 65 20 6f 6e 20 74 68 65  by SQLite on the
ab30: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 68   database file h
ab40: 61 6e 64 6c 65 0a 2a 2a 20 73 68 6f 72 74 6c 79  andle.** shortly
ab50: 20 61 66 74 65 72 20 69 74 20 69 73 20 6f 70 65   after it is ope
ab60: 6e 65 64 20 69 6e 20 6f 72 64 65 72 20 74 6f 20  ned in order to 
ab70: 70 72 6f 76 69 64 65 20 61 20 63 75 73 74 6f 6d  provide a custom
ab80: 20 56 46 53 20 77 69 74 68 20 61 63 63 65 73 73   VFS with access
ab90: 0a 2a 2a 20 74 6f 20 74 68 65 20 63 6f 6e 6e 65  .** to the conne
aba0: 63 74 69 6f 6e 73 20 62 75 73 79 2d 68 61 6e 64  ctions busy-hand
abb0: 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 54 68  ler callback. Th
abc0: 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 66  e argument is of
abd0: 20 74 79 70 65 20 28 76 6f 69 64 20 2a 2a 29 0a   type (void **).
abe0: 2a 2a 20 2d 20 61 6e 20 61 72 72 61 79 20 6f 66  ** - an array of
abf0: 20 74 77 6f 20 28 76 6f 69 64 20 2a 29 20 76 61   two (void *) va
ac00: 6c 75 65 73 2e 20 54 68 65 20 66 69 72 73 74 20  lues. The first 
ac10: 28 76 6f 69 64 20 2a 29 20 61 63 74 75 61 6c 6c  (void *) actuall
ac20: 79 20 70 6f 69 6e 74 73 0a 2a 2a 20 74 6f 20 61  y points.** to a
ac30: 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 79 70   function of typ
ac40: 65 20 28 69 6e 74 20 28 2a 29 28 76 6f 69 64 20  e (int (*)(void 
ac50: 2a 29 29 2e 20 49 6e 20 6f 72 64 65 72 20 74 6f  *)). In order to
ac60: 20 69 6e 76 6f 6b 65 20 74 68 65 20 63 6f 6e 6e   invoke the conn
ac70: 65 63 74 69 6f 6e 73 0a 2a 2a 20 62 75 73 79 2d  ections.** busy-
ac80: 68 61 6e 64 6c 65 72 2c 20 74 68 69 73 20 66 75  handler, this fu
ac90: 6e 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 62 65  nction should be
aca0: 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74 68   invoked with th
acb0: 65 20 73 65 63 6f 6e 64 20 28 76 6f 69 64 20 2a  e second (void *
acc0: 29 20 69 6e 0a 2a 2a 20 74 68 65 20 61 72 72 61  ) in.** the arra
acd0: 79 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 61 72  y as the only ar
ace0: 67 75 6d 65 6e 74 2e 20 49 66 20 69 74 20 72 65  gument. If it re
acf0: 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  turns non-zero, 
ad00: 74 68 65 6e 20 74 68 65 20 6f 70 65 72 61 74 69  then the operati
ad10: 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20  on.** should be 
ad20: 72 65 74 72 69 65 64 2e 20 49 66 20 69 74 20 72  retried. If it r
ad30: 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74 68 65  eturns zero, the
ad40: 20 63 75 73 74 6f 6d 20 56 46 53 20 73 68 6f 75   custom VFS shou
ad50: 6c 64 20 61 62 61 6e 64 6f 6e 20 74 68 65 0a 2a  ld abandon the.*
ad60: 2a 20 63 75 72 72 65 6e 74 20 6f 70 65 72 61 74  * current operat
ad70: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b  ion..**.** <li>[
ad80: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45  [SQLITE_FCNTL_TE
ad90: 4d 50 46 49 4c 45 4e 41 4d 45 5d 5d 0a 2a 2a 20  MPFILENAME]].** 
ada0: 5e 41 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e  ^Application can
adb0: 20 69 6e 76 6f 6b 65 20 74 68 65 20 5b 53 51 4c   invoke the [SQL
adc0: 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50 46 49  ITE_FCNTL_TEMPFI
add0: 4c 45 4e 41 4d 45 5d 20 66 69 6c 65 2d 63 6f 6e  LENAME] file-con
ade0: 74 72 6f 6c 0a 2a 2a 20 74 6f 20 68 61 76 65 20  trol.** to have 
adf0: 53 51 4c 69 74 65 20 67 65 6e 65 72 61 74 65 20  SQLite generate 
ae00: 61 0a 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66  a.** temporary f
ae10: 69 6c 65 6e 61 6d 65 20 75 73 69 6e 67 20 74 68  ilename using th
ae20: 65 20 73 61 6d 65 20 61 6c 67 6f 72 69 74 68 6d  e same algorithm
ae30: 20 74 68 61 74 20 69 73 20 66 6f 6c 6c 6f 77 65   that is followe
ae40: 64 20 74 6f 20 67 65 6e 65 72 61 74 65 0a 2a 2a  d to generate.**
ae50: 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 6e   temporary filen
ae60: 61 6d 65 73 20 66 6f 72 20 54 45 4d 50 20 74 61  ames for TEMP ta
ae70: 62 6c 65 73 20 61 6e 64 20 6f 74 68 65 72 20 69  bles and other i
ae80: 6e 74 65 72 6e 61 6c 20 75 73 65 73 2e 20 20 54  nternal uses.  T
ae90: 68 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 73  he.** argument s
aea0: 68 6f 75 6c 64 20 62 65 20 61 20 63 68 61 72 2a  hould be a char*
aeb0: 2a 20 77 68 69 63 68 20 77 69 6c 6c 20 62 65 20  * which will be 
aec0: 66 69 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20  filled with the 
aed0: 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 72 69 74  filename.** writ
aee0: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
aef0: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
af00: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
af10: 2e 20 20 54 68 65 20 63 61 6c 6c 65 72 20 73 68  .  The caller sh
af20: 6f 75 6c 64 0a 2a 2a 20 69 6e 76 6f 6b 65 20 5b  ould.** invoke [
af30: 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
af40: 6f 6e 20 74 68 65 20 72 65 73 75 6c 74 20 74 6f  on the result to
af50: 20 61 76 6f 69 64 20 61 20 6d 65 6d 6f 72 79 20   avoid a memory 
af60: 6c 65 61 6b 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  leak..**.** <li>
af70: 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d  [[SQLITE_FCNTL_M
af80: 4d 41 50 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68  MAP_SIZE]].** Th
af90: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
afa0: 4d 4d 41 50 5f 53 49 5a 45 5d 20 66 69 6c 65 20  MMAP_SIZE] file 
afb0: 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73 65 64 20  control is used 
afc0: 74 6f 20 71 75 65 72 79 20 6f 72 20 73 65 74 20  to query or set 
afd0: 74 68 65 0a 2a 2a 20 6d 61 78 69 6d 75 6d 20 6e  the.** maximum n
afe0: 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 74  umber of bytes t
aff0: 68 61 74 20 77 69 6c 6c 20 62 65 20 75 73 65 64  hat will be used
b000: 20 66 6f 72 20 6d 65 6d 6f 72 79 2d 6d 61 70 70   for memory-mapp
b010: 65 64 20 49 2f 4f 2e 0a 2a 2a 20 54 68 65 20 61  ed I/O..** The a
b020: 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
b030: 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 75 65 20  nter to a value 
b040: 6f 66 20 74 79 70 65 20 73 71 6c 69 74 65 33 5f  of type sqlite3_
b050: 69 6e 74 36 34 20 74 68 61 74 0a 2a 2a 20 69 73  int64 that.** is
b060: 20 61 6e 20 61 64 76 69 73 6f 72 79 20 6d 61 78   an advisory max
b070: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62  imum number of b
b080: 79 74 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65  ytes in the file
b090: 20 74 6f 20 6d 65 6d 6f 72 79 20 6d 61 70 2e 20   to memory map. 
b0a0: 20 54 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20   The.** pointer 
b0b0: 69 73 20 6f 76 65 72 77 72 69 74 74 65 6e 20 77  is overwritten w
b0c0: 69 74 68 20 74 68 65 20 6f 6c 64 20 76 61 6c 75  ith the old valu
b0d0: 65 2e 20 20 54 68 65 20 6c 69 6d 69 74 20 69 73  e.  The limit is
b0e0: 20 6e 6f 74 20 63 68 61 6e 67 65 64 20 69 66 0a   not changed if.
b0f0: 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f 72 69  ** the value ori
b100: 67 69 6e 61 6c 6c 79 20 70 6f 69 6e 74 65 64 20  ginally pointed 
b110: 74 6f 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  to is negative, 
b120: 61 6e 64 20 73 6f 20 74 68 65 20 63 75 72 72 65  and so the curre
b130: 6e 74 20 6c 69 6d 69 74 20 0a 2a 2a 20 63 61 6e  nt limit .** can
b140: 20 62 65 20 71 75 65 72 69 65 64 20 62 79 20 70   be queried by p
b150: 61 73 73 69 6e 67 20 69 6e 20 61 20 70 6f 69 6e  assing in a poin
b160: 74 65 72 20 74 6f 20 61 20 6e 65 67 61 74 69 76  ter to a negativ
b170: 65 20 6e 75 6d 62 65 72 2e 20 20 54 68 69 73 0a  e number.  This.
b180: 2a 2a 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 20  ** file-control 
b190: 69 73 20 75 73 65 64 20 69 6e 74 65 72 6e 61 6c  is used internal
b1a0: 6c 79 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ly to implement 
b1b0: 5b 50 52 41 47 4d 41 20 6d 6d 61 70 5f 73 69 7a  [PRAGMA mmap_siz
b1c0: 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b  e]..**.** <li>[[
b1d0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41  SQLITE_FCNTL_TRA
b1e0: 43 45 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  CE]].** The [SQL
b1f0: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 5d  ITE_FCNTL_TRACE]
b200: 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 70 72   file control pr
b210: 6f 76 69 64 65 73 20 61 64 76 69 73 6f 72 79 20  ovides advisory 
b220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 74  information.** t
b230: 6f 20 74 68 65 20 56 46 53 20 61 62 6f 75 74 20  o the VFS about 
b240: 77 68 61 74 20 74 68 65 20 68 69 67 68 65 72 20  what the higher 
b250: 6c 61 79 65 72 73 20 6f 66 20 74 68 65 20 53 51  layers of the SQ
b260: 4c 69 74 65 20 73 74 61 63 6b 20 61 72 65 20 64  Lite stack are d
b270: 6f 69 6e 67 2e 0a 2a 2a 20 54 68 69 73 20 66 69  oing..** This fi
b280: 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 73 20 75 73  le control is us
b290: 65 64 20 62 79 20 73 6f 6d 65 20 56 46 53 20 61  ed by some VFS a
b2a0: 63 74 69 76 69 74 79 20 74 72 61 63 69 6e 67 20  ctivity tracing 
b2b0: 5b 73 68 69 6d 73 5d 2e 0a 2a 2a 20 54 68 65 20  [shims]..** The 
b2c0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 7a 65  argument is a ze
b2d0: 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
b2e0: 72 69 6e 67 2e 20 20 48 69 67 68 65 72 20 6c 61  ring.  Higher la
b2f0: 79 65 72 73 20 69 6e 20 74 68 65 0a 2a 2a 20 53  yers in the.** S
b300: 51 4c 69 74 65 20 73 74 61 63 6b 20 6d 61 79 20  QLite stack may 
b310: 67 65 6e 65 72 61 74 65 20 69 6e 73 74 61 6e 63  generate instanc
b320: 65 73 20 6f 66 20 74 68 69 73 20 66 69 6c 65 20  es of this file 
b330: 63 6f 6e 74 72 6f 6c 20 69 66 0a 2a 2a 20 74 68  control if.** th
b340: 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 46 43  e [SQLITE_USE_FC
b350: 4e 54 4c 5f 54 52 41 43 45 5d 20 63 6f 6d 70 69  NTL_TRACE] compi
b360: 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69  le-time option i
b370: 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a  s enabled..**.**
b380: 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43   <li>[[SQLITE_FC
b390: 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 5d 0a  NTL_HAS_MOVED]].
b3a0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
b3b0: 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56 45 44 5d 20  CNTL_HAS_MOVED] 
b3c0: 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 69 6e 74  file control int
b3d0: 65 72 70 72 65 74 73 20 69 74 73 20 61 72 67 75  erprets its argu
b3e0: 6d 65 6e 74 20 61 73 20 61 0a 2a 2a 20 70 6f 69  ment as a.** poi
b3f0: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67  nter to an integ
b400: 65 72 20 61 6e 64 20 69 74 20 77 72 69 74 65 73  er and it writes
b410: 20 61 20 62 6f 6f 6c 65 61 6e 20 69 6e 74 6f 20   a boolean into 
b420: 74 68 61 74 20 69 6e 74 65 67 65 72 20 64 65 70  that integer dep
b430: 65 6e 64 69 6e 67 0a 2a 2a 20 6f 6e 20 77 68 65  ending.** on whe
b440: 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
b450: 66 69 6c 65 20 68 61 73 20 62 65 65 6e 20 72 65  file has been re
b460: 6e 61 6d 65 64 2c 20 6d 6f 76 65 64 2c 20 6f 72  named, moved, or
b470: 20 64 65 6c 65 74 65 64 20 73 69 6e 63 65 20 69   deleted since i
b480: 74 0a 2a 2a 20 77 61 73 20 66 69 72 73 74 20 6f  t.** was first o
b490: 70 65 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69  pened..**.** <li
b4a0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
b4b0: 57 49 4e 33 32 5f 53 45 54 5f 48 41 4e 44 4c 45  WIN32_SET_HANDLE
b4c0: 5d 5d 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54  ]].** The [SQLIT
b4d0: 45 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45  E_FCNTL_WIN32_SE
b4e0: 54 5f 48 41 4e 44 4c 45 5d 20 6f 70 63 6f 64 65  T_HANDLE] opcode
b4f0: 20 69 73 20 75 73 65 64 20 66 6f 72 20 64 65 62   is used for deb
b500: 75 67 67 69 6e 67 2e 20 20 54 68 69 73 0a 2a 2a  ugging.  This.**
b510: 20 6f 70 63 6f 64 65 20 63 61 75 73 65 73 20 74   opcode causes t
b520: 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20  he xFileControl 
b530: 6d 65 74 68 6f 64 20 74 6f 20 73 77 61 70 20 74  method to swap t
b540: 68 65 20 66 69 6c 65 20 68 61 6e 64 6c 65 20 77  he file handle w
b550: 69 74 68 20 74 68 65 20 6f 6e 65 0a 2a 2a 20 70  ith the one.** p
b560: 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
b570: 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 2e 20   pArg argument. 
b580: 20 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79   This capability
b590: 20 69 73 20 75 73 65 64 20 64 75 72 69 6e 67 20   is used during 
b5a0: 74 65 73 74 69 6e 67 0a 2a 2a 20 61 6e 64 20 6f  testing.** and o
b5b0: 6e 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20  nly needs to be 
b5c0: 73 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53  supported when S
b5d0: 51 4c 49 54 45 5f 54 45 53 54 20 69 73 20 64 65  QLITE_TEST is de
b5e0: 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 2f 75  fined..**.** </u
b5f0: 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  l>.*/.#define SQ
b600: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53  LITE_FCNTL_LOCKS
b610: 54 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20  TATE            
b620: 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c     1.#define SQL
b630: 49 54 45 5f 47 45 54 5f 4c 4f 43 4b 50 52 4f 58  ITE_GET_LOCKPROX
b640: 59 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20  YFILE           
b650: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
b660: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
b670: 46 49 4c 45 20 20 20 20 20 20 20 20 20 20 20 20  FILE            
b680: 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   3.#define SQLIT
b690: 45 5f 4c 41 53 54 5f 45 52 52 4e 4f 20 20 20 20  E_LAST_ERRNO    
b6a0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b6b0: 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  4.#define SQLITE
b6c0: 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54  _FCNTL_SIZE_HINT
b6d0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35                 5
b6e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b6f0: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
b700: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36 0a                6.
b710: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
b720: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
b730: 52 20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23  R            7.#
b740: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
b750: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
b760: 20 20 20 20 20 20 20 20 20 20 20 20 38 0a 23 64              8.#d
b770: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
b780: 54 4c 5f 57 49 4e 33 32 5f 41 56 5f 52 45 54 52  TL_WIN32_AV_RETR
b790: 59 20 20 20 20 20 20 20 20 20 20 39 0a 23 64 65  Y          9.#de
b7a0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
b7b0: 4c 5f 50 45 52 53 49 53 54 5f 57 41 4c 20 20 20  L_PERSIST_WAL   
b7c0: 20 20 20 20 20 20 20 20 20 31 30 0a 23 64 65 66           10.#def
b7d0: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
b7e0: 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 20 20  _OVERWRITE      
b7f0: 20 20 20 20 20 20 20 20 31 31 0a 23 64 65 66 69          11.#defi
b800: 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  ne SQLITE_FCNTL_
b810: 56 46 53 4e 41 4d 45 20 20 20 20 20 20 20 20 20  VFSNAME         
b820: 20 20 20 20 20 20 20 31 32 0a 23 64 65 66 69 6e         12.#defin
b830: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50  e SQLITE_FCNTL_P
b840: 4f 57 45 52 53 41 46 45 5f 4f 56 45 52 57 52 49  OWERSAFE_OVERWRI
b850: 54 45 20 20 20 20 31 33 0a 23 64 65 66 69 6e 65  TE    13.#define
b860: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52   SQLITE_FCNTL_PR
b870: 41 47 4d 41 20 20 20 20 20 20 20 20 20 20 20 20  AGMA            
b880: 20 20 20 20 20 31 34 0a 23 64 65 66 69 6e 65 20       14.#define 
b890: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 42 55 53  SQLITE_FCNTL_BUS
b8a0: 59 48 41 4e 44 4c 45 52 20 20 20 20 20 20 20 20  YHANDLER        
b8b0: 20 20 20 20 31 35 0a 23 64 65 66 69 6e 65 20 53      15.#define S
b8c0: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 54 45 4d 50  QLITE_FCNTL_TEMP
b8d0: 46 49 4c 45 4e 41 4d 45 20 20 20 20 20 20 20 20  FILENAME        
b8e0: 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20 53 51     16.#define SQ
b8f0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f  LITE_FCNTL_MMAP_
b900: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
b910: 20 20 31 38 0a 23 64 65 66 69 6e 65 20 53 51 4c    18.#define SQL
b920: 49 54 45 5f 46 43 4e 54 4c 5f 54 52 41 43 45 20  ITE_FCNTL_TRACE 
b930: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
b940: 20 31 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   19.#define SQLI
b950: 54 45 5f 46 43 4e 54 4c 5f 48 41 53 5f 4d 4f 56  TE_FCNTL_HAS_MOV
b960: 45 44 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ED              
b970: 32 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  20.#define SQLIT
b980: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 20 20 20 20  E_FCNTL_SYNC    
b990: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
b9a0: 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  1.#define SQLITE
b9b0: 5f 46 43 4e 54 4c 5f 43 4f 4d 4d 49 54 5f 50 48  _FCNTL_COMMIT_PH
b9c0: 41 53 45 54 57 4f 20 20 20 20 20 20 20 20 32 32  ASETWO        22
b9d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
b9e0: 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 53 45 54 5f  FCNTL_WIN32_SET_
b9f0: 48 41 4e 44 4c 45 20 20 20 20 20 20 20 32 33 0a  HANDLE       23.
ba00: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
ba10: 20 4d 75 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a   Mutex Handle.**
ba20: 0a 2a 2a 20 54 68 65 20 6d 75 74 65 78 20 6d 6f  .** The mutex mo
ba30: 64 75 6c 65 20 77 69 74 68 69 6e 20 53 51 4c 69  dule within SQLi
ba40: 74 65 20 64 65 66 69 6e 65 73 20 5b 73 71 6c 69  te defines [sqli
ba50: 74 65 33 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65  te3_mutex] to be
ba60: 20 61 6e 0a 2a 2a 20 61 62 73 74 72 61 63 74 20   an.** abstract 
ba70: 74 79 70 65 20 66 6f 72 20 61 20 6d 75 74 65 78  type for a mutex
ba80: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 53 51   object.  The SQ
ba90: 4c 69 74 65 20 63 6f 72 65 20 6e 65 76 65 72 20  Lite core never 
baa0: 6c 6f 6f 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20  looks.** at the 
bab0: 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65 73 65  internal represe
bac0: 6e 74 61 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73  ntation of an [s
bad0: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20  qlite3_mutex].  
bae0: 49 74 20 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73  It only.** deals
baf0: 20 77 69 74 68 20 70 6f 69 6e 74 65 72 73 20 74   with pointers t
bb00: 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  o the [sqlite3_m
bb10: 75 74 65 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  utex] object..**
bb20: 0a 2a 2a 20 4d 75 74 65 78 65 73 20 61 72 65 20  .** Mutexes are 
bb30: 63 72 65 61 74 65 64 20 75 73 69 6e 67 20 5b 73  created using [s
bb40: 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c  qlite3_mutex_all
bb50: 6f 63 28 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65  oc()]..*/.typede
bb60: 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33  f struct sqlite3
bb70: 5f 6d 75 74 65 78 20 73 71 6c 69 74 65 33 5f 6d  _mutex sqlite3_m
bb80: 75 74 65 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  utex;../*.** CAP
bb90: 49 33 52 45 46 3a 20 4f 53 20 49 6e 74 65 72 66  I3REF: OS Interf
bba0: 61 63 65 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ace Object.**.**
bbb0: 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   An instance of 
bbc0: 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66 73 20  the sqlite3_vfs 
bbd0: 6f 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74  object defines t
bbe0: 68 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74  he interface bet
bbf0: 77 65 65 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69  ween.** the SQLi
bc00: 74 65 20 63 6f 72 65 20 61 6e 64 20 74 68 65 20  te core and the 
bc10: 75 6e 64 65 72 6c 79 69 6e 67 20 6f 70 65 72 61  underlying opera
bc20: 74 69 6e 67 20 73 79 73 74 65 6d 2e 20 20 54 68  ting system.  Th
bc30: 65 20 22 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68  e "vfs".** in th
bc40: 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 6f 62  e name of the ob
bc50: 6a 65 63 74 20 73 74 61 6e 64 73 20 66 6f 72 20  ject stands for 
bc60: 22 76 69 72 74 75 61 6c 20 66 69 6c 65 20 73 79  "virtual file sy
bc70: 73 74 65 6d 22 2e 20 20 53 65 65 0a 2a 2a 20 74  stem".  See.** t
bc80: 68 65 20 5b 56 46 53 20 7c 20 56 46 53 20 64 6f  he [VFS | VFS do
bc90: 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
bca0: 20 66 75 72 74 68 65 72 20 69 6e 66 6f 72 6d 61   further informa
bcb0: 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tion..**.** The 
bcc0: 76 61 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65  value of the iVe
bcd0: 72 73 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69  rsion field is i
bce0: 6e 69 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d  nitially 1 but m
bcf0: 61 79 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a  ay be larger in.
bd00: 2a 2a 20 66 75 74 75 72 65 20 76 65 72 73 69 6f  ** future versio
bd10: 6e 73 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41  ns of SQLite.  A
bd20: 64 64 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73  dditional fields
bd30: 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64   may be appended
bd40: 20 74 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65   to this.** obje
bd50: 63 74 20 77 68 65 6e 20 74 68 65 20 69 56 65 72  ct when the iVer
bd60: 73 69 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e  sion value is in
bd70: 63 72 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74  creased.  Note t
bd80: 68 61 74 20 74 68 65 20 73 74 72 75 63 74 75 72  hat the structur
bd90: 65 0a 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69  e.** of the sqli
bda0: 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63  te3_vfs object c
bdb0: 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72  hanges in the tr
bdc0: 61 6e 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65  ansaction betwee
bdd0: 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73  n.** SQLite vers
bde0: 69 6f 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e  ion 3.5.9 and 3.
bdf0: 36 2e 30 20 61 6e 64 20 79 65 74 20 74 68 65 20  6.0 and yet the 
be00: 69 56 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77  iVersion field w
be10: 61 73 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69  as not.** modifi
be20: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a  ed..**.** The sz
be30: 4f 73 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20  OsFile field is 
be40: 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  the size of the 
be50: 73 75 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69  subclassed [sqli
be60: 74 65 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72  te3_file].** str
be70: 75 63 74 75 72 65 20 75 73 65 64 20 62 79 20 74  ucture used by t
be80: 68 69 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68  his VFS.  mxPath
be90: 6e 61 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69  name is the maxi
bea0: 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a  mum length of.**
beb0: 20 61 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74   a pathname in t
bec0: 68 69 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52  his VFS..**.** R
bed0: 65 67 69 73 74 65 72 65 64 20 73 71 6c 69 74 65  egistered sqlite
bee0: 33 5f 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72  3_vfs objects ar
bef0: 65 20 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b  e kept on a link
bf00: 65 64 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62  ed list formed b
bf10: 79 0a 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70  y.** the pNext p
bf20: 6f 69 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71  ointer.  The [sq
bf30: 6c 69 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74  lite3_vfs_regist
bf40: 65 72 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  er()].** and [sq
bf50: 6c 69 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69  lite3_vfs_unregi
bf60: 73 74 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63  ster()] interfac
bf70: 65 73 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c  es manage this l
bf80: 69 73 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65  ist.** in a thre
bf90: 61 64 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68  ad-safe way.  Th
bfa0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66  e [sqlite3_vfs_f
bfb0: 69 6e 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ind()] interface
bfc0: 0a 2a 2a 20 73 65 61 72 63 68 65 73 20 74 68 65  .** searches the
bfd0: 20 6c 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20   list.  Neither 
bfe0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
bff0: 63 6f 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53  code nor the VFS
c000: 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  .** implementati
c010: 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68  on should use th
c020: 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e  e pNext pointer.
c030: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74  .**.** The pNext
c040: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e   field is the on
c050: 6c 79 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20  ly field in the 
c060: 73 71 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73  sqlite3_vfs.** s
c070: 74 72 75 63 74 75 72 65 20 74 68 61 74 20 53 51  tructure that SQ
c080: 4c 69 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d  Lite will ever m
c090: 6f 64 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77  odify.  SQLite w
c0a0: 69 6c 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a  ill only access.
c0b0: 2a 2a 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69  ** or modify thi
c0c0: 73 20 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f  s field while ho
c0d0: 6c 64 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c  lding a particul
c0e0: 61 72 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e  ar static mutex.
c0f0: 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
c100: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72  ion should never
c110: 20 6d 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67   modify anything
c120: 20 77 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69   within the sqli
c130: 74 65 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63  te3_vfs.** objec
c140: 74 20 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63  t once the objec
c150: 74 20 68 61 73 20 62 65 65 6e 20 72 65 67 69 73  t has been regis
c160: 74 65 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tered..**.** The
c170: 20 7a 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c   zName field hol
c180: 64 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  ds the name of t
c190: 68 65 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20  he VFS module.  
c1a0: 54 68 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a  The name must.**
c1b0: 20 62 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73   be unique acros
c1c0: 73 20 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65  s all VFS module
c1d0: 73 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74  s..**.** [[sqlit
c1e0: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a  e3_vfs.xOpen]].*
c1f0: 2a 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e  * ^SQLite guaran
c200: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 7a 46  tees that the zF
c210: 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65  ilename paramete
c220: 72 20 74 6f 20 78 4f 70 65 6e 0a 2a 2a 20 69 73  r to xOpen.** is
c230: 20 65 69 74 68 65 72 20 61 20 4e 55 4c 4c 20 70   either a NULL p
c240: 6f 69 6e 74 65 72 20 6f 72 20 73 74 72 69 6e 67  ointer or string
c250: 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
c260: 6d 20 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 28  m xFullPathname(
c270: 29 20 77 69 74 68 20 61 6e 20 6f 70 74 69 6f 6e  ) with an option
c280: 61 6c 20 73 75 66 66 69 78 20 61 64 64 65 64 2e  al suffix added.
c290: 0a 2a 2a 20 5e 49 66 20 61 20 73 75 66 66 69 78  .** ^If a suffix
c2a0: 20 69 73 20 61 64 64 65 64 20 74 6f 20 74 68 65   is added to the
c2b0: 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   zFilename param
c2c0: 65 74 65 72 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a  eter, it will.**
c2d0: 20 63 6f 6e 73 69 73 74 20 6f 66 20 61 20 73 69   consist of a si
c2e0: 6e 67 6c 65 20 22 2d 22 20 63 68 61 72 61 63 74  ngle "-" charact
c2f0: 65 72 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 6e  er followed by n
c300: 6f 20 6d 6f 72 65 20 74 68 61 6e 0a 2a 2a 20 31  o more than.** 1
c310: 31 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 61  1 alphanumeric a
c320: 6e 64 2f 6f 72 20 22 2d 22 20 63 68 61 72 61 63  nd/or "-" charac
c330: 74 65 72 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  ters..** ^SQLite
c340: 20 66 75 72 74 68 65 72 20 67 75 61 72 61 6e 74   further guarant
c350: 65 65 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20  ees that.** the 
c360: 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 20 76  string will be v
c370: 61 6c 69 64 20 61 6e 64 20 75 6e 63 68 61 6e 67  alid and unchang
c380: 65 64 20 75 6e 74 69 6c 20 78 43 6c 6f 73 65 28  ed until xClose(
c390: 29 20 69 73 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20  ) is.** called. 
c3a0: 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 70  Because of the p
c3b0: 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
c3c0: 2c 0a 2a 2a 20 74 68 65 20 5b 73 71 6c 69 74 65  ,.** the [sqlite
c3d0: 33 5f 66 69 6c 65 5d 20 63 61 6e 20 73 61 66 65  3_file] can safe
c3e0: 6c 79 20 73 74 6f 72 65 20 61 20 70 6f 69 6e 74  ly store a point
c3f0: 65 72 20 74 6f 20 74 68 65 0a 2a 2a 20 66 69 6c  er to the.** fil
c400: 65 6e 61 6d 65 20 69 66 20 69 74 20 6e 65 65 64  ename if it need
c410: 73 20 74 6f 20 72 65 6d 65 6d 62 65 72 20 74 68  s to remember th
c420: 65 20 66 69 6c 65 6e 61 6d 65 20 66 6f 72 20 73  e filename for s
c430: 6f 6d 65 20 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49  ome reason..** I
c440: 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  f the zFilename 
c450: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78 4f 70  parameter to xOp
c460: 65 6e 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  en is a NULL poi
c470: 6e 74 65 72 20 74 68 65 6e 20 78 4f 70 65 6e 0a  nter then xOpen.
c480: 2a 2a 20 6d 75 73 74 20 69 6e 76 65 6e 74 20 69  ** must invent i
c490: 74 73 20 6f 77 6e 20 74 65 6d 70 6f 72 61 72 79  ts own temporary
c4a0: 20 6e 61 6d 65 20 66 6f 72 20 74 68 65 20 66 69   name for the fi
c4b0: 6c 65 2e 20 20 5e 57 68 65 6e 65 76 65 72 20 74  le.  ^Whenever t
c4c0: 68 65 20 0a 2a 2a 20 78 46 69 6c 65 6e 61 6d 65  he .** xFilename
c4d0: 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 4e 55   parameter is NU
c4e0: 4c 4c 20 69 74 20 77 69 6c 6c 20 61 6c 73 6f 20  LL it will also 
c4f0: 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
c500: 20 74 68 65 0a 2a 2a 20 66 6c 61 67 73 20 70 61   the.** flags pa
c510: 72 61 6d 65 74 65 72 20 77 69 6c 6c 20 69 6e 63  rameter will inc
c520: 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  lude [SQLITE_OPE
c530: 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d  N_DELETEONCLOSE]
c540: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 6c 61 67  ..**.** The flag
c550: 73 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f  s argument to xO
c560: 70 65 6e 28 29 20 69 6e 63 6c 75 64 65 73 20 61  pen() includes a
c570: 6c 6c 20 62 69 74 73 20 73 65 74 20 69 6e 0a 2a  ll bits set in.*
c580: 2a 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  * the flags argu
c590: 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  ment to [sqlite3
c5a0: 5f 6f 70 65 6e 5f 76 32 28 29 5d 2e 20 20 4f 72  _open_v2()].  Or
c5b0: 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   if [sqlite3_ope
c5c0: 6e 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  n()].** or [sqli
c5d0: 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 20 69 73  te3_open16()] is
c5e0: 20 75 73 65 64 2c 20 74 68 65 6e 20 66 6c 61 67   used, then flag
c5f0: 73 20 69 6e 63 6c 75 64 65 73 20 61 74 20 6c 65  s includes at le
c600: 61 73 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  ast.** [SQLITE_O
c610: 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
c620: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
c630: 45 41 54 45 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f  EATE]. .** If xO
c640: 70 65 6e 28 29 20 6f 70 65 6e 73 20 61 20 66 69  pen() opens a fi
c650: 6c 65 20 72 65 61 64 2d 6f 6e 6c 79 20 74 68 65  le read-only the
c660: 6e 20 69 74 20 73 65 74 73 20 2a 70 4f 75 74 46  n it sets *pOutF
c670: 6c 61 67 73 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75  lags to.** inclu
c680: 64 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  de [SQLITE_OPEN_
c690: 52 45 41 44 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65  READONLY].  Othe
c6a0: 72 20 62 69 74 73 20 69 6e 20 2a 70 4f 75 74 46  r bits in *pOutF
c6b0: 6c 61 67 73 20 6d 61 79 20 62 65 20 73 65 74 2e  lags may be set.
c6c0: 0a 2a 2a 0a 2a 2a 20 5e 28 53 51 4c 69 74 65 20  .**.** ^(SQLite 
c6d0: 77 69 6c 6c 20 61 6c 73 6f 20 61 64 64 20 6f 6e  will also add on
c6e0: 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
c6f0: 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65 20  ng flags to the 
c700: 78 4f 70 65 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c  xOpen().** call,
c710: 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68   depending on th
c720: 65 20 6f 62 6a 65 63 74 20 62 65 69 6e 67 20 6f  e object being o
c730: 70 65 6e 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c  pened:.**.** <ul
c740: 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  >.** <li>  [SQLI
c750: 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d  TE_OPEN_MAIN_DB]
c760: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
c770: 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52  E_OPEN_MAIN_JOUR
c780: 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53  NAL].** <li>  [S
c790: 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f  QLITE_OPEN_TEMP_
c7a0: 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  DB].** <li>  [SQ
c7b0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a  LITE_OPEN_TEMP_J
c7c0: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
c7d0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54 52   [SQLITE_OPEN_TR
c7e0: 41 4e 53 49 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c  ANSIENT_DB].** <
c7f0: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
c800: 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  N_SUBJOURNAL].**
c810: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
c820: 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52 4e  PEN_MASTER_JOURN
c830: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
c840: 4c 49 54 45 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a  LITE_OPEN_WAL].*
c850: 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20  * </ul>)^.**.** 
c860: 54 68 65 20 66 69 6c 65 20 49 2f 4f 20 69 6d 70  The file I/O imp
c870: 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 63 61 6e 20  lementation can 
c880: 75 73 65 20 74 68 65 20 6f 62 6a 65 63 74 20 74  use the object t
c890: 79 70 65 20 66 6c 61 67 73 20 74 6f 0a 2a 2a 20  ype flags to.** 
c8a0: 63 68 61 6e 67 65 20 74 68 65 20 77 61 79 20 69  change the way i
c8b0: 74 20 64 65 61 6c 73 20 77 69 74 68 20 66 69 6c  t deals with fil
c8c0: 65 73 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c 65  es.  For example
c8d0: 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  , an application
c8e0: 0a 2a 2a 20 74 68 61 74 20 64 6f 65 73 20 6e 6f  .** that does no
c8f0: 74 20 63 61 72 65 20 61 62 6f 75 74 20 63 72 61  t care about cra
c900: 73 68 20 72 65 63 6f 76 65 72 79 20 6f 72 20 72  sh recovery or r
c910: 6f 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 6d 61  ollback might ma
c920: 6b 65 0a 2a 2a 20 74 68 65 20 6f 70 65 6e 20 6f  ke.** the open o
c930: 66 20 61 20 6a 6f 75 72 6e 61 6c 20 66 69 6c 65  f a journal file
c940: 20 61 20 6e 6f 2d 6f 70 2e 20 20 57 72 69 74 65   a no-op.  Write
c950: 73 20 74 6f 20 74 68 69 73 20 6a 6f 75 72 6e 61  s to this journa
c960: 6c 20 77 6f 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20  l would.** also 
c970: 62 65 20 6e 6f 2d 6f 70 73 2c 20 61 6e 64 20 61  be no-ops, and a
c980: 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20 72 65  ny attempt to re
c990: 61 64 20 74 68 65 20 6a 6f 75 72 6e 61 6c 20 77  ad the journal w
c9a0: 6f 75 6c 64 20 72 65 74 75 72 6e 0a 2a 2a 20 53  ould return.** S
c9b0: 51 4c 49 54 45 5f 49 4f 45 52 52 2e 20 20 4f 72  QLITE_IOERR.  Or
c9c0: 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
c9d0: 69 6f 6e 20 6d 69 67 68 74 20 72 65 63 6f 67 6e  ion might recogn
c9e0: 69 7a 65 20 74 68 61 74 20 61 20 64 61 74 61 62  ize that a datab
c9f0: 61 73 65 0a 2a 2a 20 66 69 6c 65 20 77 69 6c 6c  ase.** file will
ca00: 20 62 65 20 64 6f 69 6e 67 20 70 61 67 65 2d 61   be doing page-a
ca10: 6c 69 67 6e 65 64 20 73 65 63 74 6f 72 20 72 65  ligned sector re
ca20: 61 64 73 20 61 6e 64 20 77 72 69 74 65 73 20 69  ads and writes i
ca30: 6e 20 61 20 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72  n a random.** or
ca40: 64 65 72 20 61 6e 64 20 73 65 74 20 75 70 20 69  der and set up i
ca50: 74 73 20 49 2f 4f 20 73 75 62 73 79 73 74 65 6d  ts I/O subsystem
ca60: 20 61 63 63 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a   accordingly..**
ca70: 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 69 67 68 74  .** SQLite might
ca80: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
ca90: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
caa0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
cab0: 6e 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20  n method:.**.** 
cac0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
cad0: 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45  LITE_OPEN_DELETE
cae0: 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e  ONCLOSE].** <li>
caf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58   [SQLITE_OPEN_EX
cb00: 43 4c 55 53 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c  CLUSIVE].** </ul
cb10: 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c  >.**.** The [SQL
cb20: 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f  ITE_OPEN_DELETEO
cb30: 4e 43 4c 4f 53 45 5d 20 66 6c 61 67 20 6d 65 61  NCLOSE] flag mea
cb40: 6e 73 20 74 68 65 20 66 69 6c 65 20 73 68 6f 75  ns the file shou
cb50: 6c 64 20 62 65 0a 2a 2a 20 64 65 6c 65 74 65 64  ld be.** deleted
cb60: 20 77 68 65 6e 20 69 74 20 69 73 20 63 6c 6f 73   when it is clos
cb70: 65 64 2e 20 20 5e 54 68 65 20 5b 53 51 4c 49 54  ed.  ^The [SQLIT
cb80: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
cb90: 4c 4f 53 45 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65  LOSE].** will be
cba0: 20 73 65 74 20 66 6f 72 20 54 45 4d 50 20 64 61   set for TEMP da
cbb0: 74 61 62 61 73 65 73 20 61 6e 64 20 74 68 65 69  tabases and thei
cbc0: 72 20 6a 6f 75 72 6e 61 6c 73 2c 20 74 72 61 6e  r journals, tran
cbd0: 73 69 65 6e 74 0a 2a 2a 20 64 61 74 61 62 61 73  sient.** databas
cbe0: 65 73 2c 20 61 6e 64 20 73 75 62 6a 6f 75 72 6e  es, and subjourn
cbf0: 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  als..**.** ^The 
cc00: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43  [SQLITE_OPEN_EXC
cc10: 4c 55 53 49 56 45 5d 20 66 6c 61 67 20 69 73 20  LUSIVE] flag is 
cc20: 61 6c 77 61 79 73 20 75 73 65 64 20 69 6e 20 63  always used in c
cc30: 6f 6e 6a 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69  onjunction.** wi
cc40: 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  th the [SQLITE_O
cc50: 50 45 4e 5f 43 52 45 41 54 45 5d 20 66 6c 61 67  PEN_CREATE] flag
cc60: 2c 20 77 68 69 63 68 20 61 72 65 20 62 6f 74 68  , which are both
cc70: 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 61 6e 61   directly.** ana
cc80: 6c 6f 67 6f 75 73 20 74 6f 20 74 68 65 20 4f 5f  logous to the O_
cc90: 45 58 43 4c 20 61 6e 64 20 4f 5f 43 52 45 41 54  EXCL and O_CREAT
cca0: 20 66 6c 61 67 73 20 6f 66 20 74 68 65 20 50 4f   flags of the PO
ccb0: 53 49 58 20 6f 70 65 6e 28 29 0a 2a 2a 20 41 50  SIX open().** AP
ccc0: 49 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 4f  I.  The SQLITE_O
ccd0: 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 66 6c  PEN_EXCLUSIVE fl
cce0: 61 67 2c 20 77 68 65 6e 20 70 61 69 72 65 64 20  ag, when paired 
ccf0: 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 53 51 4c  with the .** SQL
cd00: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 2c  ITE_OPEN_CREATE,
cd10: 20 69 73 20 75 73 65 64 20 74 6f 20 69 6e 64 69   is used to indi
cd20: 63 61 74 65 20 74 68 61 74 20 66 69 6c 65 20 73  cate that file s
cd30: 68 6f 75 6c 64 20 61 6c 77 61 79 73 0a 2a 2a 20  hould always.** 
cd40: 62 65 20 63 72 65 61 74 65 64 2c 20 61 6e 64 20  be created, and 
cd50: 74 68 61 74 20 69 74 20 69 73 20 61 6e 20 65 72  that it is an er
cd60: 72 6f 72 20 69 66 20 69 74 20 61 6c 72 65 61 64  ror if it alread
cd70: 79 20 65 78 69 73 74 73 2e 0a 2a 2a 20 49 74 20  y exists..** It 
cd80: 69 73 20 3c 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73  is <i>not</i> us
cd90: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
cda0: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
cdb0: 65 20 6f 70 65 6e 65 64 20 0a 2a 2a 20 66 6f 72  e opened .** for
cdc0: 20 65 78 63 6c 75 73 69 76 65 20 61 63 63 65 73   exclusive acces
cdd0: 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61  s..**.** ^At lea
cde0: 73 74 20 73 7a 4f 73 46 69 6c 65 20 62 79 74 65  st szOsFile byte
cdf0: 73 20 6f 66 20 6d 65 6d 6f 72 79 20 61 72 65 20  s of memory are 
ce00: 61 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c  allocated by SQL
ce10: 69 74 65 0a 2a 2a 20 74 6f 20 68 6f 6c 64 20 74  ite.** to hold t
ce20: 68 65 20 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  he  [sqlite3_fil
ce30: 65 5d 20 73 74 72 75 63 74 75 72 65 20 70 61 73  e] structure pas
ce40: 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
ce50: 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  .** argument to 
ce60: 78 4f 70 65 6e 2e 20 20 54 68 65 20 78 4f 70 65  xOpen.  The xOpe
ce70: 6e 20 6d 65 74 68 6f 64 20 64 6f 65 73 20 6e 6f  n method does no
ce80: 74 20 68 61 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c  t have to.** all
ce90: 6f 63 61 74 65 20 74 68 65 20 73 74 72 75 63 74  ocate the struct
cea0: 75 72 65 3b 20 69 74 20 73 68 6f 75 6c 64 20 6a  ure; it should j
ceb0: 75 73 74 20 66 69 6c 6c 20 69 74 20 69 6e 2e 20  ust fill it in. 
cec0: 20 4e 6f 74 65 20 74 68 61 74 0a 2a 2a 20 74 68   Note that.** th
ced0: 65 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6d  e xOpen method m
cee0: 75 73 74 20 73 65 74 20 74 68 65 20 73 71 6c 69  ust set the sqli
cef0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
cf00: 73 20 74 6f 20 65 69 74 68 65 72 0a 2a 2a 20 61  s to either.** a
cf10: 20 76 61 6c 69 64 20 5b 73 71 6c 69 74 65 33 5f   valid [sqlite3_
cf20: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
cf30: 63 74 20 6f 72 20 74 6f 20 4e 55 4c 4c 2e 20 20  ct or to NULL.  
cf40: 78 4f 70 65 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a  xOpen must do.**
cf50: 20 74 68 69 73 20 65 76 65 6e 20 69 66 20 74 68   this even if th
cf60: 65 20 6f 70 65 6e 20 66 61 69 6c 73 2e 20 20 53  e open fails.  S
cf70: 51 4c 69 74 65 20 65 78 70 65 63 74 73 20 74 68  QLite expects th
cf80: 61 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  at the sqlite3_f
cf90: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 0a 2a 2a 20  ile.pMethods.** 
cfa0: 65 6c 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65 20  element will be 
cfb0: 76 61 6c 69 64 20 61 66 74 65 72 20 78 4f 70 65  valid after xOpe
cfc0: 6e 20 72 65 74 75 72 6e 73 20 72 65 67 61 72 64  n returns regard
cfd0: 6c 65 73 73 20 6f 66 20 74 68 65 20 73 75 63 63  less of the succ
cfe0: 65 73 73 0a 2a 2a 20 6f 72 20 66 61 69 6c 75 72  ess.** or failur
cff0: 65 20 6f 66 20 74 68 65 20 78 4f 70 65 6e 20 63  e of the xOpen c
d000: 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c  all..**.** [[sql
d010: 69 74 65 33 5f 76 66 73 2e 78 41 63 63 65 73 73  ite3_vfs.xAccess
d020: 5d 5d 0a 2a 2a 20 5e 54 68 65 20 66 6c 61 67 73  ]].** ^The flags
d030: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 41 63   argument to xAc
d040: 63 65 73 73 28 29 20 6d 61 79 20 62 65 20 5b 53  cess() may be [S
d050: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
d060: 53 54 53 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20  STS].** to test 
d070: 66 6f 72 20 74 68 65 20 65 78 69 73 74 65 6e 63  for the existenc
d080: 65 20 6f 66 20 61 20 66 69 6c 65 2c 20 6f 72 20  e of a file, or 
d090: 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52  [SQLITE_ACCESS_R
d0a0: 45 41 44 57 52 49 54 45 5d 20 74 6f 0a 2a 2a 20  EADWRITE] to.** 
d0b0: 74 65 73 74 20 77 68 65 74 68 65 72 20 61 20 66  test whether a f
d0c0: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 20  ile is readable 
d0d0: 61 6e 64 20 77 72 69 74 61 62 6c 65 2c 20 6f 72  and writable, or
d0e0: 20 5b 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f   [SQLITE_ACCESS_
d0f0: 52 45 41 44 5d 0a 2a 2a 20 74 6f 20 74 65 73 74  READ].** to test
d100: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
d110: 69 73 20 61 74 20 6c 65 61 73 74 20 72 65 61 64  is at least read
d120: 61 62 6c 65 2e 20 20 20 54 68 65 20 66 69 6c 65  able.   The file
d130: 20 63 61 6e 20 62 65 20 61 0a 2a 2a 20 64 69 72   can be a.** dir
d140: 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53  ectory..**.** ^S
d150: 51 4c 69 74 65 20 77 69 6c 6c 20 61 6c 77 61 79  QLite will alway
d160: 73 20 61 6c 6c 6f 63 61 74 65 20 61 74 20 6c 65  s allocate at le
d170: 61 73 74 20 6d 78 50 61 74 68 6e 61 6d 65 2b 31  ast mxPathname+1
d180: 20 62 79 74 65 73 20 66 6f 72 20 74 68 65 0a 2a   bytes for the.*
d190: 2a 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 20  * output buffer 
d1a0: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 2e 20 20  xFullPathname.  
d1b0: 54 68 65 20 65 78 61 63 74 20 73 69 7a 65 20 6f  The exact size o
d1c0: 66 20 74 68 65 20 6f 75 74 70 75 74 20 62 75 66  f the output buf
d1d0: 66 65 72 0a 2a 2a 20 69 73 20 61 6c 73 6f 20 70  fer.** is also p
d1e0: 61 73 73 65 64 20 61 73 20 61 20 70 61 72 61 6d  assed as a param
d1f0: 65 74 65 72 20 74 6f 20 62 6f 74 68 20 20 6d 65  eter to both  me
d200: 74 68 6f 64 73 2e 20 49 66 20 74 68 65 20 6f 75  thods. If the ou
d210: 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a 20 69  tput buffer.** i
d220: 73 20 6e 6f 74 20 6c 61 72 67 65 20 65 6e 6f 75  s not large enou
d230: 67 68 2c 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54  gh, [SQLITE_CANT
d240: 4f 50 45 4e 5d 20 73 68 6f 75 6c 64 20 62 65 20  OPEN] should be 
d250: 72 65 74 75 72 6e 65 64 2e 20 53 69 6e 63 65 20  returned. Since 
d260: 74 68 69 73 20 69 73 0a 2a 2a 20 68 61 6e 64 6c  this is.** handl
d270: 65 64 20 61 73 20 61 20 66 61 74 61 6c 20 65 72  ed as a fatal er
d280: 72 6f 72 20 62 79 20 53 51 4c 69 74 65 2c 20 76  ror by SQLite, v
d290: 66 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  fs implementatio
d2a0: 6e 73 20 73 68 6f 75 6c 64 20 65 6e 64 65 61 76  ns should endeav
d2b0: 6f 72 0a 2a 2a 20 74 6f 20 70 72 65 76 65 6e 74  or.** to prevent
d2c0: 20 74 68 69 73 20 62 79 20 73 65 74 74 69 6e 67   this by setting
d2d0: 20 6d 78 50 61 74 68 6e 61 6d 65 20 74 6f 20 61   mxPathname to a
d2e0: 20 73 75 66 66 69 63 69 65 6e 74 6c 79 20 6c 61   sufficiently la
d2f0: 72 67 65 20 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a  rge value..**.**
d300: 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73   The xRandomness
d310: 28 29 2c 20 78 53 6c 65 65 70 28 29 2c 20 78 43  (), xSleep(), xC
d320: 75 72 72 65 6e 74 54 69 6d 65 28 29 2c 20 61 6e  urrentTime(), an
d330: 64 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  d xCurrentTimeIn
d340: 74 36 34 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61  t64().** interfa
d350: 63 65 73 20 61 72 65 20 6e 6f 74 20 73 74 72 69  ces are not stri
d360: 63 74 6c 79 20 61 20 70 61 72 74 20 6f 66 20 74  ctly a part of t
d370: 68 65 20 66 69 6c 65 73 79 73 74 65 6d 2c 20 62  he filesystem, b
d380: 75 74 20 74 68 65 79 20 61 72 65 0a 2a 2a 20 69  ut they are.** i
d390: 6e 63 6c 75 64 65 64 20 69 6e 20 74 68 65 20 56  ncluded in the V
d3a0: 46 53 20 73 74 72 75 63 74 75 72 65 20 66 6f 72  FS structure for
d3b0: 20 63 6f 6d 70 6c 65 74 65 6e 65 73 73 2e 0a 2a   completeness..*
d3c0: 2a 20 54 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  * The xRandomnes
d3d0: 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 61 74 74  s() function att
d3e0: 65 6d 70 74 73 20 74 6f 20 72 65 74 75 72 6e 20  empts to return 
d3f0: 6e 42 79 74 65 73 20 62 79 74 65 73 0a 2a 2a 20  nBytes bytes.** 
d400: 6f 66 20 67 6f 6f 64 2d 71 75 61 6c 69 74 79 20  of good-quality 
d410: 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20  randomness into 
d420: 7a 4f 75 74 2e 20 20 54 68 65 20 72 65 74 75 72  zOut.  The retur
d430: 6e 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 74 68  n value is.** th
d440: 65 20 61 63 74 75 61 6c 20 6e 75 6d 62 65 72 20  e actual number 
d450: 6f 66 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64  of bytes of rand
d460: 6f 6d 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 2e  omness obtained.
d470: 0a 2a 2a 20 54 68 65 20 78 53 6c 65 65 70 28 29  .** The xSleep()
d480: 20 6d 65 74 68 6f 64 20 63 61 75 73 65 73 20 74   method causes t
d490: 68 65 20 63 61 6c 6c 69 6e 67 20 74 68 72 65 61  he calling threa
d4a0: 64 20 74 6f 20 73 6c 65 65 70 20 66 6f 72 20 61  d to sleep for a
d4b0: 74 0a 2a 2a 20 6c 65 61 73 74 20 74 68 65 20 6e  t.** least the n
d4c0: 75 6d 62 65 72 20 6f 66 20 6d 69 63 72 6f 73 65  umber of microse
d4d0: 63 6f 6e 64 73 20 67 69 76 65 6e 2e 20 20 5e 54  conds given.  ^T
d4e0: 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  he xCurrentTime(
d4f0: 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74 75  ).** method retu
d500: 72 6e 73 20 61 20 4a 75 6c 69 61 6e 20 44 61 79  rns a Julian Day
d510: 20 4e 75 6d 62 65 72 20 66 6f 72 20 74 68 65 20   Number for the 
d520: 63 75 72 72 65 6e 74 20 64 61 74 65 20 61 6e 64  current date and
d530: 20 74 69 6d 65 20 61 73 0a 2a 2a 20 61 20 66 6c   time as.** a fl
d540: 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c  oating point val
d550: 75 65 2e 0a 2a 2a 20 5e 54 68 65 20 78 43 75 72  ue..** ^The xCur
d560: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d570: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 2c 20  method returns, 
d580: 61 73 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74  as an integer, t
d590: 68 65 20 4a 75 6c 69 61 6e 0a 2a 2a 20 44 61 79  he Julian.** Day
d5a0: 20 4e 75 6d 62 65 72 20 6d 75 6c 74 69 70 6c 69   Number multipli
d5b0: 65 64 20 62 79 20 38 36 34 30 30 30 30 30 20 28  ed by 86400000 (
d5c0: 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69  the number of mi
d5d0: 6c 6c 69 73 65 63 6f 6e 64 73 20 69 6e 20 0a 2a  lliseconds in .*
d5e0: 2a 20 61 20 32 34 2d 68 6f 75 72 20 64 61 79 29  * a 24-hour day)
d5f0: 2e 20 20 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  .  .** ^SQLite w
d600: 69 6c 6c 20 75 73 65 20 74 68 65 20 78 43 75 72  ill use the xCur
d610: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 20  rentTimeInt64() 
d620: 6d 65 74 68 6f 64 20 74 6f 20 67 65 74 20 74 68  method to get th
d630: 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 64 61 74  e current.** dat
d640: 65 20 61 6e 64 20 74 69 6d 65 20 69 66 20 74 68  e and time if th
d650: 61 74 20 6d 65 74 68 6f 64 20 69 73 20 61 76 61  at method is ava
d660: 69 6c 61 62 6c 65 20 28 69 66 20 69 56 65 72 73  ilable (if iVers
d670: 69 6f 6e 20 69 73 20 32 20 6f 72 20 0a 2a 2a 20  ion is 2 or .** 
d680: 67 72 65 61 74 65 72 20 61 6e 64 20 74 68 65 20  greater and the 
d690: 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72  function pointer
d6a0: 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e   is not NULL) an
d6b0: 64 20 77 69 6c 6c 20 66 61 6c 6c 20 62 61 63 6b  d will fall back
d6c0: 0a 2a 2a 20 74 6f 20 78 43 75 72 72 65 6e 74 54  .** to xCurrentT
d6d0: 69 6d 65 28 29 20 69 66 20 78 43 75 72 72 65 6e  ime() if xCurren
d6e0: 74 54 69 6d 65 49 6e 74 36 34 28 29 20 69 73 20  tTimeInt64() is 
d6f0: 75 6e 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a  unavailable..**.
d700: 2a 2a 20 5e 54 68 65 20 78 53 65 74 53 79 73 74  ** ^The xSetSyst
d710: 65 6d 43 61 6c 6c 28 29 2c 20 78 47 65 74 53 79  emCall(), xGetSy
d720: 73 74 65 6d 43 61 6c 6c 28 29 2c 20 61 6e 64 20  stemCall(), and 
d730: 78 4e 65 73 74 53 79 73 74 65 6d 43 61 6c 6c 28  xNestSystemCall(
d740: 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
d750: 61 72 65 20 6e 6f 74 20 75 73 65 64 20 62 79 20  are not used by 
d760: 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 2e  the SQLite core.
d770: 20 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 61 6c    These optional
d780: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
d790: 70 72 6f 76 69 64 65 64 0a 2a 2a 20 62 79 20 73  provided.** by s
d7a0: 6f 6d 65 20 56 46 53 65 73 20 74 6f 20 66 61 63  ome VFSes to fac
d7b0: 69 6c 69 74 61 74 65 20 74 65 73 74 69 6e 67 20  ilitate testing 
d7c0: 6f 66 20 74 68 65 20 56 46 53 20 63 6f 64 65 2e  of the VFS code.
d7d0: 20 42 79 20 6f 76 65 72 72 69 64 69 6e 67 20 0a   By overriding .
d7e0: 2a 2a 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  ** system calls 
d7f0: 77 69 74 68 20 66 75 6e 63 74 69 6f 6e 73 20 75  with functions u
d800: 6e 64 65 72 20 69 74 73 20 63 6f 6e 74 72 6f 6c  nder its control
d810: 2c 20 61 20 74 65 73 74 20 70 72 6f 67 72 61 6d  , a test program
d820: 20 63 61 6e 0a 2a 2a 20 73 69 6d 75 6c 61 74 65   can.** simulate
d830: 20 66 61 75 6c 74 73 20 61 6e 64 20 65 72 72 6f   faults and erro
d840: 72 20 63 6f 6e 64 69 74 69 6f 6e 73 20 74 68 61  r conditions tha
d850: 74 20 77 6f 75 6c 64 20 6f 74 68 65 72 77 69 73  t would otherwis
d860: 65 20 62 65 20 64 69 66 66 69 63 75 6c 74 0a 2a  e be difficult.*
d870: 2a 20 6f 72 20 69 6d 70 6f 73 73 69 62 6c 65 20  * or impossible 
d880: 74 6f 20 69 6e 64 75 63 65 2e 20 20 54 68 65 20  to induce.  The 
d890: 73 65 74 20 6f 66 20 73 79 73 74 65 6d 20 63 61  set of system ca
d8a0: 6c 6c 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  lls that can be 
d8b0: 6f 76 65 72 72 69 64 64 65 6e 0a 2a 2a 20 76 61  overridden.** va
d8c0: 72 69 65 73 20 66 72 6f 6d 20 6f 6e 65 20 56 46  ries from one VF
d8d0: 53 20 74 6f 20 61 6e 6f 74 68 65 72 2c 20 61 6e  S to another, an
d8e0: 64 20 66 72 6f 6d 20 6f 6e 65 20 76 65 72 73 69  d from one versi
d8f0: 6f 6e 20 6f 66 20 74 68 65 20 73 61 6d 65 20 56  on of the same V
d900: 46 53 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 65 78  FS to the.** nex
d910: 74 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  t.  Applications
d920: 20 74 68 61 74 20 75 73 65 20 74 68 65 73 65 20   that use these 
d930: 69 6e 74 65 72 66 61 63 65 73 20 6d 75 73 74 20  interfaces must 
d940: 62 65 20 70 72 65 70 61 72 65 64 20 66 6f 72 20  be prepared for 
d950: 61 6e 79 0a 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66  any.** or all of
d960: 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
d970: 73 20 74 6f 20 62 65 20 4e 55 4c 4c 20 6f 72 20  s to be NULL or 
d980: 66 6f 72 20 74 68 65 69 72 20 62 65 68 61 76 69  for their behavi
d990: 6f 72 20 74 6f 20 63 68 61 6e 67 65 0a 2a 2a 20  or to change.** 
d9a0: 66 72 6f 6d 20 6f 6e 65 20 72 65 6c 65 61 73 65  from one release
d9b0: 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 20 20 41   to the next.  A
d9c0: 70 70 6c 69 63 61 74 69 6f 6e 73 20 6d 75 73 74  pplications must
d9d0: 20 6e 6f 74 20 61 74 74 65 6d 70 74 20 74 6f 20   not attempt to 
d9e0: 61 63 63 65 73 73 0a 2a 2a 20 61 6e 79 20 6f 66  access.** any of
d9f0: 20 74 68 65 73 65 20 6d 65 74 68 6f 64 73 20 69   these methods i
da00: 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 6f  f the iVersion o
da10: 66 20 74 68 65 20 56 46 53 20 69 73 20 6c 65 73  f the VFS is les
da20: 73 20 74 68 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70  s than 3..*/.typ
da30: 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
da40: 74 65 33 5f 76 66 73 20 73 71 6c 69 74 65 33 5f  te3_vfs sqlite3_
da50: 76 66 73 3b 0a 74 79 70 65 64 65 66 20 76 6f 69  vfs;.typedef voi
da60: 64 20 28 2a 73 71 6c 69 74 65 33 5f 73 79 73 63  d (*sqlite3_sysc
da70: 61 6c 6c 5f 70 74 72 29 28 76 6f 69 64 29 3b 0a  all_ptr)(void);.
da80: 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76  struct sqlite3_v
da90: 66 73 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  fs {.  int iVers
daa0: 69 6f 6e 3b 20 20 20 20 20 20 20 20 20 20 20 20  ion;            
dab0: 2f 2a 20 53 74 72 75 63 74 75 72 65 20 76 65 72  /* Structure ver
dac0: 73 69 6f 6e 20 6e 75 6d 62 65 72 20 28 63 75 72  sion number (cur
dad0: 72 65 6e 74 6c 79 20 33 29 20 2a 2f 0a 20 20 69  rently 3) */.  i
dae0: 6e 74 20 73 7a 4f 73 46 69 6c 65 3b 20 20 20 20  nt szOsFile;    
daf0: 20 20 20 20 20 20 20 20 2f 2a 20 53 69 7a 65 20          /* Size 
db00: 6f 66 20 73 75 62 63 6c 61 73 73 65 64 20 73 71  of subclassed sq
db10: 6c 69 74 65 33 5f 66 69 6c 65 20 2a 2f 0a 20 20  lite3_file */.  
db20: 69 6e 74 20 6d 78 50 61 74 68 6e 61 6d 65 3b 20  int mxPathname; 
db30: 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69           /* Maxi
db40: 6d 75 6d 20 66 69 6c 65 20 70 61 74 68 6e 61 6d  mum file pathnam
db50: 65 20 6c 65 6e 67 74 68 20 2a 2f 0a 20 20 73 71  e length */.  sq
db60: 6c 69 74 65 33 5f 76 66 73 20 2a 70 4e 65 78 74  lite3_vfs *pNext
db70: 3b 20 20 20 20 20 20 2f 2a 20 4e 65 78 74 20 72  ;      /* Next r
db80: 65 67 69 73 74 65 72 65 64 20 56 46 53 20 2a 2f  egistered VFS */
db90: 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
dba0: 4e 61 6d 65 3b 20 20 20 20 20 20 20 2f 2a 20 4e  Name;       /* N
dbb0: 61 6d 65 20 6f 66 20 74 68 69 73 20 76 69 72 74  ame of this virt
dbc0: 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 20  ual file system 
dbd0: 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 44  */.  void *pAppD
dbe0: 61 74 61 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  ata;          /*
dbf0: 20 50 6f 69 6e 74 65 72 20 74 6f 20 61 70 70 6c   Pointer to appl
dc00: 69 63 61 74 69 6f 6e 2d 73 70 65 63 69 66 69 63  ication-specific
dc10: 20 64 61 74 61 20 2a 2f 0a 20 20 69 6e 74 20 28   data */.  int (
dc20: 2a 78 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f  *xOpen)(sqlite3_
dc30: 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  vfs*, const char
dc40: 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74 65 33   *zName, sqlite3
dc50: 5f 66 69 6c 65 2a 2c 0a 20 20 20 20 20 20 20 20  _file*,.        
dc60: 20 20 20 20 20 20 20 69 6e 74 20 66 6c 61 67 73         int flags
dc70: 2c 20 69 6e 74 20 2a 70 4f 75 74 46 6c 61 67 73  , int *pOutFlags
dc80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 65 6c 65  );.  int (*xDele
dc90: 74 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  te)(sqlite3_vfs*
dca0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcb0: 61 6d 65 2c 20 69 6e 74 20 73 79 6e 63 44 69 72  ame, int syncDir
dcc0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 41 63 63 65  );.  int (*xAcce
dcd0: 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ss)(sqlite3_vfs*
dce0: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
dcf0: 61 6d 65 2c 20 69 6e 74 20 66 6c 61 67 73 2c 20  ame, int flags, 
dd00: 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a 20  int *pResOut);. 
dd10: 20 69 6e 74 20 28 2a 78 46 75 6c 6c 50 61 74 68   int (*xFullPath
dd20: 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 66  name)(sqlite3_vf
dd30: 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  s*, const char *
dd40: 7a 4e 61 6d 65 2c 20 69 6e 74 20 6e 4f 75 74 2c  zName, int nOut,
dd50: 20 63 68 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20   char *zOut);.  
dd60: 76 6f 69 64 20 2a 28 2a 78 44 6c 4f 70 65 6e 29  void *(*xDlOpen)
dd70: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
dd80: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65  onst char *zFile
dd90: 6e 61 6d 65 29 3b 0a 20 20 76 6f 69 64 20 28 2a  name);.  void (*
dda0: 78 44 6c 45 72 72 6f 72 29 28 73 71 6c 69 74 65  xDlError)(sqlite
ddb0: 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6e 42 79 74  3_vfs*, int nByt
ddc0: 65 2c 20 63 68 61 72 20 2a 7a 45 72 72 4d 73 67  e, char *zErrMsg
ddd0: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 28 2a 78 44  );.  void (*(*xD
dde0: 6c 53 79 6d 29 28 73 71 6c 69 74 65 33 5f 76 66  lSym)(sqlite3_vf
ddf0: 73 2a 2c 76 6f 69 64 2a 2c 20 63 6f 6e 73 74 20  s*,void*, const 
de00: 63 68 61 72 20 2a 7a 53 79 6d 62 6f 6c 29 29 28  char *zSymbol))(
de10: 76 6f 69 64 29 3b 0a 20 20 76 6f 69 64 20 28 2a  void);.  void (*
de20: 78 44 6c 43 6c 6f 73 65 29 28 73 71 6c 69 74 65  xDlClose)(sqlite
de30: 33 5f 76 66 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a  3_vfs*, void*);.
de40: 20 20 69 6e 74 20 28 2a 78 52 61 6e 64 6f 6d 6e    int (*xRandomn
de50: 65 73 73 29 28 73 71 6c 69 74 65 33 5f 76 66 73  ess)(sqlite3_vfs
de60: 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68  *, int nByte, ch
de70: 61 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 69 6e 74  ar *zOut);.  int
de80: 20 28 2a 78 53 6c 65 65 70 29 28 73 71 6c 69 74   (*xSleep)(sqlit
de90: 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20 6d 69 63  e3_vfs*, int mic
dea0: 72 6f 73 65 63 6f 6e 64 73 29 3b 0a 20 20 69 6e  roseconds);.  in
deb0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dec0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
ded0: 64 6f 75 62 6c 65 2a 29 3b 0a 20 20 69 6e 74 20  double*);.  int 
dee0: 28 2a 78 47 65 74 4c 61 73 74 45 72 72 6f 72 29  (*xGetLastError)
def0: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
df00: 6e 74 2c 20 63 68 61 72 20 2a 29 3b 0a 20 20 2f  nt, char *);.  /
df10: 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68 6f  *.  ** The metho
df20: 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e 20  ds above are in 
df30: 76 65 72 73 69 6f 6e 20 31 20 6f 66 20 74 68 65  version 1 of the
df40: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
df50: 63 74 0a 20 20 2a 2a 20 64 65 66 69 6e 69 74 69  ct.  ** definiti
df60: 6f 6e 2e 20 20 54 68 6f 73 65 20 74 68 61 74 20  on.  Those that 
df70: 66 6f 6c 6c 6f 77 20 61 72 65 20 61 64 64 65 64  follow are added
df80: 20 69 6e 20 76 65 72 73 69 6f 6e 20 32 20 6f 72   in version 2 or
df90: 20 6c 61 74 65 72 0a 20 20 2a 2f 0a 20 20 69 6e   later.  */.  in
dfa0: 74 20 28 2a 78 43 75 72 72 65 6e 74 54 69 6d 65  t (*xCurrentTime
dfb0: 49 6e 74 36 34 29 28 73 71 6c 69 74 65 33 5f 76  Int64)(sqlite3_v
dfc0: 66 73 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  fs*, sqlite3_int
dfd0: 36 34 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  64*);.  /*.  ** 
dfe0: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
dff0: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
e000: 73 20 31 20 61 6e 64 20 32 20 6f 66 20 74 68 65  s 1 and 2 of the
e010: 20 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65   sqlite_vfs obje
e020: 63 74 2e 0a 20 20 2a 2a 20 54 68 6f 73 65 20 62  ct..  ** Those b
e030: 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
e040: 73 69 6f 6e 20 33 20 61 6e 64 20 67 72 65 61 74  sion 3 and great
e050: 65 72 2e 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28  er..  */.  int (
e060: 2a 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 29  *xSetSystemCall)
e070: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
e080: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
e090: 2c 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c  , sqlite3_syscal
e0a0: 6c 5f 70 74 72 29 3b 0a 20 20 73 71 6c 69 74 65  l_ptr);.  sqlite
e0b0: 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 20 28 2a  3_syscall_ptr (*
e0c0: 78 47 65 74 53 79 73 74 65 6d 43 61 6c 6c 29 28  xGetSystemCall)(
e0d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
e0e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
e0f0: 3b 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ;.  const char *
e100: 28 2a 78 4e 65 78 74 53 79 73 74 65 6d 43 61 6c  (*xNextSystemCal
e110: 6c 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  l)(sqlite3_vfs*,
e120: 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
e130: 6d 65 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54  me);.  /*.  ** T
e140: 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65  he methods above
e150: 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e 73   are in versions
e160: 20 31 20 74 68 72 6f 75 67 68 20 33 20 6f 66 20   1 through 3 of 
e170: 74 68 65 20 73 71 6c 69 74 65 5f 76 66 73 20 6f  the sqlite_vfs o
e180: 62 6a 65 63 74 2e 0a 20 20 2a 2a 20 4e 65 77 20  bject..  ** New 
e190: 66 69 65 6c 64 73 20 6d 61 79 20 62 65 20 61 70  fields may be ap
e1a0: 70 65 6e 64 65 64 20 69 6e 20 66 69 67 75 72 65  pended in figure
e1b0: 20 76 65 72 73 69 6f 6e 73 2e 20 20 54 68 65 20   versions.  The 
e1c0: 69 56 65 72 73 69 6f 6e 0a 20 20 2a 2a 20 76 61  iVersion.  ** va
e1d0: 6c 75 65 20 77 69 6c 6c 20 69 6e 63 72 65 6d 65  lue will increme
e1e0: 6e 74 20 77 68 65 6e 65 76 65 72 20 74 68 69 73  nt whenever this
e1f0: 20 68 61 70 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a   happens. .  */.
e200: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
e210: 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68  EF: Flags for th
e220: 65 20 78 41 63 63 65 73 73 20 56 46 53 20 6d 65  e xAccess VFS me
e230: 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  thod.**.** These
e240: 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e   integer constan
e250: 74 73 20 63 61 6e 20 62 65 20 75 73 65 64 20 61  ts can be used a
e260: 73 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  s the third para
e270: 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20  meter to.** the 
e280: 78 41 63 63 65 73 73 20 6d 65 74 68 6f 64 20 6f  xAccess method o
e290: 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  f an [sqlite3_vf
e2a0: 73 5d 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 79  s] object.  They
e2b0: 20 64 65 74 65 72 6d 69 6e 65 0a 2a 2a 20 77 68   determine.** wh
e2c0: 61 74 20 6b 69 6e 64 20 6f 66 20 70 65 72 6d 69  at kind of permi
e2d0: 73 73 69 6f 6e 73 20 74 68 65 20 78 41 63 63 65  ssions the xAcce
e2e0: 73 73 20 6d 65 74 68 6f 64 20 69 73 20 6c 6f 6f  ss method is loo
e2f0: 6b 69 6e 67 20 66 6f 72 2e 0a 2a 2a 20 57 69 74  king for..** Wit
e300: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e310: 45 58 49 53 54 53 2c 20 74 68 65 20 78 41 63 63  EXISTS, the xAcc
e320: 65 73 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 73 69  ess method.** si
e330: 6d 70 6c 79 20 63 68 65 63 6b 73 20 77 68 65 74  mply checks whet
e340: 68 65 72 20 74 68 65 20 66 69 6c 65 20 65 78 69  her the file exi
e350: 73 74 73 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c  sts..** With SQL
e360: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
e370: 52 49 54 45 2c 20 74 68 65 20 78 41 63 63 65 73  RITE, the xAcces
e380: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e390: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 6e  ks whether the n
e3a0: 61 6d 65 64 20 64 69 72 65 63 74 6f 72 79 20 69  amed directory i
e3b0: 73 20 62 6f 74 68 20 72 65 61 64 61 62 6c 65 20  s both readable 
e3c0: 61 6e 64 20 77 72 69 74 61 62 6c 65 0a 2a 2a 20  and writable.** 
e3d0: 28 69 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c  (in other words,
e3e0: 20 69 66 20 66 69 6c 65 73 20 63 61 6e 20 62 65   if files can be
e3f0: 20 61 64 64 65 64 2c 20 72 65 6d 6f 76 65 64 2c   added, removed,
e400: 20 61 6e 64 20 72 65 6e 61 6d 65 64 20 77 69 74   and renamed wit
e410: 68 69 6e 0a 2a 2a 20 74 68 65 20 64 69 72 65 63  hin.** the direc
e420: 74 6f 72 79 29 2e 0a 2a 2a 20 54 68 65 20 53 51  tory)..** The SQ
e430: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
e440: 57 52 49 54 45 20 63 6f 6e 73 74 61 6e 74 20 69  WRITE constant i
e450: 73 20 63 75 72 72 65 6e 74 6c 79 20 75 73 65 64  s currently used
e460: 20 6f 6e 6c 79 20 62 79 20 74 68 65 0a 2a 2a 20   only by the.** 
e470: 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65  [temp_store_dire
e480: 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 74  ctory pragma], t
e490: 68 6f 75 67 68 20 74 68 69 73 20 63 6f 75 6c 64  hough this could
e4a0: 20 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74   change in a fut
e4b0: 75 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f  ure.** release o
e4c0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 57 69 74  f SQLite..** Wit
e4d0: 68 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  h SQLITE_ACCESS_
e4e0: 52 45 41 44 2c 20 74 68 65 20 78 41 63 63 65 73  READ, the xAcces
e4f0: 73 20 6d 65 74 68 6f 64 0a 2a 2a 20 63 68 65 63  s method.** chec
e500: 6b 73 20 77 68 65 74 68 65 72 20 74 68 65 20 66  ks whether the f
e510: 69 6c 65 20 69 73 20 72 65 61 64 61 62 6c 65 2e  ile is readable.
e520: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43 43    The SQLITE_ACC
e530: 45 53 53 5f 52 45 41 44 20 63 6f 6e 73 74 61 6e  ESS_READ constan
e540: 74 20 69 73 0a 2a 2a 20 63 75 72 72 65 6e 74 6c  t is.** currentl
e550: 79 20 75 6e 75 73 65 64 2c 20 74 68 6f 75 67 68  y unused, though
e560: 20 69 74 20 6d 69 67 68 74 20 62 65 20 75 73 65   it might be use
e570: 64 20 69 6e 20 61 20 66 75 74 75 72 65 20 72 65  d in a future re
e580: 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
e590: 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
e5a0: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49  QLITE_ACCESS_EXI
e5b0: 53 54 53 20 20 20 20 30 0a 23 64 65 66 69 6e 65  STS    0.#define
e5c0: 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52   SQLITE_ACCESS_R
e5d0: 45 41 44 57 52 49 54 45 20 31 20 20 20 2f 2a 20  EADWRITE 1   /* 
e5e0: 55 73 65 64 20 62 79 20 50 52 41 47 4d 41 20 74  Used by PRAGMA t
e5f0: 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
e600: 6f 72 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ory */.#define S
e610: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
e620: 44 20 20 20 20 20 20 32 20 20 20 2f 2a 20 55 6e  D      2   /* Un
e630: 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  used */../*.** C
e640: 41 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 66  API3REF: Flags f
e650: 6f 72 20 74 68 65 20 78 53 68 6d 4c 6f 63 6b 20  or the xShmLock 
e660: 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a  VFS method.**.**
e670: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
e680: 6f 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20  onstants define 
e690: 74 68 65 20 76 61 72 69 6f 75 73 20 6c 6f 63 6b  the various lock
e6a0: 69 6e 67 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a  ing operations.*
e6b0: 2a 20 61 6c 6c 6f 77 65 64 20 62 79 20 74 68 65  * allowed by the
e6c0: 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64   xShmLock method
e6d0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f   of [sqlite3_io_
e6e0: 6d 65 74 68 6f 64 73 5d 2e 20 20 54 68 65 0a 2a  methods].  The.*
e6f0: 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 72 65 20  * following are 
e700: 74 68 65 20 6f 6e 6c 79 20 6c 65 67 61 6c 20 63  the only legal c
e710: 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 6f 66 20 66  ombinations of f
e720: 6c 61 67 73 20 74 6f 20 74 68 65 0a 2a 2a 20 78  lags to the.** x
e730: 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a  ShmLock method:.
e740: 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
e750: 69 3e 20 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c  i>  SQLITE_SHM_L
e760: 4f 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d  OCK | SQLITE_SHM
e770: 5f 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20  _SHARED.** <li> 
e780: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b   SQLITE_SHM_LOCK
e790: 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58   | SQLITE_SHM_EX
e7a0: 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20  CLUSIVE.** <li> 
e7b0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
e7c0: 43 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f  CK | SQLITE_SHM_
e7d0: 53 48 41 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20  SHARED.** <li>  
e7e0: 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43  SQLITE_SHM_UNLOC
e7f0: 4b 20 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  K | SQLITE_SHM_E
e800: 58 43 4c 55 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c  XCLUSIVE.** </ul
e810: 3e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c  >.**.** When unl
e820: 6f 63 6b 69 6e 67 2c 20 74 68 65 20 73 61 6d 65  ocking, the same
e830: 20 53 48 41 52 45 44 20 6f 72 20 45 58 43 4c 55   SHARED or EXCLU
e840: 53 49 56 45 20 66 6c 61 67 20 6d 75 73 74 20 62  SIVE flag must b
e850: 65 20 73 75 70 70 6c 69 65 64 20 61 73 0a 2a 2a  e supplied as.**
e860: 20 77 61 73 20 67 69 76 65 6e 20 6e 6f 20 74 68   was given no th
e870: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
e880: 6c 6f 63 6b 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68  lock.  .**.** Th
e890: 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f  e xShmLock metho
e8a0: 64 20 63 61 6e 20 74 72 61 6e 73 69 74 69 6f 6e  d can transition
e8b0: 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65   between unlocke
e8c0: 64 20 61 6e 64 20 53 48 41 52 45 44 20 6f 72 0a  d and SHARED or.
e8d0: 2a 2a 20 62 65 74 77 65 65 6e 20 75 6e 6c 6f 63  ** between unloc
e8e0: 6b 65 64 20 61 6e 64 20 45 58 43 4c 55 53 49 56  ked and EXCLUSIV
e8f0: 45 2e 20 20 49 74 20 63 61 6e 6e 6f 74 20 74 72  E.  It cannot tr
e900: 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65 6e  ansition between
e910: 20 53 48 41 52 45 44 0a 2a 2a 20 61 6e 64 20 45   SHARED.** and E
e920: 58 43 4c 55 53 49 56 45 2e 0a 2a 2f 0a 23 64 65  XCLUSIVE..*/.#de
e930: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
e940: 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20 31 0a 23  UNLOCK       1.#
e950: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
e960: 4d 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 32  M_LOCK         2
e970: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
e980: 53 48 4d 5f 53 48 41 52 45 44 20 20 20 20 20 20  SHM_SHARED      
e990: 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   4.#define SQLIT
e9a0: 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45 20  E_SHM_EXCLUSIVE 
e9b0: 20 20 20 38 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49     8../*.** CAPI
e9c0: 33 52 45 46 3a 20 4d 61 78 69 6d 75 6d 20 78 53  3REF: Maximum xS
e9d0: 68 6d 4c 6f 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a  hmLock index.**.
e9e0: 2a 2a 20 54 68 65 20 78 53 68 6d 4c 6f 63 6b 20  ** The xShmLock 
e9f0: 6d 65 74 68 6f 64 20 6f 6e 20 5b 73 71 6c 69 74  method on [sqlit
ea00: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d  e3_io_methods] m
ea10: 61 79 20 75 73 65 20 76 61 6c 75 65 73 0a 2a 2a  ay use values.**
ea20: 20 62 65 74 77 65 65 6e 20 30 20 61 6e 64 20 74   between 0 and t
ea30: 68 69 73 20 75 70 70 65 72 20 62 6f 75 6e 64 20  his upper bound 
ea40: 61 73 20 69 74 73 20 22 6f 66 66 73 65 74 22 20  as its "offset" 
ea50: 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65  argument..** The
ea60: 20 53 51 4c 69 74 65 20 63 6f 72 65 20 77 69 6c   SQLite core wil
ea70: 6c 20 6e 65 76 65 72 20 61 74 74 65 6d 70 74 20  l never attempt 
ea80: 74 6f 20 61 63 71 75 69 72 65 20 6f 72 20 72 65  to acquire or re
ea90: 6c 65 61 73 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20  lease a.** lock 
eaa0: 6f 75 74 73 69 64 65 20 6f 66 20 74 68 69 73 20  outside of this 
eab0: 72 61 6e 67 65 0a 2a 2f 0a 23 64 65 66 69 6e 65  range.*/.#define
eac0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43   SQLITE_SHM_NLOC
ead0: 4b 20 20 20 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a  K        8.../*.
eae0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 69  ** CAPI3REF: Ini
eaf0: 74 69 61 6c 69 7a 65 20 54 68 65 20 53 51 4c 69  tialize The SQLi
eb00: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
eb10: 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e   ^The sqlite3_in
eb20: 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74 69  itialize() routi
eb30: 6e 65 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74  ne initializes t
eb40: 68 65 0a 2a 2a 20 53 51 4c 69 74 65 20 6c 69 62  he.** SQLite lib
eb50: 72 61 72 79 2e 20 20 5e 54 68 65 20 73 71 6c 69  rary.  ^The sqli
eb60: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 72  te3_shutdown() r
eb70: 6f 75 74 69 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f  outine.** deallo
eb80: 63 61 74 65 73 20 61 6e 79 20 72 65 73 6f 75 72  cates any resour
eb90: 63 65 73 20 74 68 61 74 20 77 65 72 65 20 61 6c  ces that were al
eba0: 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
ebb0: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e  e3_initialize().
ebc0: 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
ebd0: 65 73 20 61 72 65 20 64 65 73 69 67 6e 65 64 20  es are designed 
ebe0: 74 6f 20 61 69 64 20 69 6e 20 70 72 6f 63 65 73  to aid in proces
ebf0: 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e  s initialization
ec00: 20 61 6e 64 0a 2a 2a 20 73 68 75 74 64 6f 77 6e   and.** shutdown
ec10: 20 6f 6e 20 65 6d 62 65 64 64 65 64 20 73 79 73   on embedded sys
ec20: 74 65 6d 73 2e 20 20 57 6f 72 6b 73 74 61 74 69  tems.  Workstati
ec30: 6f 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  on applications 
ec40: 75 73 69 6e 67 0a 2a 2a 20 53 51 4c 69 74 65 20  using.** SQLite 
ec50: 6e 6f 72 6d 61 6c 6c 79 20 64 6f 20 6e 6f 74 20  normally do not 
ec60: 6e 65 65 64 20 74 6f 20 69 6e 76 6f 6b 65 20 65  need to invoke e
ec70: 69 74 68 65 72 20 6f 66 20 74 68 65 73 65 20 72  ither of these r
ec80: 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41  outines..**.** A
ec90: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
eca0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
ecb0: 20 61 6e 20 22 65 66 66 65 63 74 69 76 65 22 20   an "effective" 
ecc0: 63 61 6c 6c 20 69 66 20 69 74 20 69 73 0a 2a 2a  call if it is.**
ecd0: 20 74 68 65 20 66 69 72 73 74 20 74 69 6d 65 20   the first time 
ece0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ecf0: 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ze() is invoked 
ed00: 64 75 72 69 6e 67 20 74 68 65 20 6c 69 66 65 74  during the lifet
ed10: 69 6d 65 20 6f 66 0a 2a 2a 20 74 68 65 20 70 72  ime of.** the pr
ed20: 6f 63 65 73 73 2c 20 6f 72 20 69 66 20 69 74 20  ocess, or if it 
ed30: 69 73 20 74 68 65 20 66 69 72 73 74 20 74 69 6d  is the first tim
ed40: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
ed50: 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
ed60: 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  d.** following a
ed70: 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
ed80: 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 5e 28  _shutdown().  ^(
ed90: 4f 6e 6c 79 20 61 6e 20 65 66 66 65 63 74 69 76  Only an effectiv
eda0: 65 20 63 61 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c  e call.** of sql
edb0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
edc0: 29 20 64 6f 65 73 20 61 6e 79 20 69 6e 69 74 69  ) does any initi
edd0: 61 6c 69 7a 61 74 69 6f 6e 2e 20 20 41 6c 6c 20  alization.  All 
ede0: 6f 74 68 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 61  other calls.** a
edf0: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
ee00: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61  ps.)^.**.** A ca
ee10: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
ee20: 75 74 64 6f 77 6e 28 29 20 69 73 20 61 6e 20 22  utdown() is an "
ee30: 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20  effective" call 
ee40: 69 66 20 69 74 20 69 73 20 74 68 65 20 66 69 72  if it is the fir
ee50: 73 74 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 73 71  st.** call to sq
ee60: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
ee70: 20 73 69 6e 63 65 20 74 68 65 20 6c 61 73 74 20   since the last 
ee80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ee90: 7a 65 28 29 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a  ze().  ^(Only.**
eea0: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
eeb0: 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68  ll to sqlite3_sh
eec0: 75 74 64 6f 77 6e 28 29 20 64 6f 65 73 20 61 6e  utdown() does an
eed0: 79 20 64 65 69 6e 69 74 69 61 6c 69 7a 61 74 69  y deinitializati
eee0: 6f 6e 2e 0a 2a 2a 20 41 6c 6c 20 6f 74 68 65 72  on..** All other
eef0: 20 76 61 6c 69 64 20 63 61 6c 6c 73 20 74 6f 20   valid calls to 
ef00: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
ef10: 28 29 20 61 72 65 20 68 61 72 6d 6c 65 73 73 20  () are harmless 
ef20: 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20  no-ops.)^.**.** 
ef30: 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  The sqlite3_init
ef40: 69 61 6c 69 7a 65 28 29 20 69 6e 74 65 72 66 61  ialize() interfa
ef50: 63 65 20 69 73 20 74 68 72 65 61 64 73 61 66 65  ce is threadsafe
ef60: 2c 20 62 75 74 20 73 71 6c 69 74 65 33 5f 73 68  , but sqlite3_sh
ef70: 75 74 64 6f 77 6e 28 29 0a 2a 2a 20 69 73 20 6e  utdown().** is n
ef80: 6f 74 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33  ot.  The sqlite3
ef90: 5f 73 68 75 74 64 6f 77 6e 28 29 20 69 6e 74 65  _shutdown() inte
efa0: 72 66 61 63 65 20 6d 75 73 74 20 6f 6e 6c 79 20  rface must only 
efb0: 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 61  be called from a
efc0: 0a 2a 2a 20 73 69 6e 67 6c 65 20 74 68 72 65 61  .** single threa
efd0: 64 2e 20 20 41 6c 6c 20 6f 70 65 6e 20 5b 64 61  d.  All open [da
efe0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
eff0: 6e 73 5d 20 6d 75 73 74 20 62 65 20 63 6c 6f 73  ns] must be clos
f000: 65 64 20 61 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74  ed and all.** ot
f010: 68 65 72 20 53 51 4c 69 74 65 20 72 65 73 6f 75  her SQLite resou
f020: 72 63 65 73 20 6d 75 73 74 20 62 65 20 64 65 61  rces must be dea
f030: 6c 6c 6f 63 61 74 65 64 20 70 72 69 6f 72 20 74  llocated prior t
f040: 6f 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  o invoking.** sq
f050: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f060: 2e 0a 2a 2a 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74  ..**.** Among ot
f070: 68 65 72 20 74 68 69 6e 67 73 2c 20 5e 73 71 6c  her things, ^sql
f080: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f090: 29 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a  ) will invoke.**
f0a0: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
f0b0: 28 29 2e 20 20 53 69 6d 69 6c 61 72 6c 79 2c 20  ().  Similarly, 
f0c0: 5e 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  ^sqlite3_shutdow
f0d0: 6e 28 29 0a 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f  n().** will invo
f0e0: 6b 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  ke sqlite3_os_en
f0f0: 64 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  d()..**.** ^The 
f100: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
f110: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74  ze() routine ret
f120: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
f130: 20 6f 6e 20 73 75 63 63 65 73 73 2e 0a 2a 2a 20   on success..** 
f140: 5e 49 66 20 66 6f 72 20 73 6f 6d 65 20 72 65 61  ^If for some rea
f150: 73 6f 6e 2c 20 73 71 6c 69 74 65 33 5f 69 6e 69  son, sqlite3_ini
f160: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 75 6e 61  tialize() is una
f170: 62 6c 65 20 74 6f 20 69 6e 69 74 69 61 6c 69 7a  ble to initializ
f180: 65 0a 2a 2a 20 74 68 65 20 6c 69 62 72 61 72 79  e.** the library
f190: 20 28 70 65 72 68 61 70 73 20 69 74 20 69 73 20   (perhaps it is 
f1a0: 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61  unable to alloca
f1b0: 74 65 20 61 20 6e 65 65 64 65 64 20 72 65 73 6f  te a needed reso
f1c0: 75 72 63 65 20 73 75 63 68 0a 2a 2a 20 61 73 20  urce such.** as 
f1d0: 61 20 6d 75 74 65 78 29 20 69 74 20 72 65 74 75  a mutex) it retu
f1e0: 72 6e 73 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  rns an [error co
f1f0: 64 65 5d 20 6f 74 68 65 72 20 74 68 61 6e 20 5b  de] other than [
f200: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
f210: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
f220: 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f 75 74  nitialize() rout
f230: 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 69 6e  ine is called in
f240: 74 65 72 6e 61 6c 6c 79 20 62 79 20 6d 61 6e 79  ternally by many
f250: 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69 74 65   other.** SQLite
f260: 20 69 6e 74 65 72 66 61 63 65 73 20 73 6f 20 74   interfaces so t
f270: 68 61 74 20 61 6e 20 61 70 70 6c 69 63 61 74 69  hat an applicati
f280: 6f 6e 20 75 73 75 61 6c 6c 79 20 64 6f 65 73 20  on usually does 
f290: 6e 6f 74 20 6e 65 65 64 20 74 6f 0a 2a 2a 20 69  not need to.** i
f2a0: 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e  nvoke sqlite3_in
f2b0: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
f2c0: 74 6c 79 2e 20 20 46 6f 72 20 65 78 61 6d 70 6c  tly.  For exampl
f2d0: 65 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  e, [sqlite3_open
f2e0: 28 29 5d 0a 2a 2a 20 63 61 6c 6c 73 20 73 71 6c  ()].** calls sql
f2f0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f300: 29 20 73 6f 20 74 68 65 20 53 51 4c 69 74 65 20  ) so the SQLite 
f310: 6c 69 62 72 61 72 79 20 77 69 6c 6c 20 62 65 20  library will be 
f320: 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a  automatically.**
f330: 20 69 6e 69 74 69 61 6c 69 7a 65 64 20 77 68 65   initialized whe
f340: 6e 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  n [sqlite3_open(
f350: 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 69 66 20  )] is called if 
f360: 69 74 20 68 61 73 20 6e 6f 74 20 62 65 20 69 6e  it has not be in
f370: 69 74 69 61 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72  itialized.** alr
f380: 65 61 64 79 2e 20 20 5e 48 6f 77 65 76 65 72 2c  eady.  ^However,
f390: 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f   if SQLite is co
f3a0: 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 20  mpiled with the 
f3b0: 5b 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54  [SQLITE_OMIT_AUT
f3c0: 4f 49 4e 49 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c  OINIT].** compil
f3d0: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2c 20 74  e-time option, t
f3e0: 68 65 6e 20 74 68 65 20 61 75 74 6f 6d 61 74 69  hen the automati
f3f0: 63 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  c calls to sqlit
f400: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a  e3_initialize().
f410: 2a 2a 20 61 72 65 20 6f 6d 69 74 74 65 64 20 61  ** are omitted a
f420: 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
f430: 6f 6e 20 6d 75 73 74 20 63 61 6c 6c 20 73 71 6c  on must call sql
f440: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
f450: 29 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 70 72  ) directly.** pr
f460: 69 6f 72 20 74 6f 20 75 73 69 6e 67 20 61 6e 79  ior to using any
f470: 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e   other SQLite in
f480: 74 65 72 66 61 63 65 2e 20 20 46 6f 72 20 6d 61  terface.  For ma
f490: 78 69 6d 75 6d 20 70 6f 72 74 61 62 69 6c 69 74  ximum portabilit
f4a0: 79 2c 0a 2a 2a 20 69 74 20 69 73 20 72 65 63 6f  y,.** it is reco
f4b0: 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 61 70 70  mmended that app
f4c0: 6c 69 63 61 74 69 6f 6e 73 20 61 6c 77 61 79 73  lications always
f4d0: 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f   invoke sqlite3_
f4e0: 69 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20  initialize().** 
f4f0: 64 69 72 65 63 74 6c 79 20 70 72 69 6f 72 20 74  directly prior t
f500: 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65  o using any othe
f510: 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
f520: 63 65 2e 20 20 46 75 74 75 72 65 20 72 65 6c 65  ce.  Future rele
f530: 61 73 65 73 0a 2a 2a 20 6f 66 20 53 51 4c 69 74  ases.** of SQLit
f540: 65 20 6d 61 79 20 72 65 71 75 69 72 65 20 74 68  e may require th
f550: 69 73 2e 20 20 49 6e 20 6f 74 68 65 72 20 77 6f  is.  In other wo
f560: 72 64 73 2c 20 74 68 65 20 62 65 68 61 76 69 6f  rds, the behavio
f570: 72 20 65 78 68 69 62 69 74 65 64 0a 2a 2a 20 77  r exhibited.** w
f580: 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20 63 6f  hen SQLite is co
f590: 6d 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c  mpiled with [SQL
f5a0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
f5b0: 54 5d 20 6d 69 67 68 74 20 62 65 63 6f 6d 65 20  T] might become 
f5c0: 74 68 65 0a 2a 2a 20 64 65 66 61 75 6c 74 20 62  the.** default b
f5d0: 65 68 61 76 69 6f 72 20 69 6e 20 73 6f 6d 65 20  ehavior in some 
f5e0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
f5f0: 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20  f SQLite..**.** 
f600: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69  The sqlite3_os_i
f610: 6e 69 74 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  nit() routine do
f620: 65 73 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73  es operating-sys
f630: 74 65 6d 20 73 70 65 63 69 66 69 63 0a 2a 2a 20  tem specific.** 
f640: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 6f  initialization o
f650: 66 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62  f the SQLite lib
f660: 72 61 72 79 2e 20 20 54 68 65 20 73 71 6c 69 74  rary.  The sqlit
f670: 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 72  e3_os_end().** r
f680: 6f 75 74 69 6e 65 20 75 6e 64 6f 65 73 20 74 68  outine undoes th
f690: 65 20 65 66 66 65 63 74 20 6f 66 20 73 71 6c 69  e effect of sqli
f6a0: 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20  te3_os_init().  
f6b0: 54 79 70 69 63 61 6c 20 74 61 73 6b 73 0a 2a 2a  Typical tasks.**
f6c0: 20 70 65 72 66 6f 72 6d 65 64 20 62 79 20 74 68   performed by th
f6d0: 65 73 65 20 72 6f 75 74 69 6e 65 73 20 69 6e 63  ese routines inc
f6e0: 6c 75 64 65 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  lude allocation 
f6f0: 6f 72 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a  or deallocation.
f700: 2a 2a 20 6f 66 20 73 74 61 74 69 63 20 72 65 73  ** of static res
f710: 6f 75 72 63 65 73 2c 20 69 6e 69 74 69 61 6c 69  ources, initiali
f720: 7a 61 74 69 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c  zation of global
f730: 20 76 61 72 69 61 62 6c 65 73 2c 0a 2a 2a 20 73   variables,.** s
f740: 65 74 74 69 6e 67 20 75 70 20 61 20 64 65 66 61  etting up a defa
f750: 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73  ult [sqlite3_vfs
f760: 5d 20 6d 6f 64 75 6c 65 2c 20 6f 72 20 73 65 74  ] module, or set
f770: 74 69 6e 67 20 75 70 0a 2a 2a 20 61 20 64 65 66  ting up.** a def
f780: 61 75 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69  ault configurati
f790: 6f 6e 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  on using [sqlite
f7a0: 33 5f 63 6f 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a  3_config()]..**.
f7b0: 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
f7c0: 6f 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20  on should never 
f7d0: 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 73 71  invoke either sq
f7e0: 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 0a  lite3_os_init().
f7f0: 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  ** or sqlite3_os
f800: 5f 65 6e 64 28 29 20 64 69 72 65 63 74 6c 79 2e  _end() directly.
f810: 20 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f    The applicatio
f820: 6e 20 73 68 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e  n should only in
f830: 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  voke.** sqlite3_
f840: 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 61 6e 64  initialize() and
f850: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
f860: 6e 28 29 2e 20 20 54 68 65 20 73 71 6c 69 74 65  n().  The sqlite
f870: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 69  3_os_init().** i
f880: 6e 74 65 72 66 61 63 65 20 69 73 20 63 61 6c 6c  nterface is call
f890: 65 64 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ed automatically
f8a0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
f8b0: 69 61 6c 69 7a 65 28 29 20 61 6e 64 0a 2a 2a 20  ialize() and.** 
f8c0: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
f8d0: 20 69 73 20 63 61 6c 6c 65 64 20 62 79 20 73 71   is called by sq
f8e0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
f8f0: 2e 20 20 41 70 70 72 6f 70 72 69 61 74 65 0a 2a  .  Appropriate.*
f900: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
f910: 73 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73  s for sqlite3_os
f920: 5f 69 6e 69 74 28 29 20 61 6e 64 20 73 71 6c 69  _init() and sqli
f930: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
f940: 61 72 65 20 62 75 69 6c 74 20 69 6e 74 6f 20 53  are built into S
f950: 51 4c 69 74 65 20 77 68 65 6e 20 69 74 20 69 73  QLite when it is
f960: 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20 55 6e   compiled for Un
f970: 69 78 2c 20 57 69 6e 64 6f 77 73 2c 20 6f 72 20  ix, Windows, or 
f980: 4f 53 2f 32 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63  OS/2..** When [c
f990: 75 73 74 6f 6d 20 62 75 69 6c 64 73 20 7c 20 62  ustom builds | b
f9a0: 75 69 6c 74 20 66 6f 72 20 6f 74 68 65 72 20 70  uilt for other p
f9b0: 6c 61 74 66 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73  latforms].** (us
f9c0: 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
f9d0: 4f 53 5f 4f 54 48 45 52 3d 31 5d 20 63 6f 6d 70  OS_OTHER=1] comp
f9e0: 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69  ile-time.** opti
f9f0: 6f 6e 29 20 74 68 65 20 61 70 70 6c 69 63 61 74  on) the applicat
fa00: 69 6f 6e 20 6d 75 73 74 20 73 75 70 70 6c 79 20  ion must supply 
fa10: 61 20 73 75 69 74 61 62 6c 65 20 69 6d 70 6c 65  a suitable imple
fa20: 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a  mentation for.**
fa30: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fa40: 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f  () and sqlite3_o
fa50: 73 5f 65 6e 64 28 29 2e 20 20 41 6e 20 61 70 70  s_end().  An app
fa60: 6c 69 63 61 74 69 6f 6e 2d 73 75 70 70 6c 69 65  lication-supplie
fa70: 64 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  d.** implementat
fa80: 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f  ion of sqlite3_o
fa90: 73 5f 69 6e 69 74 28 29 20 6f 72 20 73 71 6c 69  s_init() or sqli
faa0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20  te3_os_end().** 
fab0: 6d 75 73 74 20 72 65 74 75 72 6e 20 5b 53 51 4c  must return [SQL
fac0: 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
fad0: 73 73 20 61 6e 64 20 73 6f 6d 65 20 6f 74 68 65  ss and some othe
fae0: 72 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 75  r [error code] u
faf0: 70 6f 6e 0a 2a 2a 20 66 61 69 6c 75 72 65 2e 0a  pon.** failure..
fb00: 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 69  */.int sqlite3_i
fb10: 6e 69 74 69 61 6c 69 7a 65 28 76 6f 69 64 29 3b  nitialize(void);
fb20: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 68 75  .int sqlite3_shu
fb30: 74 64 6f 77 6e 28 76 6f 69 64 29 3b 0a 69 6e 74  tdown(void);.int
fb40: 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74   sqlite3_os_init
fb50: 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69  (void);.int sqli
fb60: 74 65 33 5f 6f 73 5f 65 6e 64 28 76 6f 69 64 29  te3_os_end(void)
fb70: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
fb80: 46 3a 20 43 6f 6e 66 69 67 75 72 69 6e 67 20 54  F: Configuring T
fb90: 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72 61 72  he SQLite Librar
fba0: 79 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  y.**.** The sqli
fbb0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  te3_config() int
fbc0: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
fbd0: 6f 20 6d 61 6b 65 20 67 6c 6f 62 61 6c 20 63 6f  o make global co
fbe0: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
fbf0: 68 61 6e 67 65 73 20 74 6f 20 53 51 4c 69 74 65  hanges to SQLite
fc00: 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 74 75 6e   in order to tun
fc10: 65 20 53 51 4c 69 74 65 20 74 6f 20 74 68 65 20  e SQLite to the 
fc20: 73 70 65 63 69 66 69 63 20 6e 65 65 64 73 20 6f  specific needs o
fc30: 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
fc40: 74 69 6f 6e 2e 20 20 54 68 65 20 64 65 66 61 75  tion.  The defau
fc50: 6c 74 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  lt configuration
fc60: 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20   is recommended 
fc70: 66 6f 72 20 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c  for most.** appl
fc80: 69 63 61 74 69 6f 6e 73 20 61 6e 64 20 73 6f 20  ications and so 
fc90: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20  this routine is 
fca0: 75 73 75 61 6c 6c 79 20 6e 6f 74 20 6e 65 63 65  usually not nece
fcb0: 73 73 61 72 79 2e 20 20 49 74 20 69 73 0a 2a 2a  ssary.  It is.**
fcc0: 20 70 72 6f 76 69 64 65 64 20 74 6f 20 73 75 70   provided to sup
fcd0: 70 6f 72 74 20 72 61 72 65 20 61 70 70 6c 69 63  port rare applic
fce0: 61 74 69 6f 6e 73 20 77 69 74 68 20 75 6e 75 73  ations with unus
fcf0: 75 61 6c 20 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a  ual needs..**.**
fd00: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
fd10: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
fd20: 69 73 20 6e 6f 74 20 74 68 72 65 61 64 73 61 66  is not threadsaf
fd30: 65 2e 20 20 54 68 65 20 61 70 70 6c 69 63 61 74  e.  The applicat
fd40: 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 73 75  ion.** must insu
fd50: 72 65 20 74 68 61 74 20 6e 6f 20 6f 74 68 65 72  re that no other
fd60: 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63   SQLite interfac
fd70: 65 73 20 61 72 65 20 69 6e 76 6f 6b 65 64 20 62  es are invoked b
fd80: 79 20 6f 74 68 65 72 0a 2a 2a 20 74 68 72 65 61  y other.** threa
fd90: 64 73 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  ds while sqlite3
fda0: 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 72 75 6e  _config() is run
fdb0: 6e 69 6e 67 2e 20 20 46 75 72 74 68 65 72 6d 6f  ning.  Furthermo
fdc0: 72 65 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66  re, sqlite3_conf
fdd0: 69 67 28 29 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ig().** may only
fde0: 20 62 65 20 69 6e 76 6f 6b 65 64 20 70 72 69 6f   be invoked prio
fdf0: 72 20 74 6f 20 6c 69 62 72 61 72 79 20 69 6e 69  r to library ini
fe00: 74 69 61 6c 69 7a 61 74 69 6f 6e 20 75 73 69 6e  tialization usin
fe10: 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6e  g.** [sqlite3_in
fe20: 69 74 69 61 6c 69 7a 65 28 29 5d 20 6f 72 20 61  itialize()] or a
fe30: 66 74 65 72 20 73 68 75 74 64 6f 77 6e 20 62 79  fter shutdown by
fe40: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
fe50: 77 6e 28 29 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71  wn()]..** ^If sq
fe60: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
fe70: 73 20 63 61 6c 6c 65 64 20 61 66 74 65 72 20 5b  s called after [
fe80: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
fe90: 7a 65 28 29 5d 20 61 6e 64 20 62 65 66 6f 72 65  ze()] and before
fea0: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  .** [sqlite3_shu
feb0: 74 64 6f 77 6e 28 29 5d 20 74 68 65 6e 20 69 74  tdown()] then it
fec0: 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53 51 4c   will return SQL
fed0: 49 54 45 5f 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e  ITE_MISUSE..** N
fee0: 6f 74 65 2c 20 68 6f 77 65 76 65 72 2c 20 74 68  ote, however, th
fef0: 61 74 20 5e 73 71 6c 69 74 65 33 5f 63 6f 6e 66  at ^sqlite3_conf
ff00: 69 67 28 29 20 63 61 6e 20 62 65 20 63 61 6c 6c  ig() can be call
ff10: 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68  ed as part of th
ff20: 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
ff30: 69 6f 6e 20 6f 66 20 61 6e 20 61 70 70 6c 69 63  ion of an applic
ff40: 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 5b 73  ation-defined [s
ff50: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
ff60: 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72  ]..**.** The fir
ff70: 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  st argument to s
ff80: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
ff90: 69 73 20 61 6e 20 69 6e 74 65 67 65 72 0a 2a 2a  is an integer.**
ffa0: 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   [configuration 
ffb0: 6f 70 74 69 6f 6e 5d 20 74 68 61 74 20 64 65 74  option] that det
ffc0: 65 72 6d 69 6e 65 73 0a 2a 2a 20 77 68 61 74 20  ermines.** what 
ffd0: 70 72 6f 70 65 72 74 79 20 6f 66 20 53 51 4c 69  property of SQLi
ffe0: 74 65 20 69 73 20 74 6f 20 62 65 20 63 6f 6e 66  te is to be conf
fff0: 69 67 75 72 65 64 2e 20 20 53 75 62 73 65 71 75  igured.  Subsequ
10000 65 6e 74 20 61 72 67 75 6d 65 6e 74 73 0a 2a 2a  ent arguments.**
10010 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
10020 6f 6e 20 74 68 65 20 5b 63 6f 6e 66 69 67 75 72  on the [configur
10030 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a  ation option].**
10040 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10050 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57  gument..**.** ^W
10060 68 65 6e 20 61 20 63 6f 6e 66 69 67 75 72 61 74  hen a configurat
10070 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20 73 65  ion option is se
10080 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  t, sqlite3_confi
10090 67 28 29 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  g() returns [SQL
100a0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20  ITE_OK]..** ^If 
100b0 74 68 65 20 6f 70 74 69 6f 6e 20 69 73 20 75 6e  the option is un
100c0 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69 74 65 20  known or SQLite 
100d0 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 73 65 74  is unable to set
100e0 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74   the option.** t
100f0 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
10100 20 72 65 74 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a   returns a non-z
10110 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ero [error code]
10120 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
10130 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20 2e 2e 2e  _config(int, ...
10140 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
10150 45 46 3a 20 43 6f 6e 66 69 67 75 72 65 20 64 61  EF: Configure da
10160 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10170 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  ns.**.** The sql
10180 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
10190 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 75 73   interface is us
101a0 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f 6e 66 69  ed to make confi
101b0 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e  guration.** chan
101c0 67 65 73 20 74 6f 20 61 20 5b 64 61 74 61 62 61  ges to a [databa
101d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
101e0 20 54 68 65 20 69 6e 74 65 72 66 61 63 65 20 69   The interface i
101f0 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20  s similar to.** 
10200 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10210 29 5d 20 65 78 63 65 70 74 20 74 68 61 74 20 74  )] except that t
10220 68 65 20 63 68 61 6e 67 65 73 20 61 70 70 6c 79  he changes apply
10230 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a 2a 2a 20   to a single.** 
10240 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
10250 74 69 6f 6e 5d 20 28 73 70 65 63 69 66 69 65 64  tion] (specified
10260 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
10270 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54  gument)..**.** T
10280 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
10290 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62  nt to sqlite3_db
102a0 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e 2e 2e 29  _config(D,V,...)
102b0 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b 53 51 4c    is the.** [SQL
102c0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
102d0 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66 69 67 75  KASIDE | configu
102e0 72 61 74 69 6f 6e 20 76 65 72 62 5d 20 2d 20 61  ration verb] - a
102f0 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20 0a  n integer code .
10300 2a 2a 20 74 68 61 74 20 69 6e 64 69 63 61 74 65  ** that indicate
10310 73 20 77 68 61 74 20 61 73 70 65 63 74 20 6f 66  s what aspect of
10320 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
10330 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73 20 62 65  onnection] is be
10340 69 6e 67 20 63 6f 6e 66 69 67 75 72 65 64 2e 0a  ing configured..
10350 2a 2a 20 53 75 62 73 65 71 75 65 6e 74 20 61 72  ** Subsequent ar
10360 67 75 6d 65 6e 74 73 20 76 61 72 79 20 64 65 70  guments vary dep
10370 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 63 6f  ending on the co
10380 6e 66 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62  nfiguration verb
10390 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ..**.** ^Calls t
103a0 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
103b0 66 69 67 28 29 20 72 65 74 75 72 6e 20 53 51 4c  fig() return SQL
103c0 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64 20 6f 6e  ITE_OK if and on
103d0 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20 63 61 6c  ly if.** the cal
103e0 6c 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  l is considered 
103f0 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69  successful..*/.i
10400 6e 74 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f  nt sqlite3_db_co
10410 6e 66 69 67 28 73 71 6c 69 74 65 33 2a 2c 20 69  nfig(sqlite3*, i
10420 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a  nt op, ...);../*
10430 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65  .** CAPI3REF: Me
10440 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20  mory Allocation 
10450 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41  Routines.**.** A
10460 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
10470 69 73 20 6f 62 6a 65 63 74 20 64 65 66 69 6e 65  is object define
10480 73 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20  s the interface 
10490 62 65 74 77 65 65 6e 20 53 51 4c 69 74 65 0a 2a  between SQLite.*
104a0 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76 65 6c 20  * and low-level 
104b0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
104c0 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a  n routines..**.*
104d0 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73  * This object is
104e0 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e   used in only on
104f0 65 20 70 6c 61 63 65 20 69 6e 20 74 68 65 20 53  e place in the S
10500 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e  QLite interface.
10510 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72 20 74 6f  .** A pointer to
10520 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20   an instance of 
10530 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 74  this object is t
10540 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a  he argument to.*
10550 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10560 67 28 29 5d 20 77 68 65 6e 20 74 68 65 20 63 6f  g()] when the co
10570 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10580 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c 49 54 45  on is.** [SQLITE
10590 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20  _CONFIG_MALLOC] 
105a0 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
105b0 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a  G_GETMALLOC].  .
105c0 2a 2a 20 42 79 20 63 72 65 61 74 69 6e 67 20 61  ** By creating a
105d0 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  n instance of th
105e0 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20 61 6e 64  is object.** and
105f0 20 70 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b   passing it to [
10600 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 5d 28  sqlite3_config](
10610 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10620 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75 72 69 6e  ALLOC]).** durin
10630 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 2c  g configuration,
10640 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20   an application 
10650 63 61 6e 20 73 70 65 63 69 66 79 20 61 6e 20 61  can specify an a
10660 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
10670 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
10680 73 75 62 73 79 73 74 65 6d 20 66 6f 72 20 53 51  subsystem for SQ
10690 4c 69 74 65 20 74 6f 20 75 73 65 20 66 6f 72 20  Lite to use for 
106a0 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a 20 64 79  all of its.** dy
106b0 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20 6e 65 65  namic memory nee
106c0 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  ds..**.** Note t
106d0 68 61 74 20 53 51 4c 69 74 65 20 63 6f 6d 65 73  hat SQLite comes
106e0 20 77 69 74 68 20 73 65 76 65 72 61 6c 20 5b 62   with several [b
106f0 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61  uilt-in memory a
10700 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a 20 74 68  llocators].** th
10710 61 74 20 61 72 65 20 70 65 72 66 65 63 74 6c 79  at are perfectly
10720 20 61 64 65 71 75 61 74 65 20 66 6f 72 20 74 68   adequate for th
10730 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e 67 20 6d  e overwhelming m
10740 61 6a 6f 72 69 74 79 20 6f 66 20 61 70 70 6c 69  ajority of appli
10750 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74  cations.** and t
10760 68 61 74 20 74 68 69 73 20 6f 62 6a 65 63 74 20  hat this object 
10770 69 73 20 6f 6e 6c 79 20 75 73 65 66 75 6c 20 74  is only useful t
10780 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f 72 69 74  o a tiny minorit
10790 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e  y of application
107a0 73 0a 2a 2a 20 77 69 74 68 20 73 70 65 63 69 61  s.** with specia
107b0 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  lized memory all
107c0 6f 63 61 74 69 6f 6e 20 72 65 71 75 69 72 65 6d  ocation requirem
107d0 65 6e 74 73 2e 20 20 54 68 69 73 20 6f 62 6a 65  ents.  This obje
107e0 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f 20 75 73  ct is.** also us
107f0 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69 6e  ed during testin
10800 67 20 6f 66 20 53 51 4c 69 74 65 20 69 6e 20 6f  g of SQLite in o
10810 72 64 65 72 20 74 6f 20 73 70 65 63 69 66 79 20  rder to specify 
10820 61 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a  an alternative.*
10830 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
10840 6f 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74 65  or that simulate
10850 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d  s memory out-of-
10860 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74 69 6f 6e  memory condition
10870 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72 20 74 6f  s in.** order to
10880 20 76 65 72 69 66 79 20 74 68 61 74 20 53 51 4c   verify that SQL
10890 69 74 65 20 72 65 63 6f 76 65 72 73 20 67 72 61  ite recovers gra
108a0 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20 73 75 63  cefully from suc
108b0 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f 6e 73 2e  h.** conditions.
108c0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d 61 6c 6c  .**.** The xMall
108d0 6f 63 2c 20 78 52 65 61 6c 6c 6f 63 2c 20 61 6e  oc, xRealloc, an
108e0 64 20 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20  d xFree methods 
108f0 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74  must work like t
10900 68 65 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20  he.** malloc(), 
10910 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72  realloc() and fr
10920 65 65 28 29 20 66 75 6e 63 74 69 6f 6e 73 20 66  ee() functions f
10930 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
10940 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 5e   C library..** ^
10950 53 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65  SQLite guarantee
10960 73 20 74 68 61 74 20 74 68 65 20 73 65 63 6f 6e  s that the secon
10970 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
10980 20 78 52 65 61 6c 6c 6f 63 20 69 73 20 61 6c 77   xRealloc is alw
10990 61 79 73 20 61 20 76 61 6c 75 65 20 72 65 74 75  ays a value retu
109a0 72 6e 65 64 20 62 79 20 61 20 70 72 69 6f 72 20  rned by a prior 
109b0 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e 64 75 70  call to xRoundup
109c0 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
109d0 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
109e0 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
109f0 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
10a00 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
10a10 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
10a20 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
10a30 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
10a40 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
10a50 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
10a60 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
10a70 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
10a80 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
10a90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
10aa0 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
10ab0 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
10ac0 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
10ad0 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
10ae0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
10af0 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
10b00 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
10b10 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
10b20 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
10b30 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
10b40 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
10b50 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
10b60 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
10b70 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
10b80 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
10b90 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
10ba0 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
10bb0 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
10bc0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
10bd0 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
10be0 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
10bf0 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
10c00 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
10c10 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
10c20 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
10c30 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
10c40 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
10c50 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
10c60 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
10c70 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
10c80 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
10c90 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
10ca0 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
10cb0 6f 63 61 74 6f 72 2e 20 20 46 6f 72 20 65 78 61  ocator.  For exa
10cc0 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68  mple,.** it migh
10cd0 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72  t allocate any r
10ce0 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20 6f  equire mutexes o
10cf0 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74  r initialize int
10d00 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74  ernal data.** st
10d10 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20 78  ructures.  The x
10d20 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10d30 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69  is invoked (indi
10d40 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73  rectly) by.** [s
10d50 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
10d60 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64 65  )] and should de
10d70 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 73  allocate any res
10d80 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64 0a  ources acquired.
10d90 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54 68  ** by xInit.  Th
10da0 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e 74  e pAppData point
10db0 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74 68  er is used as th
10dc0 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72  e only parameter
10dd0 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64   to.** xInit and
10de0 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a   xShutdown..**.*
10df0 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20 74  * SQLite holds t
10e00 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58  he [SQLITE_MUTEX
10e10 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d 20  _STATIC_MASTER] 
10e20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69 6e  mutex when it in
10e30 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e  vokes.** the xIn
10e40 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68  it method, so th
10e50 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e  e xInit method n
10e60 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65 61  eed not be threa
10e70 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78  dsafe.  The.** x
10e80 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20  Shutdown method 
10e90 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66  is only called f
10ea0 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68 75  rom [sqlite3_shu
10eb0 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20 64  tdown()] so it d
10ec0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20  oes.** not need 
10ed0 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66 65  to be threadsafe
10ee0 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61 6c   either.  For al
10ef0 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73 2c  l other methods,
10f00 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73   SQLite.** holds
10f10 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54   the [SQLITE_MUT
10f20 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d  EX_STATIC_MEM] m
10f30 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73 20  utex as long as 
10f40 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43  the.** [SQLITE_C
10f50 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
10f60 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
10f70 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20  ption is turned 
10f80 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74 20  on (which.** it 
10f90 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20 61  is by default) a
10fa0 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f 64  nd so the method
10fb0 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63 61  s are automatica
10fc0 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a  lly serialized..
10fd0 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20 5b  ** However, if [
10fe0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45  SQLITE_CONFIG_ME
10ff0 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73 61  MSTATUS] is disa
11000 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f  bled, then the o
11010 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20  ther.** methods 
11020 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73 61  must be threadsa
11030 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20  fe or else make 
11040 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e 67  their own arrang
11050 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65  ements for.** se
11060 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a  rialization..**.
11070 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e  ** SQLite will n
11080 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69  ever invoke xIni
11090 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e  t() more than on
110a0 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69 6e  ce without an in
110b0 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c  tervening.** cal
110c0 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28 29  l to xShutdown()
110d0 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  ..*/.typedef str
110e0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
110f0 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
11100 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72  mem_methods;.str
11110 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  uct sqlite3_mem_
11120 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64  methods {.  void
11130 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74   *(*xMalloc)(int
11140 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 65  );         /* Me
11150 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
11160 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  function */.  vo
11170 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69 64  id (*xFree)(void
11180 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  *);          /* 
11190 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c 6c  Free a prior all
111a0 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69  ocation */.  voi
111b0 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76  d *(*xRealloc)(v
111c0 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52  oid*,int);  /* R
111d0 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74  esize an allocat
111e0 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  ion */.  int (*x
111f0 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20 20  Size)(void*);   
11200 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75 72          /* Retur
11210 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61 6e  n the size of an
11220 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20   allocation */. 
11230 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70 29   int (*xRoundup)
11240 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20 20  (int);          
11250 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71 75  /* Round up requ
11260 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f  est size to allo
11270 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20  cation size */. 
11280 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76 6f   int (*xInit)(vo
11290 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20  id*);           
112a0 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74 68  /* Initialize th
112b0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
112c0 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78  or */.  void (*x
112d0 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29  Shutdown)(void*)
112e0 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69 74  ;      /* Deinit
112f0 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72  ialize the memor
11300 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20  y allocator */. 
11310 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
11320 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
11330 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20 78  /* Argument to x
11340 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75 74  Init() and xShut
11350 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a  down() */.};../*
11360 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
11370 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
11380 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ons.** KEYWORDS:
11390 20 7b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20   {configuration 
113a0 6f 70 74 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68  option}.**.** Th
113b0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72  ese constants ar
113c0 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c 65 20  e the available 
113d0 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67 75 72  integer configur
113e0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68  ation options th
113f0 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70 61 73  at.** can be pas
11400 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
11410 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
11420 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
11430 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
11440 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
11450 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
11460 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
11470 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
11480 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
11490 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
114a0 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
114b0 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
114c0 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
114d0 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
114e0 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
114f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63   from [sqlite3_c
11500 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65  onfig()] to make
11510 20 73 75 72 65 20 74 68 61 74 0a 2a 2a 20 74 68   sure that.** th
11520 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20  e call worked.  
11530 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  The [sqlite3_con
11540 66 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65  fig()] interface
11550 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a   will return a.*
11560 2a 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f  * non-zero [erro
11570 72 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73  r code] if a dis
11580 63 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73  continued or uns
11590 75 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75  upported configu
115a0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a  ration option.**
115b0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a   is invoked..**.
115c0 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c  ** <dl>.** [[SQL
115d0 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
115e0 45 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51  ETHREAD]] <dt>SQ
115f0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
11600 4c 45 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  LETHREAD</dt>.**
11610 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
11620 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
11630 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
11640 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
11650 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
11660 20 6d 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65   mode] to Single
11670 2d 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68  -thread.  In oth
11680 65 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73  er words, it dis
11690 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74  ables.** all mut
116a0 65 78 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53  exing and puts S
116b0 51 4c 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64  QLite into a mod
116c0 65 20 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f  e where it can o
116d0 6e 6c 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62  nly be used.** b
116e0 79 20 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61  y a single threa
116f0 64 2e 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20  d.   ^If SQLite 
11700 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  is compiled with
11710 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  .** the [SQLITE_
11720 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c  THREADSAFE | SQL
11730 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30  ITE_THREADSAFE=0
11740 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
11750 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74  ption then.** it
11760 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65   is not possible
11770 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b   to change the [
11780 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
11790 66 72 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74  from its default
117a0 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e  .** value of Sin
117b0 67 6c 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73  gle-thread and s
117c0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
117d0 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e  g()] will return
117e0 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52   .** [SQLITE_ERR
117f0 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69  OR] if called wi
11800 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f  th the SQLITE_CO
11810 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
11820 44 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69  D.** configurati
11830 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a  on option.</dd>.
11840 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11850 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11860 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11870 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
11880 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
11890 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
118a0 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
118b0 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
118c0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
118d0 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
118e0 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
118f0 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
11900 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
11910 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
11920 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
11930 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
11940 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
11950 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
11960 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
11970 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
11980 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
11990 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
119a0 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
119b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
119c0 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
119d0 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
119e0 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
119f0 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
11a00 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
11a10 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
11a20 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
11a30 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
11a40 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
11a50 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
11a60 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
11a70 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
11a80 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
11a90 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
11aa0 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
11ab0 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
11ac0 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
11ad0 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
11ae0 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
11af0 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
11b00 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
11b10 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
11b20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
11b30 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
11b40 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
11b50 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11b60 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
11b70 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
11b80 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
11b90 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
11ba0 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
11bb0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
11bc0 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45  CONFIG_SERIALIZE
11bd0 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  D]] <dt>SQLITE_C
11be0 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11bf0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
11c00 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65  re are no argume
11c10 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69  nts to this opti
11c20 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f  on.  ^This optio
11c30 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74  n sets the.** [t
11c40 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74  hreading mode] t
11c50 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e  o Serialized. In
11c60 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
11c70 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65  is option enable
11c80 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73  s.** all mutexes
11c90 20 69 6e 63 6c 75 64 69 6e 67 20 74 68 65 20 72   including the r
11ca0 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65  ecursive.** mute
11cb0 78 65 73 20 6f 6e 20 5b 64 61 74 61 62 61 73 65  xes on [database
11cc0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64   connection] and
11cd0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
11ce0 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a  ment] objects..*
11cf0 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64 65 20 28  * In this mode (
11d00 77 68 69 63 68 20 69 73 20 74 68 65 20 64 65 66  which is the def
11d10 61 75 6c 74 20 77 68 65 6e 20 53 51 4c 69 74 65  ault when SQLite
11d20 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11d30 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52  h.** [SQLITE_THR
11d40 45 41 44 53 41 46 45 3d 31 5d 29 20 74 68 65 20  EADSAFE=1]) the 
11d50 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79 20 77  SQLite library w
11d60 69 6c 6c 20 69 74 73 65 6c 66 20 73 65 72 69 61  ill itself seria
11d70 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a 2a 20 74  lize access.** t
11d80 6f 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  o [database conn
11d90 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72  ections] and [pr
11da0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
11db0 73 5d 20 73 6f 20 74 68 61 74 20 74 68 65 0a 2a  s] so that the.*
11dc0 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 73  * application is
11dd0 20 66 72 65 65 20 74 6f 20 75 73 65 20 74 68 65   free to use the
11de0 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20   same [database 
11df0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74  connection] or t
11e00 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70  he.** same [prep
11e10 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
11e20 69 6e 20 64 69 66 66 65 72 65 6e 74 20 74 68 72  in different thr
11e30 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d 65  eads at the same
11e40 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51   time..** ^If SQ
11e50 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
11e60 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51   with.** the [SQ
11e70 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20  LITE_THREADSAFE 
11e80 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53  | SQLITE_THREADS
11e90 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74  AFE=0] compile-t
11ea0 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a  ime option then.
11eb0 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73  ** it is not pos
11ec0 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  sible to set the
11ed0 20 53 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72   Serialized [thr
11ee0 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64  eading mode] and
11ef0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  .** [sqlite3_con
11f00 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  fig()] will retu
11f10 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  rn [SQLITE_ERROR
11f20 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
11f30 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43   the.** SQLITE_C
11f40 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44  ONFIG_SERIALIZED
11f50 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11f60 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  ption.</dd>.**.*
11f70 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11f80 47 5f 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53  G_MALLOC]] <dt>S
11f90 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11fa0 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  LOC</dt>.** <dd>
11fb0 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74   ^(This option t
11fc0 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72  akes a single ar
11fd0 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20  gument which is 
11fe0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a  a pointer to an.
11ff0 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74  ** instance of t
12000 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f  he [sqlite3_mem_
12010 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
12020 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
12030 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
12040 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
12050 65 76 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  evel memory allo
12060 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
12070 74 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c  to be used in pl
12080 61 63 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65  ace of.** the me
12090 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
120a0 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
120b0 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53  nto SQLite.)^ ^S
120c0 51 4c 69 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69  QLite makes.** i
120d0 74 73 20 6f 77 6e 20 70 72 69 76 61 74 65 20 63  ts own private c
120e0 6f 70 79 20 6f 66 20 74 68 65 20 63 6f 6e 74 65  opy of the conte
120f0 6e 74 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  nt of the [sqlit
12100 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
12110 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 62 65 66  structure.** bef
12120 6f 72 65 20 74 68 65 20 5b 73 71 6c 69 74 65 33  ore the [sqlite3
12130 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20  _config()] call 
12140 72 65 74 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  returns.</dd>.**
12150 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
12160 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20  FIG_GETMALLOC]] 
12170 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
12180 47 5f 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e  G_GETMALLOC</dt>
12190 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20  .** <dd> ^(This 
121a0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
121b0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77  ingle argument w
121c0 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65  hich is a pointe
121d0 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61  r to an.** insta
121e0 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  nce of the [sqli
121f0 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d  te3_mem_methods]
12200 20 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65   structure.  The
12210 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
12220 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
12230 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
12240 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
12250 20 64 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20   defined memory 
12260 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
12270 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f  nes.)^.** This o
12280 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65  ption can be use
12290 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68  d to overload th
122a0 65 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  e default memory
122b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
122c0 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
122d0 72 61 70 70 65 72 20 74 68 61 74 20 73 69 6d 75  rapper that simu
122e0 6c 61 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61  lations memory a
122f0 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72  llocation failur
12300 65 20 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d  e or.** tracks m
12310 65 6d 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72  emory usage, for
12320 20 65 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a   example. </dd>.
12330 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
12340 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d  ONFIG_MEMSTATUS]
12350 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
12360 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64  FIG_MEMSTATUS</d
12370 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
12380 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 73 69   option takes si
12390 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f 66  ngle argument of
123a0 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74 65 72   type int, inter
123b0 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20  preted as a .** 
123c0 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68 20 65  boolean, which e
123d0 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c  nables or disabl
123e0 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f  es the collectio
123f0 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  n of memory allo
12400 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69  cation .** stati
12410 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65  stics. ^(When me
12420 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12430 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 64  statistics are d
12440 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a  isabled, the .**
12450 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74   following SQLit
12460 65 20 69 6e 74 65 72 66 61 63 65 73 20 62 65 63  e interfaces bec
12470 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f  ome non-operatio
12480 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a  nal:.**   <ul>.*
12490 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
124a0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
124b0 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
124c0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
124d0 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  ater()].**   <li
124e0 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  > [sqlite3_soft_
124f0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
12500 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74  **   <li> [sqlit
12510 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20  e3_status()].** 
12520 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65    </ul>)^.** ^Me
12530 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
12540 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20 65  statistics are e
12550 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c  nabled by defaul
12560 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74 65 20  t unless SQLite 
12570 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77  is.** compiled w
12580 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45 46 41  ith [SQLITE_DEFA
12590 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30  ULT_MEMSTATUS]=0
125a0 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 6d   in which case m
125b0 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74  emory.** allocat
125c0 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73 20 61  ion statistics a
125d0 72 65 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  re disabled by d
125e0 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e  efault..** </dd>
125f0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
12600 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 5d  CONFIG_SCRATCH]]
12610 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12620 49 47 5f 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a  IG_SCRATCH</dt>.
12630 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
12640 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
12650 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
12660 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
12670 65 20 63 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a  e can use for.**
12680 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e   scratch memory.
12690 20 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65    There are thre
126a0 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 20 41 20  e arguments:  A 
126b0 70 6f 69 6e 74 65 72 20 61 6e 20 38 2d 62 79 74  pointer an 8-byt
126c0 65 0a 2a 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d  e.** aligned mem
126d0 6f 72 79 20 62 75 66 66 65 72 20 66 72 6f 6d 20  ory buffer from 
126e0 77 68 69 63 68 20 74 68 65 20 73 63 72 61 74 63  which the scratc
126f0 68 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69  h allocations wi
12700 6c 6c 20 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20  ll be.** drawn, 
12710 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61 63 68  the size of each
12720 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
12730 69 6f 6e 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64  ion (sz),.** and
12740 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d   the maximum num
12750 62 65 72 20 6f 66 20 73 63 72 61 74 63 68 20 61  ber of scratch a
12760 6c 6c 6f 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20  llocations (N). 
12770 20 54 68 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d   The sz.** argum
12780 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 6d 75  ent must be a mu
12790 6c 74 69 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a  ltiple of 16..**
127a0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
127b0 65 6e 74 20 6d 75 73 74 20 62 65 20 61 20 70 6f  ent must be a po
127c0 69 6e 74 65 72 20 74 6f 20 61 6e 20 38 2d 62 79  inter to an 8-by
127d0 74 65 20 61 6c 69 67 6e 65 64 20 62 75 66 66 65  te aligned buffe
127e0 72 0a 2a 2a 20 6f 66 20 61 74 20 6c 65 61 73 74  r.** of at least
127f0 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d   sz*N bytes of m
12800 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74  emory..** ^SQLit
12810 65 20 77 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f  e will use no mo
12820 72 65 20 74 68 61 6e 20 74 77 6f 20 73 63 72 61  re than two scra
12830 74 63 68 20 62 75 66 66 65 72 73 20 70 65 72 20  tch buffers per 
12840 74 68 72 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e  thread.  So.** N
12850 20 73 68 6f 75 6c 64 20 62 65 20 73 65 74 20 74   should be set t
12860 6f 20 74 77 69 63 65 20 74 68 65 20 65 78 70 65  o twice the expe
12870 63 74 65 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  cted maximum num
12880 62 65 72 20 6f 66 20 74 68 72 65 61 64 73 2e 0a  ber of threads..
12890 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
128a0 6e 65 76 65 72 20 72 65 71 75 69 72 65 20 61 20  never require a 
128b0 73 63 72 61 74 63 68 20 62 75 66 66 65 72 20 74  scratch buffer t
128c0 68 61 74 20 69 73 20 6d 6f 72 65 20 74 68 61 6e  hat is more than
128d0 20 36 0a 2a 2a 20 74 69 6d 65 73 20 74 68 65 20   6.** times the 
128e0 64 61 74 61 62 61 73 65 20 70 61 67 65 20 73 69  database page si
128f0 7a 65 2e 20 5e 49 66 20 53 51 4c 69 74 65 20 6e  ze. ^If SQLite n
12900 65 65 64 73 20 6e 65 65 64 73 20 61 64 64 69 74  eeds needs addit
12910 69 6f 6e 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68  ional.** scratch
12920 20 6d 65 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77   memory beyond w
12930 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64 20  hat is provided 
12940 62 79 20 74 68 69 73 20 63 6f 6e 66 69 67 75 72  by this configur
12950 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68  ation option, th
12960 65 6e 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  en .** [sqlite3_
12970 6d 61 6c 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62  malloc()] will b
12980 65 20 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e  e used to obtain
12990 20 74 68 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64   the memory need
129a0 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  ed.</dd>.**.** [
129b0 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
129c0 41 47 45 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53  AGECACHE]] <dt>S
129d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47  QLITE_CONFIG_PAG
129e0 45 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  ECACHE</dt>.** <
129f0 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
12a00 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61   specifies a sta
12a10 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  tic memory buffe
12a20 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 61  r that SQLite ca
12a30 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65  n use for.** the
12a40 20 64 61 74 61 62 61 73 65 20 70 61 67 65 20 63   database page c
12a50 61 63 68 65 20 77 69 74 68 20 74 68 65 20 64 65  ache with the de
12a60 66 61 75 6c 74 20 70 61 67 65 20 63 61 63 68 65  fault page cache
12a70 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
12a80 20 20 0a 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69    .** This confi
12a90 67 75 72 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20  guration should 
12aa0 6e 6f 74 20 62 65 20 75 73 65 64 20 69 66 20 61  not be used if a
12ab0 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
12ac0 66 69 6e 65 20 70 61 67 65 0a 2a 2a 20 63 61 63  fine page.** cac
12ad0 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  he implementatio
12ae0 6e 20 69 73 20 6c 6f 61 64 65 64 20 75 73 69 6e  n is loaded usin
12af0 67 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e  g the SQLITE_CON
12b00 46 49 47 5f 50 43 41 43 48 45 32 20 6f 70 74 69  FIG_PCACHE2 opti
12b10 6f 6e 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  on..** There are
12b20 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
12b30 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a   to this option:
12b40 20 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d   A pointer to 8-
12b50 62 79 74 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20  byte aligned.** 
12b60 6d 65 6d 6f 72 79 2c 20 74 68 65 20 73 69 7a 65  memory, the size
12b70 20 6f 66 20 65 61 63 68 20 70 61 67 65 20 62 75   of each page bu
12b80 66 66 65 72 20 28 73 7a 29 2c 20 61 6e 64 20 74  ffer (sz), and t
12b90 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61 67  he number of pag
12ba0 65 73 20 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73  es (N)..** The s
12bb0 7a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  z argument shoul
12bc0 64 20 62 65 20 74 68 65 20 73 69 7a 65 20 6f 66  d be the size of
12bd0 20 74 68 65 20 6c 61 72 67 65 73 74 20 64 61 74   the largest dat
12be0 61 62 61 73 65 20 70 61 67 65 0a 2a 2a 20 28 61  abase page.** (a
12bf0 20 70 6f 77 65 72 20 6f 66 20 74 77 6f 20 62 65   power of two be
12c00 74 77 65 65 6e 20 35 31 32 20 61 6e 64 20 33 32  tween 512 and 32
12c10 37 36 38 29 20 70 6c 75 73 20 61 20 6c 69 74 74  768) plus a litt
12c20 6c 65 20 65 78 74 72 61 20 66 6f 72 20 65 61 63  le extra for eac
12c30 68 0a 2a 2a 20 70 61 67 65 20 68 65 61 64 65 72  h.** page header
12c40 2e 20 20 5e 54 68 65 20 70 61 67 65 20 68 65 61  .  ^The page hea
12c50 64 65 72 20 73 69 7a 65 20 69 73 20 32 30 20 74  der size is 20 t
12c60 6f 20 34 30 20 62 79 74 65 73 20 64 65 70 65 6e  o 40 bytes depen
12c70 64 69 6e 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68  ding on.** the h
12c80 6f 73 74 20 61 72 63 68 69 74 65 63 74 75 72 65  ost architecture
12c90 2e 20 20 5e 49 74 20 69 73 20 68 61 72 6d 6c 65  .  ^It is harmle
12ca0 73 73 2c 20 61 70 61 72 74 20 66 72 6f 6d 20 74  ss, apart from t
12cb0 68 65 20 77 61 73 74 65 64 20 6d 65 6d 6f 72 79  he wasted memory
12cc0 2c 0a 2a 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20  ,.** to make sz 
12cd0 61 20 6c 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72  a little too lar
12ce0 67 65 2e 20 20 54 68 65 20 66 69 72 73 74 0a 2a  ge.  The first.*
12cf0 2a 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c  * argument shoul
12d00 64 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c  d point to an al
12d10 6c 6f 63 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c  location of at l
12d20 65 61 73 74 20 73 7a 2a 4e 20 62 79 74 65 73 20  east sz*N bytes 
12d30 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53  of memory..** ^S
12d40 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20 74  QLite will use t
12d50 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64  he memory provid
12d60 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
12d70 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 61 74 69  argument to sati
12d80 73 66 79 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72  sfy its.** memor
12d90 79 20 6e 65 65 64 73 20 66 6f 72 20 74 68 65 20  y needs for the 
12da0 66 69 72 73 74 20 4e 20 70 61 67 65 73 20 74 68  first N pages th
12db0 61 74 20 69 74 20 61 64 64 73 20 74 6f 20 63 61  at it adds to ca
12dc0 63 68 65 2e 20 20 5e 49 66 20 61 64 64 69 74 69  che.  ^If additi
12dd0 6f 6e 61 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63  onal.** page cac
12de0 68 65 20 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65  he memory is nee
12df0 64 65 64 20 62 65 79 6f 6e 64 20 77 68 61 74 20  ded beyond what 
12e00 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20 74  is provided by t
12e10 68 69 73 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e  his option, then
12e20 0a 2a 2a 20 53 51 4c 69 74 65 20 67 6f 65 73 20  .** SQLite goes 
12e30 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  to [sqlite3_mall
12e40 6f 63 28 29 5d 20 66 6f 72 20 74 68 65 20 61 64  oc()] for the ad
12e50 64 69 74 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65  ditional storage
12e60 20 73 70 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70   space..** The p
12e70 6f 69 6e 74 65 72 20 69 6e 20 74 68 65 20 66 69  ointer in the fi
12e80 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
12e90 74 0a 2a 2a 20 62 65 20 61 6c 69 67 6e 65 64 20  t.** be aligned 
12ea0 74 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75  to an 8-byte bou
12eb0 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71 75  ndary or subsequ
12ec0 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20  ent behavior of 
12ed0 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62  SQLite.** will b
12ee0 65 20 75 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64  e undefined.</dd
12ef0 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  >.**.** [[SQLITE
12f00 5f 43 4f 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c  _CONFIG_HEAP]] <
12f10 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
12f20 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  _HEAP</dt>.** <d
12f30 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
12f40 73 70 65 63 69 66 69 65 73 20 61 20 73 74 61 74  specifies a stat
12f50 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72  ic memory buffer
12f60 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69 6c   that SQLite wil
12f70 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c  l use.** for all
12f80 20 6f 66 20 69 74 73 20 64 79 6e 61 6d 69 63 20   of its dynamic 
12f90 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
12fa0 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e 64 20 74  n needs beyond t
12fb0 68 6f 73 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a  hose provided.**
12fc0 20 66 6f 72 20 62 79 20 5b 53 51 4c 49 54 45 5f   for by [SQLITE_
12fd0 43 4f 4e 46 49 47 5f 53 43 52 41 54 43 48 5d 20  CONFIG_SCRATCH] 
12fe0 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  and [SQLITE_CONF
12ff0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a  IG_PAGECACHE]..*
13000 2a 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65  * There are thre
13010 65 20 61 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20  e arguments: An 
13020 38 2d 62 79 74 65 20 61 6c 69 67 6e 65 64 20 70  8-byte aligned p
13030 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65  ointer to the me
13040 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d  mory,.** the num
13050 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
13060 74 68 65 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  the memory buffe
13070 72 2c 20 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d  r, and the minim
13080 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13090 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66  ze..** ^If the f
130a0 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68  irst pointer (th
130b0 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  e memory pointer
130c0 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  ) is NULL, then 
130d0 53 51 4c 69 74 65 20 72 65 76 65 72 74 73 0a 2a  SQLite reverts.*
130e0 2a 20 74 6f 20 75 73 69 6e 67 20 69 74 73 20 64  * to using its d
130f0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
13100 6c 6f 63 61 74 6f 72 20 28 74 68 65 20 73 79 73  locator (the sys
13110 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70  tem malloc() imp
13120 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a  lementation),.**
13130 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20 70 72 69   undoing any pri
13140 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  or invocation of
13150 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
13160 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68  MALLOC].  ^If th
13170 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  e.** memory poin
13180 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ter is not NULL 
13190 61 6e 64 20 65 69 74 68 65 72 20 5b 53 51 4c 49  and either [SQLI
131a0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53  TE_ENABLE_MEMSYS
131b0 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  3] or.** [SQLITE
131c0 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d  _ENABLE_MEMSYS5]
131d0 20 61 72 65 20 64 65 66 69 6e 65 64 2c 20 74 68   are defined, th
131e0 65 6e 20 74 68 65 20 61 6c 74 65 72 6e 61 74 69  en the alternati
131f0 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  ve memory.** all
13200 6f 63 61 74 6f 72 20 69 73 20 65 6e 67 61 67 65  ocator is engage
13210 64 20 74 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20  d to handle all 
13220 6f 66 20 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72  of SQLites memor
13230 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
13240 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73 74  ds..** The first
13250 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d 65   pointer (the me
13260 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 6d 75  mory pointer) mu
13270 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f  st be aligned to
13280 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f   an 8-byte.** bo
13290 75 6e 64 61 72 79 20 6f 72 20 73 75 62 73 65 71  undary or subseq
132a0 75 65 6e 74 20 62 65 68 61 76 69 6f 72 20 6f 66  uent behavior of
132b0 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20   SQLite will be 
132c0 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68  undefined..** Th
132d0 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61  e minimum alloca
132e0 74 69 6f 6e 20 73 69 7a 65 20 69 73 20 63 61 70  tion size is cap
132f0 70 65 64 20 61 74 20 32 2a 2a 31 32 2e 20 52 65  ped at 2**12. Re
13300 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a  asonable values.
13310 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d  ** for the minim
13320 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  um allocation si
13330 7a 65 20 61 72 65 20 32 2a 2a 35 20 74 68 72 6f  ze are 2**5 thro
13340 75 67 68 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a  ugh 2**8.</dd>.*
13350 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13360 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74  NFIG_MUTEX]] <dt
13370 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  >SQLITE_CONFIG_M
13380 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13390 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
133a0 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
133b0 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
133c0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
133d0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
133e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
133f0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
13400 63 74 75 72 65 2e 20 20 54 68 65 20 61 72 67 75  cture.  The argu
13410 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73 0a 2a  ment specifies.*
13420 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f  * alternative lo
13430 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20 72 6f  w-level mutex ro
13440 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
13450 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68  d in place.** th
13460 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73  e mutex routines
13470 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69   built into SQLi
13480 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d  te.)^  ^SQLite m
13490 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
134a0 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66  he.** content of
134b0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75   the [sqlite3_mu
134c0 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  tex_methods] str
134d0 75 63 74 75 72 65 20 62 65 66 6f 72 65 20 74 68  ucture before th
134e0 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71  e call to.** [sq
134f0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
13500 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c  returns. ^If SQL
13510 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
13520 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
13530 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
13540 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
13550 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
13560 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
13570 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
13580 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
13590 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
135a0 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
135b0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
135c0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
135d0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
135e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20  TE_CONFIG_MUTEX 
135f0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13600 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74  tion will.** ret
13610 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
13620 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  R].</dd>.**.** [
13630 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  [SQLITE_CONFIG_G
13640 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  ETMUTEX]] <dt>SQ
13650 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
13660 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  UTEX</dt>.** <dd
13670 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
13680 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
13690 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
136a0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
136b0 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20  .** instance of 
136c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74  the [sqlite3_mut
136d0 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75  ex_methods] stru
136e0 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b  cture.  The.** [
136f0 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65  sqlite3_mutex_me
13700 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74  thods].** struct
13710 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69  ure is filled wi
13720 74 68 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79  th the currently
13730 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78 20 72   defined mutex r
13740 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68  outines.)^.** Th
13750 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65  is option can be
13760 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61   used to overloa
13770 64 20 74 68 65 20 64 65 66 61 75 6c 74 20 6d 75  d the default mu
13780 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a  tex allocation.*
13790 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74 68 20  * routines with 
137a0 61 20 77 72 61 70 70 65 72 20 75 73 65 64 20 74  a wrapper used t
137b0 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20 75 73  o track mutex us
137c0 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72 6d 61  age for performa
137d0 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67  nce.** profiling
137e0 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66 6f 72   or testing, for
137f0 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20   example.   ^If 
13800 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
13810 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
13820 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
13830 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
13840 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
13850 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
13860 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20  n.** the entire 
13870 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74  mutexing subsyst
13880 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  em is omitted fr
13890 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64  om the build and
138a0 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a   hence calls to.
138b0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
138c0 69 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53  ig()] with the S
138d0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54  QLITE_CONFIG_GET
138e0 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72 61 74  MUTEX configurat
138f0 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a  ion option will.
13900 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ** return [SQLIT
13910 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a  E_ERROR].</dd>.*
13920 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
13930 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d  NFIG_LOOKASIDE]]
13940 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13950 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74  IG_LOOKASIDE</dt
13960 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
13970 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77   option takes tw
13980 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  o arguments that
13990 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 64   determine the d
139a0 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79  efault.** memory
139b0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20   allocation for 
139c0 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65  the lookaside me
139d0 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f  mory allocator o
139e0 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62  n each.** [datab
139f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
13a00 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75    The first argu
13a10 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20 73  ment is the.** s
13a20 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b  ize of each look
13a30 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c 6f  aside buffer slo
13a40 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  t and the second
13a50 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
13a60 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63  f.** slots alloc
13a70 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61 74  ated to each dat
13a80 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13a90 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74 69  .)^  ^(This opti
13aa0 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c  on sets the.** <
13ab0 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f  i>default</i> lo
13ac0 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54 68  okaside size. Th
13ad0 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  e [SQLITE_DBCONF
13ae0 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a  IG_LOOKASIDE].**
13af0 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74 65   verb to [sqlite
13b00 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63  3_db_config()] c
13b10 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63 68  an be used to ch
13b20 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69  ange the lookasi
13b30 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  de.** configurat
13b40 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
13b50 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e  l connections.)^
13b60 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
13b70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
13b80 43 48 45 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  CHE2]] <dt>SQLIT
13b90 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
13ba0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
13bb0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
13bc0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
13bd0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
13be0 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
13bf0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
13c00 6d 65 74 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74  methods2] object
13c10 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73  .  This object s
13c20 70 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74  pecifies the int
13c30 65 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63  erface.** to a c
13c40 75 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65  ustom page cache
13c50 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
13c60 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
13c70 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
13c80 2a 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73  ** object and us
13c90 65 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63  es it for page c
13ca0 61 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ache memory allo
13cb0 63 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a  cations.</dd>.**
13cc0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
13cd0 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 5d 5d  FIG_GETPCACHE2]]
13ce0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
13cf0 49 47 5f 47 45 54 50 43 41 43 48 45 32 3c 2f 64  IG_GETPCACHE2</d
13d00 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
13d10 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
13d20 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
13d30 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
13d40 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71  ter to an.** [sq
13d50 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
13d60 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
13d70 53 51 4c 69 74 65 20 63 6f 70 69 65 73 20 6f 66  SQLite copies of
13d80 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20   the current.** 
13d90 70 61 67 65 20 63 61 63 68 65 20 69 6d 70 6c 65  page cache imple
13da0 6d 65 6e 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74  mentation into t
13db0 68 61 74 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f  hat object.)^ </
13dc0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
13dd0 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20  TE_CONFIG_LOG]] 
13de0 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
13df0 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
13e00 64 3e 20 54 68 65 20 53 51 4c 49 54 45 5f 43 4f  d> The SQLITE_CO
13e10 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20  NFIG_LOG option 
13e20 69 73 20 75 73 65 64 20 74 6f 20 63 6f 6e 66 69  is used to confi
13e30 67 75 72 65 20 74 68 65 20 53 51 4c 69 74 65 0a  gure the SQLite.
13e40 2a 2a 20 67 6c 6f 62 61 6c 20 5b 65 72 72 6f 72  ** global [error
13e50 20 6c 6f 67 5d 2e 0a 2a 2a 20 28 5e 54 68 65 20   log]..** (^The 
13e60 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
13e70 47 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  G option takes t
13e80 77 6f 20 61 72 67 75 6d 65 6e 74 73 3a 20 61 20  wo arguments: a 
13e90 70 6f 69 6e 74 65 72 20 74 6f 20 61 0a 2a 2a 20  pointer to a.** 
13ea0 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20  function with a 
13eb0 63 61 6c 6c 20 73 69 67 6e 61 74 75 72 65 20 6f  call signature o
13ec0 66 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c  f void(*)(void*,
13ed0 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  int,const char*)
13ee0 2c 20 0a 2a 2a 20 61 6e 64 20 61 20 70 6f 69 6e  , .** and a poin
13ef0 74 65 72 20 74 6f 20 76 6f 69 64 2e 20 5e 49 66  ter to void. ^If
13f00 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 70 6f   the function po
13f10 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55 4c  inter is not NUL
13f20 4c 2c 20 69 74 20 69 73 0a 2a 2a 20 69 6e 76 6f  L, it is.** invo
13f30 6b 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ked by [sqlite3_
13f40 6c 6f 67 28 29 5d 20 74 6f 20 70 72 6f 63 65 73  log()] to proces
13f50 73 20 65 61 63 68 20 6c 6f 67 67 69 6e 67 20 65  s each logging e
13f60 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a  vent.  ^If the.*
13f70 2a 20 66 75 6e 63 74 69 6f 6e 20 70 6f 69 6e 74  * function point
13f80 65 72 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 20  er is NULL, the 
13f90 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
13fa0 69 6e 74 65 72 66 61 63 65 20 62 65 63 6f 6d 65  interface become
13fb0 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a 2a 20 5e 54  s a no-op..** ^T
13fc0 68 65 20 76 6f 69 64 20 70 6f 69 6e 74 65 72 20  he void pointer 
13fd0 74 68 61 74 20 69 73 20 74 68 65 20 73 65 63 6f  that is the seco
13fe0 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 53  nd argument to S
13ff0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47  QLITE_CONFIG_LOG
14000 20 69 73 0a 2a 2a 20 70 61 73 73 65 64 20 74 68   is.** passed th
14010 72 6f 75 67 68 20 61 73 20 74 68 65 20 66 69 72  rough as the fir
14020 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
14030 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
14040 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
14050 2a 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 6e 65  * function whene
14060 76 65 72 20 74 68 61 74 20 66 75 6e 63 74 69 6f  ver that functio
14070 6e 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  n is invoked.  ^
14080 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
14090 65 74 65 72 20 74 6f 0a 2a 2a 20 74 68 65 20 6c  eter to.** the l
140a0 6f 67 67 65 72 20 66 75 6e 63 74 69 6f 6e 20 69  ogger function i
140b0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
140c0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
140d0 74 6f 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  to the correspon
140e0 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ding.** [sqlite3
140f0 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c 20 61 6e 64  _log()] call and
14100 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74 6f 20   is intended to 
14110 62 65 20 61 20 5b 72 65 73 75 6c 74 20 63 6f 64  be a [result cod
14120 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 78 74  e] or an.** [ext
14130 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
14140 65 5d 2e 20 20 5e 54 68 65 20 74 68 69 72 64 20  e].  ^The third 
14150 70 61 72 61 6d 65 74 65 72 20 70 61 73 73 65 64  parameter passed
14160 20 74 6f 20 74 68 65 20 6c 6f 67 67 65 72 20 69   to the logger i
14170 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73 73 61 67 65  s.** log message
14180 20 61 66 74 65 72 20 66 6f 72 6d 61 74 74 69 6e   after formattin
14190 67 20 76 69 61 20 5b 73 71 6c 69 74 65 33 5f 73  g via [sqlite3_s
141a0 6e 70 72 69 6e 74 66 28 29 5d 2e 0a 2a 2a 20 54  nprintf()]..** T
141b0 68 65 20 53 51 4c 69 74 65 20 6c 6f 67 67 69 6e  he SQLite loggin
141c0 67 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  g interface is n
141d0 6f 74 20 72 65 65 6e 74 72 61 6e 74 3b 20 74 68  ot reentrant; th
141e0 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69 6f  e logger functio
141f0 6e 0a 2a 2a 20 73 75 70 70 6c 69 65 64 20 62 79  n.** supplied by
14200 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
14210 20 6d 75 73 74 20 6e 6f 74 20 69 6e 76 6f 6b 65   must not invoke
14220 20 61 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65   any SQLite inte
14230 72 66 61 63 65 2e 0a 2a 2a 20 49 6e 20 61 20 6d  rface..** In a m
14240 75 6c 74 69 2d 74 68 72 65 61 64 65 64 20 61 70  ulti-threaded ap
14250 70 6c 69 63 61 74 69 6f 6e 2c 20 74 68 65 20 61  plication, the a
14260 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
14270 65 64 20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e  ed logger.** fun
14280 63 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 74 68  ction must be th
14290 72 65 61 64 73 61 66 65 2e 20 3c 2f 64 64 3e 0a  readsafe. </dd>.
142a0 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
142b0 4f 4e 46 49 47 5f 55 52 49 5d 5d 20 3c 64 74 3e  ONFIG_URI]] <dt>
142c0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
142d0 49 0a 2a 2a 20 3c 64 64 3e 5e 28 54 68 69 73 20  I.** <dd>^(This 
142e0 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73  option takes a s
142f0 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 6f  ingle argument o
14300 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20 6e  f type int. If n
14310 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a 2a  on-zero, then.**
14320 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73   URI handling is
14330 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65   globally enable
14340 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d 65  d. If the parame
14350 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68 65  ter is zero, the
14360 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a 2a  n URI handling.*
14370 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69  * is globally di
14380 73 61 62 6c 65 64 2e 29 5e 20 5e 49 66 20 55 52  sabled.)^ ^If UR
14390 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
143a0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
143b0 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
143c0 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
143d0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
143e0 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
143f0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
14400 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
14410 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
14420 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
14430 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
14440 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
14450 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
14460 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
14470 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
14480 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
14490 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
144a0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
144b0 6f 70 65 6e 65 64 2e 20 5e 49 66 20 69 74 20 69  opened. ^If it i
144c0 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
144d0 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
144e0 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
144f0 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
14500 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
14510 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
14520 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
14530 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14540 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 5e 28 42  n is opened. ^(B
14550 79 20 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68  y default, URI h
14560 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61  andling is globa
14570 6c 6c 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e  lly.** disabled.
14580 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
14590 75 65 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65  ue may be change
145a0 64 20 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77  d by compiling w
145b0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49  ith the.** [SQLI
145c0 54 45 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62  TE_USE_URI] symb
145d0 6f 6c 20 64 65 66 69 6e 65 64 2e 29 5e 0a 2a 2a  ol defined.)^.**
145e0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
145f0 46 49 47 5f 43 4f 56 45 52 49 4e 47 5f 49 4e 44  FIG_COVERING_IND
14600 45 58 5f 53 43 41 4e 5d 5d 20 3c 64 74 3e 53 51  EX_SCAN]] <dt>SQ
14610 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45  LITE_CONFIG_COVE
14620 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 0a  RING_INDEX_SCAN.
14630 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
14640 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
14650 6c 65 20 69 6e 74 65 67 65 72 20 61 72 67 75 6d  le integer argum
14660 65 6e 74 20 77 68 69 63 68 20 69 73 20 69 6e 74  ent which is int
14670 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
14680 20 62 6f 6f 6c 65 61 6e 20 69 6e 20 6f 72 64 65   boolean in orde
14690 72 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64  r to enable or d
146a0 69 73 61 62 6c 65 20 74 68 65 20 75 73 65 20 6f  isable the use o
146b0 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64 69 63  f covering indic
146c0 65 73 20 66 6f 72 0a 2a 2a 20 66 75 6c 6c 20 74  es for.** full t
146d0 61 62 6c 65 20 73 63 61 6e 73 20 69 6e 20 74 68  able scans in th
146e0 65 20 71 75 65 72 79 20 6f 70 74 69 6d 69 7a 65  e query optimize
146f0 72 2e 20 20 5e 54 68 65 20 64 65 66 61 75 6c 74  r.  ^The default
14700 20 73 65 74 74 69 6e 67 20 69 73 20 64 65 74 65   setting is dete
14710 72 6d 69 6e 65 64 0a 2a 2a 20 62 79 20 74 68 65  rmined.** by the
14720 20 5b 53 51 4c 49 54 45 5f 41 4c 4c 4f 57 5f 43   [SQLITE_ALLOW_C
14730 4f 56 45 52 49 4e 47 5f 49 4e 44 45 58 5f 53 43  OVERING_INDEX_SC
14740 41 4e 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  AN] compile-time
14750 20 6f 70 74 69 6f 6e 2c 20 6f 72 20 69 73 20 22   option, or is "
14760 6f 6e 22 0a 2a 2a 20 69 66 20 74 68 61 74 20 63  on".** if that c
14770 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
14780 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 2e 0a 2a  on is omitted..*
14790 2a 20 54 68 65 20 61 62 69 6c 69 74 79 20 74 6f  * The ability to
147a0 20 64 69 73 61 62 6c 65 20 74 68 65 20 75 73 65   disable the use
147b0 20 6f 66 20 63 6f 76 65 72 69 6e 67 20 69 6e 64   of covering ind
147c0 69 63 65 73 20 66 6f 72 20 66 75 6c 6c 20 74 61  ices for full ta
147d0 62 6c 65 20 73 63 61 6e 73 0a 2a 2a 20 69 73 20  ble scans.** is 
147e0 62 65 63 61 75 73 65 20 73 6f 6d 65 20 69 6e 63  because some inc
147f0 6f 72 72 65 63 74 6c 79 20 63 6f 64 65 64 20 6c  orrectly coded l
14800 65 67 61 63 79 20 61 70 70 6c 69 63 61 74 69 6f  egacy applicatio
14810 6e 73 20 6d 69 67 68 74 20 6d 61 6c 66 75 6e 63  ns might malfunc
14820 74 69 6f 6e 0a 2a 2a 20 77 68 65 6e 20 74 68 65  tion.** when the
14830 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20 69 73   optimization is
14840 20 65 6e 61 62 6c 65 64 2e 20 20 50 72 6f 76 69   enabled.  Provi
14850 64 69 6e 67 20 74 68 65 20 61 62 69 6c 69 74 79  ding the ability
14860 20 74 6f 0a 2a 2a 20 64 69 73 61 62 6c 65 20 74   to.** disable t
14870 68 65 20 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 20  he optimization 
14880 61 6c 6c 6f 77 73 20 74 68 65 20 6f 6c 64 65 72  allows the older
14890 2c 20 62 75 67 67 79 20 61 70 70 6c 69 63 61 74  , buggy applicat
148a0 69 6f 6e 20 63 6f 64 65 20 74 6f 20 77 6f 72 6b  ion code to work
148b0 0a 2a 2a 20 77 69 74 68 6f 75 74 20 63 68 61 6e  .** without chan
148c0 67 65 20 65 76 65 6e 20 77 69 74 68 20 6e 65 77  ge even with new
148d0 65 72 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  er versions of S
148e0 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  QLite..**.** [[S
148f0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41  QLITE_CONFIG_PCA
14900 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54 45 5f 43  CHE]] [[SQLITE_C
14910 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 5d  ONFIG_GETPCACHE]
14920 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  ].** <dt>SQLITE_
14930 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 20 61 6e  CONFIG_PCACHE an
14940 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  d SQLITE_CONFIG_
14950 47 45 54 50 43 41 43 48 45 0a 2a 2a 20 3c 64 64  GETPCACHE.** <dd
14960 3e 20 54 68 65 73 65 20 6f 70 74 69 6f 6e 73 20  > These options 
14970 61 72 65 20 6f 62 73 6f 6c 65 74 65 20 61 6e 64  are obsolete and
14980 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75   should not be u
14990 73 65 64 20 62 79 20 6e 65 77 20 63 6f 64 65 2e  sed by new code.
149a0 0a 2a 2a 20 54 68 65 79 20 61 72 65 20 72 65 74  .** They are ret
149b0 61 69 6e 65 64 20 66 6f 72 20 62 61 63 6b 77 61  ained for backwa
149c0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
149d0 79 20 62 75 74 20 61 72 65 20 6e 6f 77 20 6e 6f  y but are now no
149e0 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a  -ops..** </dd>.*
149f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14a00 4e 46 49 47 5f 53 51 4c 4c 4f 47 5d 5d 0a 2a 2a  NFIG_SQLLOG]].**
14a10 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
14a20 49 47 5f 53 51 4c 4c 4f 47 0a 2a 2a 20 3c 64 64  IG_SQLLOG.** <dd
14a30 3e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20  >This option is 
14a40 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
14a50 66 20 73 71 6c 69 74 65 20 69 73 20 63 6f 6d 70  f sqlite is comp
14a60 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
14a70 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
14a80 53 51 4c 4c 4f 47 5d 20 70 72 65 2d 70 72 6f 63  SQLLOG] pre-proc
14a90 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65 66 69  essor macro defi
14aa0 6e 65 64 2e 20 54 68 65 20 66 69 72 73 74 20 61  ned. The first a
14ab0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 0a 2a  rgument should.*
14ac0 2a 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74  * be a pointer t
14ad0 6f 20 61 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20  o a function of 
14ae0 74 79 70 65 20 76 6f 69 64 28 2a 29 28 76 6f 69  type void(*)(voi
14af0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 63 6f 6e 73  d*,sqlite3*,cons
14b00 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 2e 0a 2a  t char*, int)..*
14b10 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 73 68 6f  * The second sho
14b20 75 6c 64 20 62 65 20 6f 66 20 74 79 70 65 20 28  uld be of type (
14b30 76 6f 69 64 2a 29 2e 20 54 68 65 20 63 61 6c 6c  void*). The call
14b40 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20  back is invoked 
14b50 62 79 20 74 68 65 20 6c 69 62 72 61 72 79 0a 2a  by the library.*
14b60 2a 20 69 6e 20 74 68 72 65 65 20 73 65 70 61 72  * in three separ
14b70 61 74 65 20 63 69 72 63 75 6d 73 74 61 6e 63 65  ate circumstance
14b80 73 2c 20 69 64 65 6e 74 69 66 69 65 64 20 62 79  s, identified by
14b90 20 74 68 65 20 76 61 6c 75 65 20 70 61 73 73 65   the value passe
14ba0 64 20 61 73 20 74 68 65 0a 2a 2a 20 66 6f 75 72  d as the.** four
14bb0 74 68 20 70 61 72 61 6d 65 74 65 72 2e 20 49 66  th parameter. If
14bc0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
14bd0 6d 65 74 65 72 20 69 73 20 30 2c 20 74 68 65 6e  meter is 0, then
14be0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
14bf0 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 70 61 73 73  nnection.** pass
14c00 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64  ed as the second
14c10 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 6a 75   argument has ju
14c20 73 74 20 62 65 65 6e 20 6f 70 65 6e 65 64 2e 20  st been opened. 
14c30 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65  The third argume
14c40 6e 74 0a 2a 2a 20 70 6f 69 6e 74 73 20 74 6f 20  nt.** points to 
14c50 61 20 62 75 66 66 65 72 20 63 6f 6e 74 61 69 6e  a buffer contain
14c60 69 6e 67 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  ing the name of 
14c70 74 68 65 20 6d 61 69 6e 20 64 61 74 61 62 61 73  the main databas
14c80 65 20 66 69 6c 65 2e 20 49 66 20 74 68 65 0a 2a  e file. If the.*
14c90 2a 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74  * fourth paramet
14ca0 65 72 20 69 73 20 31 2c 20 74 68 65 6e 20 74 68  er is 1, then th
14cb0 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
14cc0 74 68 61 74 20 74 68 65 20 74 68 69 72 64 20 70  that the third p
14cd0 61 72 61 6d 65 74 65 72 0a 2a 2a 20 70 6f 69 6e  arameter.** poin
14ce0 74 73 20 74 6f 20 68 61 73 20 6a 75 73 74 20 62  ts to has just b
14cf0 65 65 6e 20 65 78 65 63 75 74 65 64 2e 20 4f 72  een executed. Or
14d00 2c 20 69 66 20 74 68 65 20 66 6f 75 72 74 68 20  , if the fourth 
14d10 70 61 72 61 6d 65 74 65 72 20 69 73 20 32 2c 20  parameter is 2, 
14d20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6e 6e  then.** the conn
14d30 65 63 74 69 6f 6e 20 62 65 69 6e 67 20 70 61 73  ection being pas
14d40 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
14d50 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 62  d parameter is b
14d60 65 69 6e 67 20 63 6c 6f 73 65 64 2e 20 54 68 65  eing closed. The
14d70 0a 2a 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65  .** third parame
14d80 74 65 72 20 69 73 20 70 61 73 73 65 64 20 4e 55  ter is passed NU
14d90 4c 4c 20 49 6e 20 74 68 69 73 20 63 61 73 65 2e  LL In this case.
14da0 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20    An example of 
14db0 75 73 69 6e 67 20 74 68 69 73 0a 2a 2a 20 63 6f  using this.** co
14dc0 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
14dd0 6f 6e 20 63 61 6e 20 62 65 20 73 65 65 6e 20 69  on can be seen i
14de0 6e 20 74 68 65 20 22 74 65 73 74 5f 73 71 6c 6c  n the "test_sqll
14df0 6f 67 2e 63 22 20 73 6f 75 72 63 65 20 66 69 6c  og.c" source fil
14e00 65 20 69 6e 0a 2a 2a 20 74 68 65 20 63 61 6e 6f  e in.** the cano
14e10 6e 69 63 61 6c 20 53 51 4c 69 74 65 20 73 6f 75  nical SQLite sou
14e20 72 63 65 20 74 72 65 65 2e 3c 2f 64 64 3e 0a 2a  rce tree.</dd>.*
14e30 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
14e40 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 5d 5d  NFIG_MMAP_SIZE]]
14e50 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
14e60 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 0a  ONFIG_MMAP_SIZE.
14e70 2a 2a 20 3c 64 64 3e 5e 53 51 4c 49 54 45 5f 43  ** <dd>^SQLITE_C
14e80 4f 4e 46 49 47 5f 4d 4d 41 50 5f 53 49 5a 45 20  ONFIG_MMAP_SIZE 
14e90 74 61 6b 65 73 20 74 77 6f 20 36 34 2d 62 69 74  takes two 64-bit
14ea0 20 69 6e 74 65 67 65 72 20 28 73 71 6c 69 74 65   integer (sqlite
14eb0 33 5f 69 6e 74 36 34 29 20 76 61 6c 75 65 73 0a  3_int64) values.
14ec0 2a 2a 20 74 68 61 74 20 61 72 65 20 74 68 65 20  ** that are the 
14ed0 64 65 66 61 75 6c 74 20 6d 6d 61 70 20 73 69 7a  default mmap siz
14ee0 65 20 6c 69 6d 69 74 20 28 74 68 65 20 64 65 66  e limit (the def
14ef0 61 75 6c 74 20 73 65 74 74 69 6e 67 20 66 6f 72  ault setting for
14f00 0a 2a 2a 20 5b 50 52 41 47 4d 41 20 6d 6d 61 70  .** [PRAGMA mmap
14f10 5f 73 69 7a 65 5d 29 20 61 6e 64 20 74 68 65 20  _size]) and the 
14f20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64 20  maximum allowed 
14f30 6d 6d 61 70 20 73 69 7a 65 20 6c 69 6d 69 74 2e  mmap size limit.
14f40 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
14f50 20 73 65 74 74 69 6e 67 20 63 61 6e 20 62 65 20   setting can be 
14f60 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 65 61  overridden by ea
14f70 63 68 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ch database conn
14f80 65 63 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20  ection using.** 
14f90 65 69 74 68 65 72 20 74 68 65 20 5b 50 52 41 47  either the [PRAG
14fa0 4d 41 20 6d 6d 61 70 5f 73 69 7a 65 5d 20 63 6f  MA mmap_size] co
14fb0 6d 6d 61 6e 64 2c 20 6f 72 20 62 79 20 75 73 69  mmand, or by usi
14fc0 6e 67 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  ng the.** [SQLIT
14fd0 45 5f 46 43 4e 54 4c 5f 4d 4d 41 50 5f 53 49 5a  E_FCNTL_MMAP_SIZ
14fe0 45 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 2e  E] file control.
14ff0 20 20 5e 28 54 68 65 20 6d 61 78 69 6d 75 6d 20    ^(The maximum 
15000 61 6c 6c 6f 77 65 64 20 6d 6d 61 70 20 73 69 7a  allowed mmap siz
15010 65 0a 2a 2a 20 63 61 6e 6e 6f 74 20 62 65 20 63  e.** cannot be c
15020 68 61 6e 67 65 64 20 61 74 20 72 75 6e 2d 74 69  hanged at run-ti
15030 6d 65 2e 20 20 4e 6f 72 20 6d 61 79 20 74 68 65  me.  Nor may the
15040 20 6d 61 78 69 6d 75 6d 20 61 6c 6c 6f 77 65 64   maximum allowed
15050 20 6d 6d 61 70 20 73 69 7a 65 0a 2a 2a 20 65 78   mmap size.** ex
15060 63 65 65 64 20 74 68 65 20 63 6f 6d 70 69 6c 65  ceed the compile
15070 2d 74 69 6d 65 20 6d 61 78 69 6d 75 6d 20 6d 6d  -time maximum mm
15080 61 70 20 73 69 7a 65 20 73 65 74 20 62 79 20 74  ap size set by t
15090 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 41  he.** [SQLITE_MA
150a0 58 5f 4d 4d 41 50 5f 53 49 5a 45 5d 20 63 6f 6d  X_MMAP_SIZE] com
150b0 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
150c0 2e 29 5e 0a 2a 2a 20 5e 49 66 20 65 69 74 68 65  .)^.** ^If eithe
150d0 72 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68  r argument to th
150e0 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 6e 65 67  is option is neg
150f0 61 74 69 76 65 2c 20 74 68 65 6e 20 74 68 61 74  ative, then that
15100 20 61 72 67 75 6d 65 6e 74 20 69 73 0a 2a 2a 20   argument is.** 
15110 63 68 61 6e 67 65 64 20 74 6f 20 69 74 73 20 63  changed to its c
15120 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 64 65 66 61  ompile-time defa
15130 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  ult..**.** [[SQL
15140 49 54 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32  ITE_CONFIG_WIN32
15150 5f 48 45 41 50 53 49 5a 45 5d 5d 0a 2a 2a 20 3c  _HEAPSIZE]].** <
15160 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
15170 5f 57 49 4e 33 32 5f 48 45 41 50 53 49 5a 45 0a  _WIN32_HEAPSIZE.
15180 2a 2a 20 3c 64 64 3e 5e 54 68 69 73 20 6f 70 74  ** <dd>^This opt
15190 69 6f 6e 20 69 73 20 6f 6e 6c 79 20 61 76 61 69  ion is only avai
151a0 6c 61 62 6c 65 20 69 66 20 53 51 4c 69 74 65 20  lable if SQLite 
151b0 69 73 20 63 6f 6d 70 69 6c 65 64 20 66 6f 72 20  is compiled for 
151c0 57 69 6e 64 6f 77 73 0a 2a 2a 20 77 69 74 68 20  Windows.** with 
151d0 74 68 65 20 5b 53 51 4c 49 54 45 5f 57 49 4e 33  the [SQLITE_WIN3
151e0 32 5f 4d 41 4c 4c 4f 43 5d 20 70 72 65 2d 70 72  2_MALLOC] pre-pr
151f0 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 64 65  ocessor macro de
15200 66 69 6e 65 64 2e 0a 2a 2a 20 53 51 4c 49 54 45  fined..** SQLITE
15210 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48 45  _CONFIG_WIN32_HE
15220 41 50 53 49 5a 45 20 74 61 6b 65 73 20 61 20 33  APSIZE takes a 3
15230 32 2d 62 69 74 20 75 6e 73 69 67 6e 65 64 20 69  2-bit unsigned i
15240 6e 74 65 67 65 72 20 76 61 6c 75 65 0a 2a 2a 20  nteger value.** 
15250 74 68 61 74 20 73 70 65 63 69 66 69 65 73 20 74  that specifies t
15260 68 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20  he maximum size 
15270 6f 66 20 74 68 65 20 63 72 65 61 74 65 64 20 68  of the created h
15280 65 61 70 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  eap..** </dl>.**
15290 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
152a0 46 49 47 5f 57 4f 52 4b 45 52 5f 54 48 52 45 41  FIG_WORKER_THREA
152b0 44 53 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  DS]].** <dt>SQLI
152c0 54 45 5f 43 4f 4e 46 49 47 5f 57 4f 52 4b 45 52  TE_CONFIG_WORKER
152d0 5f 54 48 52 45 41 44 53 0a 2a 2a 20 3c 64 64 3e  _THREADS.** <dd>
152e0 5e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 57  ^SQLITE_CONFIG_W
152f0 4f 52 4b 45 52 5f 54 48 52 45 41 44 53 20 74 61  ORKER_THREADS ta
15300 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
15310 75 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e  ument of type in
15320 74 2e 0a 2a 2a 20 49 74 20 69 73 20 75 73 65 64  t..** It is used
15330 20 74 6f 20 73 65 74 20 74 68 65 20 6e 75 6d 62   to set the numb
15340 65 72 20 6f 66 20 62 61 63 6b 67 72 6f 75 6e 64  er of background
15350 20 77 6f 72 6b 65 72 20 74 68 72 65 61 64 73 20   worker threads 
15360 74 68 61 74 20 6d 61 79 20 62 65 0a 2a 2a 20 6c  that may be.** l
15370 61 75 6e 63 68 65 64 20 77 68 65 6e 20 73 6f 72  aunched when sor
15380 74 69 6e 67 20 6c 61 72 67 65 20 61 6d 6f 75 6e  ting large amoun
15390 74 73 20 6f 66 20 64 61 74 61 2e 20 41 20 76 61  ts of data. A va
153a0 6c 75 65 20 6f 66 20 30 20 6d 65 61 6e 73 20 6c  lue of 0 means l
153b0 61 75 6e 63 68 20 0a 2a 2a 20 6e 6f 20 62 61 63  aunch .** no bac
153c0 6b 67 72 6f 75 6e 64 20 74 68 72 65 61 64 73 20  kground threads 
153d0 61 74 20 61 6c 6c 2e 20 54 68 65 20 6d 61 78 69  at all. The maxi
153e0 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 62 61  mum number of ba
153f0 63 6b 67 72 6f 75 6e 64 20 74 68 72 65 61 64 73  ckground threads
15400 20 0a 2a 2a 20 61 6c 6c 6f 77 65 64 20 69 73 20   .** allowed is 
15410 63 6f 6e 66 69 67 75 72 65 64 20 61 74 20 62 75  configured at bu
15420 69 6c 64 2d 74 69 6d 65 20 62 79 20 74 68 65 20  ild-time by the 
15430 53 51 4c 49 54 45 5f 4d 41 58 5f 57 4f 52 4b 45  SQLITE_MAX_WORKE
15440 52 5f 54 48 52 45 41 44 53 20 0a 2a 2a 20 70 72  R_THREADS .** pr
15450 65 2d 70 72 6f 63 65 73 73 6f 72 20 6f 70 74 69  e-processor opti
15460 6f 6e 2e 20 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  on. .** </dl>.*/
15470 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
15480 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52  CONFIG_SINGLETHR
15490 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c 20 2a  EAD  1  /* nil *
154a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
154b0 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52  _CONFIG_MULTITHR
154c0 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69 6c 20  EAD   2  /* nil 
154d0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
154e0 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
154f0 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e 69 6c  ZED    3  /* nil
15500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
15510 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
15520 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20 73 71          4  /* sq
15530 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
15540 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
15550 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
15560 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f 2a 20  ALLOC     5  /* 
15570 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
15580 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
15590 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
155a0 52 41 54 43 48 20 20 20 20 20 20 20 36 20 20 2f  RATCH       6  /
155b0 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73 7a 2c  * void*, int sz,
155c0 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66 69 6e   int N */.#defin
155d0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
155e0 50 41 47 45 43 41 43 48 45 20 20 20 20 20 37 20  PAGECACHE     7 
155f0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
15600 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
15610 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
15620 47 5f 48 45 41 50 20 20 20 20 20 20 20 20 20 20  G_HEAP          
15630 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  8  /* void*, int
15640 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69 6e 20   nByte, int min 
15650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
15660 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
15670 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62 6f 6f  US     9  /* boo
15680 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20  lean */.#define 
15690 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55  SQLITE_CONFIG_MU
156a0 54 45 58 20 20 20 20 20 20 20 20 31 30 20 20 2f  TEX        10  /
156b0 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f  * sqlite3_mutex_
156c0 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
156d0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
156e0 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20 20 31  G_GETMUTEX     1
156f0 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  1  /* sqlite3_mu
15700 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
15710 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 53 51  /* previously SQ
15720 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48 55 4e  LITE_CONFIG_CHUN
15730 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63 68 20  KALLOC 12 which 
15740 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e 20 2a  is now unused. *
15750 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  / .#define SQLIT
15760 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  E_CONFIG_LOOKASI
15770 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69 6e 74  DE    13  /* int
15780 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20   int */.#define 
15790 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 43  SQLITE_CONFIG_PC
157a0 41 43 48 45 20 20 20 20 20 20 20 31 34 20 20 2f  ACHE       14  /
157b0 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64 65 66 69  * no-op */.#defi
157c0 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ne SQLITE_CONFIG
157d0 5f 47 45 54 50 43 41 43 48 45 20 20 20 20 31 35  _GETPCACHE    15
157e0 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23 64    /* no-op */.#d
157f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
15800 46 49 47 5f 4c 4f 47 20 20 20 20 20 20 20 20 20  FIG_LOG         
15810 20 31 36 20 20 2f 2a 20 78 46 75 6e 63 2c 20 76   16  /* xFunc, v
15820 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  oid* */.#define 
15830 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
15840 49 20 20 20 20 20 20 20 20 20 20 31 37 20 20 2f  I          17  /
15850 2a 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65  * int */.#define
15860 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
15870 43 41 43 48 45 32 20 20 20 20 20 20 31 38 20 20  CACHE2      18  
15880 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63 68  /* sqlite3_pcach
15890 65 5f 6d 65 74 68 6f 64 73 32 2a 20 2a 2f 0a 23  e_methods2* */.#
158a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
158b0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 32 20  NFIG_GETPCACHE2 
158c0 20 20 31 39 20 20 2f 2a 20 73 71 6c 69 74 65 33    19  /* sqlite3
158d0 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32  _pcache_methods2
158e0 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  * */.#define SQL
158f0 49 54 45 5f 43 4f 4e 46 49 47 5f 43 4f 56 45 52  ITE_CONFIG_COVER
15900 49 4e 47 5f 49 4e 44 45 58 5f 53 43 41 4e 20 32  ING_INDEX_SCAN 2
15910 30 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  0  /* int */.#de
15920 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
15930 49 47 5f 53 51 4c 4c 4f 47 20 20 20 20 20 20 20  IG_SQLLOG       
15940 32 31 20 20 2f 2a 20 78 53 71 6c 6c 6f 67 2c 20  21  /* xSqllog, 
15950 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66 69 6e 65  void* */.#define
15960 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d   SQLITE_CONFIG_M
15970 4d 41 50 5f 53 49 5a 45 20 20 20 20 32 32 20 20  MAP_SIZE    22  
15980 2f 2a 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  /* sqlite3_int64
15990 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
159a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
159b0 45 5f 43 4f 4e 46 49 47 5f 57 49 4e 33 32 5f 48  E_CONFIG_WIN32_H
159c0 45 41 50 53 49 5a 45 20 20 20 20 20 20 32 33 20  EAPSIZE      23 
159d0 20 2f 2a 20 69 6e 74 20 6e 42 79 74 65 20 2a 2f   /* int nByte */
159e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
159f0 43 4f 4e 46 49 47 5f 57 4f 52 4b 45 52 5f 54 48  CONFIG_WORKER_TH
15a00 52 45 41 44 53 20 20 20 20 20 20 32 34 20 20 2f  READS      24  /
15a10 2a 20 69 6e 74 20 6e 57 6f 72 6b 65 72 20 2a 2f  * int nWorker */
15a20 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
15a30 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
15a40 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
15a50 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
15a60 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
15a70 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
15a80 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
15a90 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
15aa0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
15ab0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
15ac0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
15ad0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
15ae0 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
15af0 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
15b00 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
15b10 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
15b20 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
15b30 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
15b40 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
15b50 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
15b60 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
15b70 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
15b80 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
15b90 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
15ba0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
15bb0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
15bc0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
15bd0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
15be0 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
15bf0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
15c00 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
15c10 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
15c20 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
15c30 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
15c40 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
15c50 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
15c60 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
15c70 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
15c80 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
15c90 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
15ca0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
15cb0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
15cc0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
15cd0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
15ce0 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
15cf0 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
15d00 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
15d10 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
15d20 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
15d30 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15d40 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
15d50 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
15d60 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
15d70 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
15d80 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
15d90 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
15da0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
15db0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
15dc0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
15dd0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
15de0 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
15df0 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
15e00 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
15e10 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
15e20 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
15e30 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
15e40 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
15e50 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
15e60 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
15e70 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
15e80 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
15e90 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
15ea0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
15eb0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
15ec0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
15ed0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
15ee0 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
15ef0 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
15f00 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
15f10 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
15f20 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
15f30 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
15f40 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
15f50 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
15f60 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
15f70 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
15f80 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
15f90 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
15fa0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
15fb0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
15fc0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
15fd0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
15fe0 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
15ff0 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
16000 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
16010 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
16020 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
16030 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
16040 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
16050 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
16060 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
16070 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
16080 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
16090 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
160a0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
160b0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
160c0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
160d0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
160e0 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
160f0 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
16100 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
16110 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
16120 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
16130 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
16140 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
16150 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
16160 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
16170 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
16180 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
16190 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
161a0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
161b0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
161c0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
161d0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
161e0 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
161f0 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
16200 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
16210 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
16220 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
16230 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
16240 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
16250 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
16260 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
16270 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
16280 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
16290 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
162a0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
162b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
162c0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
162d0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
162e0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
162f0 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
16300 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
16310 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
16320 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
16330 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
16340 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
16350 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
16360 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
16370 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
16380 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
16390 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
163a0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
163b0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
163c0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
163d0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
163e0 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
163f0 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
16400 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
16410 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
16420 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
16430 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
16440 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
16450 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
16460 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
16470 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
16480 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
16490 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
164a0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
164b0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
164c0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
164d0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
164e0 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
164f0 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
16500 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
16510 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
16520 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
16530 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
16540 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
16550 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
16560 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
16570 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
16580 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
16590 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
165a0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
165b0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
165c0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
165d0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
165e0 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
165f0 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
16600 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
16610 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
16620 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
16630 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
16640 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
16650 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
16660 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
16670 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
16680 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
16690 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
166a0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
166b0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
166c0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
166d0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
166e0 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
166f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
16700 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
16710 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
16720 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
16730 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
16740 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
16750 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
16760 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
16770 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
16780 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
16790 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
167a0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
167b0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
167c0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
167d0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
167e0 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
167f0 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
16800 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
16810 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
16820 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
16830 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
16840 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
16850 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
16860 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
16870 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
16880 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
16890 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
168a0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
168b0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
168c0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
168d0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
168e0 6e 20 6d 6f 73 74 20 53 51 4c 69 74 65 20 74 61  n most SQLite ta
168f0 62 6c 65 73 20 28 65 78 63 65 70 74 20 66 6f 72  bles (except for
16900 20 5b 57 49 54 48 4f 55 54 20 52 4f 57 49 44 5d   [WITHOUT ROWID]
16910 20 74 61 62 6c 65 73 29 0a 2a 2a 20 68 61 73 20   tables).** has 
16920 61 20 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20  a unique 64-bit 
16930 73 69 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65  signed.** intege
16940 72 20 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65  r key called the
16950 20 5b 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64   [ROWID | "rowid
16960 22 5d 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69  "]. ^The rowid i
16970 73 20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62  s always availab
16980 6c 65 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65  le.** as an unde
16990 63 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61  clared column na
169a0 6d 65 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20  med ROWID, OID, 
169b0 6f 72 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f  or _ROWID_ as lo
169c0 6e 67 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e  ng as those.** n
169d0 61 6d 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73  ames are not als
169e0 6f 20 75 73 65 64 20 62 79 20 65 78 70 6c 69 63  o used by explic
169f0 69 74 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f  itly declared co
16a00 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68  lumns. ^If.** th
16a10 65 20 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f  e table has a co
16a20 6c 75 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e  lumn of type [IN
16a30 54 45 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45  TEGER PRIMARY KE
16a40 59 5d 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c  Y] then that col
16a50 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65  umn.** is anothe
16a60 72 20 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20  r alias for the 
16a70 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rowid..**.** ^Th
16a80 65 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69  e sqlite3_last_i
16a90 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20 69  nsert_rowid(D) i
16aa0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
16ab0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
16ac0 74 68 65 20 0a 2a 2a 20 6d 6f 73 74 20 72 65 63  the .** most rec
16ad0 65 6e 74 20 73 75 63 63 65 73 73 66 75 6c 20 5b  ent successful [
16ae0 49 4e 53 45 52 54 5d 20 69 6e 74 6f 20 61 20 72  INSERT] into a r
16af0 6f 77 69 64 20 74 61 62 6c 65 20 6f 72 20 5b 76  owid table or [v
16b00 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a  irtual table].**
16b10 20 6f 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e   on database con
16b20 6e 65 63 74 69 6f 6e 20 44 2e 0a 2a 2a 20 5e 49  nection D..** ^I
16b30 6e 73 65 72 74 73 20 69 6e 74 6f 20 5b 57 49 54  nserts into [WIT
16b40 48 4f 55 54 20 52 4f 57 49 44 5d 20 74 61 62 6c  HOUT ROWID] tabl
16b50 65 73 20 61 72 65 20 6e 6f 74 20 72 65 63 6f 72  es are not recor
16b60 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  ded..** ^If no s
16b70 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
16b80 54 5d 73 20 69 6e 74 6f 20 72 6f 77 69 64 20 74  T]s into rowid t
16b90 61 62 6c 65 73 0a 2a 2a 20 68 61 76 65 20 65 76  ables.** have ev
16ba0 65 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74  er occurred on t
16bb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
16bc0 65 63 74 69 6f 6e 20 44 2c 20 0a 2a 2a 20 74 68  ection D, .** th
16bd0 65 6e 20 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  en sqlite3_last_
16be0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 44 29 20  insert_rowid(D) 
16bf0 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
16c00 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b 49 4e 53  .** ^(If an [INS
16c10 45 52 54 5d 20 6f 63 63 75 72 73 20 77 69 74 68  ERT] occurs with
16c20 69 6e 20 61 20 74 72 69 67 67 65 72 20 6f 72 20  in a trigger or 
16c30 77 69 74 68 69 6e 20 61 20 5b 76 69 72 74 75 61  within a [virtua
16c40 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d 65 74 68  l table].** meth
16c50 6f 64 2c 20 74 68 65 6e 20 74 68 69 73 20 72 6f  od, then this ro
16c60 75 74 69 6e 65 20 77 69 6c 6c 20 72 65 74 75 72  utine will retur
16c70 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66  n the [rowid] of
16c80 20 74 68 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a   the inserted.**
16c90 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20 61 73 20   row as long as 
16ca0 74 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76  the trigger or v
16cb0 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74  irtual table met
16cc0 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  hod is running..
16cd0 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65 20  ** But once the 
16ce0 74 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75  trigger or virtu
16cf0 61 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20  al table method 
16d00 65 6e 64 73 2c 20 74 68 65 20 76 61 6c 75 65 20  ends, the value 
16d10 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20 62 79 20  returned .** by 
16d20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 76  this routine rev
16d30 65 72 74 73 20 74 6f 20 77 68 61 74 20 69 74 20  erts to what it 
16d40 77 61 73 20 62 65 66 6f 72 65 20 74 68 65 20 74  was before the t
16d50 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
16d60 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65 74 68 6f  l.** table metho
16d70 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a  d began.)^.**.**
16d80 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68   ^An [INSERT] th
16d90 61 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20  at fails due to 
16da0 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
16db0 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a  lation is not a.
16dc0 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
16dd0 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20  NSERT] and does 
16de0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
16df0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
16e00 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65   this.** routine
16e10 2e 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20  .  ^Thus INSERT 
16e20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20  OR FAIL, INSERT 
16e30 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52  OR IGNORE, INSER
16e40 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a  T OR ROLLBACK,.*
16e50 2a 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20  * and INSERT OR 
16e60 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68  ABORT make no ch
16e70 61 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74  anges to the ret
16e80 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69  urn value of thi
16e90 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65  s.** routine whe
16ea0 6e 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f  n their insertio
16eb0 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e  n fails.  ^(When
16ec0 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41   INSERT OR REPLA
16ed0 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73  CE.** encounters
16ee0 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69   a constraint vi
16ef0 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73  olation, it does
16f00 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a   not fail.  The.
16f10 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e  ** INSERT contin
16f20 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  ues to completio
16f30 6e 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67  n after deleting
16f40 20 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65   rows that cause
16f50 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61  d.** the constra
16f60 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49  int problem so I
16f70 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45  NSERT OR REPLACE
16f80 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61   will always cha
16f90 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72  nge.** the retur
16fa0 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20  n value of this 
16fb0 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a  interface.)^.**.
16fc0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
16fd0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75  oses of this rou
16fe0 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54  tine, an [INSERT
16ff0 5d 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20  ] is considered 
17000 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73  to.** be success
17010 66 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69  ful even if it i
17020 73 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72  s subsequently r
17030 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a  olled back..**.*
17040 2a 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  * This function 
17050 69 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f  is accessible to
17060 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
17070 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74  via the.** [last
17080 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20  _insert_rowid() 
17090 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a  SQL function]..*
170a0 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61  *.** If a separa
170b0 74 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72  te thread perfor
170c0 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54  ms a new [INSERT
170d0 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a  ] on the same.**
170e0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
170f0 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b  tion while the [
17100 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
17110 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20  ert_rowid()].** 
17120 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
17130 69 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61  ing and thus cha
17140 6e 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e  nges the last in
17150 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a  sert [rowid],.**
17160 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20   then the value 
17170 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
17180 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74  ite3_last_insert
17190 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20  _rowid()] is.** 
171a0 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e  unpredictable an
171b0 64 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61  d might not equa
171c0 6c 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64  l either the old
171d0 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c   or the new.** l
171e0 61 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69  ast insert [rowi
171f0 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  d]..*/.sqlite3_i
17200 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73  nt64 sqlite3_las
17210 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73  t_insert_rowid(s
17220 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
17230 20 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74   CAPI3REF: Count
17240 20 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52   The Number Of R
17250 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a  ows Modified.**.
17260 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
17270 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
17280 6d 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65  mber of database
17290 20 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20   rows that were 
172a0 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e  changed.** or in
172b0 73 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65  serted or delete
172c0 64 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65  d by the most re
172d0 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64  cently completed
172e0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a   SQL statement.*
172f0 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61  * on the [databa
17300 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73  se connection] s
17310 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
17320 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e  first parameter.
17330 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67  .** ^(Only chang
17340 65 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65  es that are dire
17350 63 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62  ctly specified b
17360 79 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20  y the [INSERT], 
17370 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20  [UPDATE],.** or 
17380 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65  [DELETE] stateme
17390 6e 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20  nt are counted. 
173a0 20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67   Auxiliary chang
173b0 65 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20  es caused by.** 
173c0 74 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72  triggers or [for
173d0 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73  eign key actions
173e0 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  ] are not counte
173f0 64 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20  d.)^ Use the.** 
17400 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63  [sqlite3_total_c
17410 68 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69  hanges()] functi
17420 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74  on to find the t
17430 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63  otal number of c
17440 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64  hanges.** includ
17450 69 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73  ing changes caus
17460 65 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61  ed by triggers a
17470 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61  nd foreign key a
17480 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43  ctions..**.** ^C
17490 68 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77  hanges to a view
174a0 20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61   that are simula
174b0 74 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45  ted by an [INSTE
174c0 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a  AD OF trigger].*
174d0 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65  * are not counte
174e0 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61  d.  Only real ta
174f0 62 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20  ble changes are 
17500 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  counted..**.** ^
17510 28 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20  (A "row change" 
17520 69 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61  is a change to a
17530 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61   single row of a
17540 20 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a   single table.**
17550 20 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e   caused by an IN
17560 53 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72  SERT, DELETE, or
17570 20 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e   UPDATE statemen
17580 74 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a  t.  Rows that.**
17590 20 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20   are changed as 
175a0 73 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20  side effects of 
175b0 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
175c0 61 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c  aint resolution,
175d0 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42  .** rollback, AB
175e0 4f 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20  ORT processing, 
175f0 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72  [DROP TABLE], or
17600 20 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a   by any other.**
17610 20 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e   mechanisms do n
17620 6f 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65  ot count as dire
17630 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29  ct row changes.)
17640 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67  ^.**.** A "trigg
17650 65 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61  er context" is a
17660 20 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74   scope of execut
17670 69 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20  ion that begins 
17680 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68  and.** ends with
17690 20 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61   the script of a
176a0 20 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52   [CREATE TRIGGER
176b0 20 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a   | trigger]. .**
176c0 20 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d   Most SQL statem
176d0 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c  ents are.** eval
176e0 75 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66  uated outside of
176f0 20 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54   any trigger.  T
17700 68 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20  his is the "top 
17710 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65  level".** trigge
17720 72 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61  r context.  If a
17730 20 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66   trigger fires f
17740 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65  rom the top leve
17750 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67  l, a.** new trig
17760 67 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65  ger context is e
17770 6e 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64  ntered for the d
17780 75 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20  uration of that 
17790 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20  one.** trigger. 
177a0 20 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65   Subtriggers cre
177b0 61 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20  ate subcontexts 
177c0 66 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69  for their durati
177d0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  on..**.** ^Calli
177e0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63  ng [sqlite3_exec
177f0 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
17800 73 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76  step()] recursiv
17810 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20  ely does.** not 
17820 63 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69  create a new tri
17830 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a  gger context..**
17840 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69  .** ^This functi
17850 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  on returns the n
17860 75 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20  umber of direct 
17870 72 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74  row changes in t
17880 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e  he.** most recen
17890 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  t INSERT, UPDATE
178a0 2c 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74  , or DELETE stat
178b0 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65  ement within the
178c0 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72   same.** trigger
178d0 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20   context..**.** 
178e0 5e 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c  ^Thus, when call
178f0 65 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20  ed from the top 
17900 6c 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63  level, this func
17910 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
17920 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  .** number of ch
17930 61 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73  anges in the mos
17940 74 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c  t recent INSERT,
17950 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45   UPDATE, or DELE
17960 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20  TE.** that also 
17970 6f 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20  occurred at the 
17980 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69  top level.  ^(Wi
17990 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66  thin the body of
179a0 20 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74   a trigger,.** t
179b0 68 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  he sqlite3_chang
179c0 65 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63  es() interface c
179d0 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20  an be called to 
179e0 66 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20  find the number 
179f0 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e  of.** changes in
17a00 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74   the most recent
17a10 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53  ly completed INS
17a20 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
17a30 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d  DELETE.** statem
17a40 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62  ent within the b
17a50 6f 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20  ody of the same 
17a60 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65  trigger..** Howe
17a70 76 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20  ver, the number 
17a80 72 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f  returned does no
17a90 74 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65  t include change
17aa0 73 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73  s.** caused by s
17ab0 75 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65  ubtriggers since
17ac0 20 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69   those have thei
17ad0 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e  r own context.)^
17ae0 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20  .**.** See also 
17af0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74  the [sqlite3_tot
17b00 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e  al_changes()] in
17b10 74 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20  terface, the.** 
17b20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70  [count_changes p
17b30 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20  ragma], and the 
17b40 5b 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66  [changes() SQL f
17b50 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
17b60 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
17b70 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67  read makes chang
17b80 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64  es on the same d
17b90 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
17ba0 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c  on.** while [sql
17bb0 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20  ite3_changes()] 
17bc0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
17bd0 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  the value return
17be0 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69  ed.** is unpredi
17bf0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
17c00 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
17c10 74 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  t sqlite3_change
17c20 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  s(sqlite3*);../*
17c30 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f  .** CAPI3REF: To
17c40 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  tal Number Of Ro
17c50 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
17c60 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
17c70 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
17c80 62 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67  ber of row chang
17c90 65 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e  es caused by [IN
17ca0 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54  SERT],.** [UPDAT
17cb0 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73  E] or [DELETE] s
17cc0 74 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20  tatements since 
17cd0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
17ce0 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70  nnection] was op
17cf0 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63  ened..** ^(The c
17d00 6f 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79  ount returned by
17d10 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63   sqlite3_total_c
17d20 68 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65  hanges() include
17d30 73 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a  s all changes.**
17d40 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54   from all [CREAT
17d50 45 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67  E TRIGGER | trig
17d60 67 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e  ger] contexts an
17d70 64 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62  d changes made b
17d80 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65  y.** [foreign ke
17d90 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65  y actions]. Howe
17da0 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e  ver,.** the coun
17db0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
17dc0 64 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20  de changes used 
17dd0 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45  to implement [RE
17de0 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e  PLACE] constrain
17df0 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61  ts,.** do rollba
17e00 63 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f  cks or ABORT pro
17e10 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f  cessing, or [DRO
17e20 50 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73  P TABLE] process
17e30 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75  ing.  The.** cou
17e40 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c  nt does not incl
17e50 75 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77  ude rows of view
17e60 73 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b  s that fire an [
17e70 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67  INSTEAD OF trigg
17e80 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69  er],.** though i
17e90 66 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46  f the INSTEAD OF
17ea0 20 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63   trigger makes c
17eb0 68 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77  hanges of its ow
17ec0 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73  n, those changes
17ed0 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64   .** are counted
17ee0 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .)^.** ^The sqli
17ef0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
17f00 73 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75  s() function cou
17f10 6e 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20  nts the changes 
17f20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68  as soon as.** th
17f30 65 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74  e statement that
17f40 20 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63   makes them is c
17f50 6f 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74  ompleted (when t
17f60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e  he statement han
17f70 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64  dle.** is passed
17f80 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   to [sqlite3_res
17f90 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
17fa0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a  3_finalize()])..
17fb0 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
17fc0 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e  he [sqlite3_chan
17fd0 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65  ges()] interface
17fe0 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f  , the.** [count_
17ff0 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c  changes pragma],
18000 20 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f   and the [total_
18010 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
18020 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
18030 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
18040 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
18050 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
18060 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
18070 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
18080 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
18090 73 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20  s()] is running 
180a0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a  then the value.*
180b0 2a 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e  * returned is un
180c0 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20  predictable and 
180d0 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a  not meaningful..
180e0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74  */.int sqlite3_t
180f0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c  otal_changes(sql
18100 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
18110 41 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75  API3REF: Interru
18120 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e  pt A Long-Runnin
18130 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54  g Query.**.** ^T
18140 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  his function cau
18150 73 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20  ses any pending 
18160 64 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69  database operati
18170 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a  on to abort and.
18180 2a 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73  ** return at its
18190 20 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74   earliest opport
181a0 75 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74  unity. This rout
181b0 69 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79  ine is typically
181c0 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65  .** called in re
181d0 73 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72  sponse to a user
181e0 20 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20   action such as 
181f0 70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c  pressing "Cancel
18200 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77  ".** or Ctrl-C w
18210 68 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61  here the user wa
18220 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79  nts a long query
18230 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61   operation to ha
18240 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c  lt.** immediatel
18250 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  y..**.** ^It is 
18260 73 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69  safe to call thi
18270 73 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61  s routine from a
18280 20 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e   thread differen
18290 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68  t from the.** th
182a0 72 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72  read that is cur
182b0 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74  rently running t
182c0 68 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  he database oper
182d0 61 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a  ation.  But it.*
182e0 2a 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f  * is not safe to
182f0 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69   call this routi
18300 6e 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ne with a [datab
18310 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
18320 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65  that.** is close
18330 64 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65  d or might close
18340 20 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f   before sqlite3_
18350 69 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75  interrupt() retu
18360 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61  rns..**.** ^If a
18370 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18380 69 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66  is very nearly f
18390 69 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74  inished at the t
183a0 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69  ime when.** sqli
183b0 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20  te3_interrupt() 
183c0 69 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20  is called, then 
183d0 69 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76  it might not hav
183e0 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79  e an opportunity
183f0 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72  .** to be interr
18400 75 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20  upted and might 
18410 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70  continue to comp
18420 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41  letion..**.** ^A
18430 6e 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20  n SQL operation 
18440 74 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70  that is interrup
18450 74 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ted will return 
18460 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50  [SQLITE_INTERRUP
18470 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69  T]..** ^If the i
18480 6e 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f  nterrupted SQL o
18490 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49  peration is an I
184a0 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f  NSERT, UPDATE, o
184b0 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74  r DELETE.** that
184c0 20 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78   is inside an ex
184d0 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69  plicit transacti
184e0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74  on, then the ent
184f0 69 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a  ire transaction.
18500 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65  ** will be rolle
18510 64 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63  d back automatic
18520 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ally..**.** ^The
18530 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
18540 70 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e  pt(D) call is in
18550 20 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c   effect until al
18560 6c 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e  l currently runn
18570 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
18580 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61  ments on [databa
18590 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
185a0 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79   complete.  ^Any
185b0 20 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65   new SQL stateme
185c0 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
185d0 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
185e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
185f0 75 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62  upt() call and b
18600 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75  efore the .** ru
18610 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73  nning statements
18620 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72   reaches zero ar
18630 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73  e interrupted as
18640 20 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65   if they had bee
18650 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69  n.** running pri
18660 6f 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  or to the sqlite
18670 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61  3_interrupt() ca
18680 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74  ll.  ^New SQL st
18690 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
186a0 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
186b0 65 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73  er the running s
186c0 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72  tatement count r
186d0 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a  eaches zero are.
186e0 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20  ** not effected 
186f0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  by the sqlite3_i
18700 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e  nterrupt()..** ^
18710 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  A call to sqlite
18720 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74  3_interrupt(D) t
18730 68 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20  hat occurs when 
18740 74 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e  there are no run
18750 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74  ning.** SQL stat
18760 65 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f  ements is a no-o
18770 70 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66  p and has no eff
18780 65 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65  ect on SQL state
18790 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72  ments.** that ar
187a0 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20  e started after 
187b0 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  the sqlite3_inte
187c0 72 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74  rrupt() call ret
187d0 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  urns..**.** If t
187e0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
187f0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68  ection closes wh
18800 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74  ile [sqlite3_int
18810 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20  errupt()].** is 
18820 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64  running then bad
18830 20 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b   things will lik
18840 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76  ely happen..*/.v
18850 6f 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  oid sqlite3_inte
18860 72 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b  rrupt(sqlite3*);
18870 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
18880 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41  : Determine If A
18890 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20  n SQL Statement 
188a0 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a  Is Complete.**.*
188b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
188c0 20 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69   are useful duri
188d0 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20  ng command-line 
188e0 69 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69  input to determi
188f0 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72  ne if the.** cur
18900 72 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74  rently entered t
18910 65 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72  ext seems to for
18920 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  m a complete SQL
18930 20 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a   statement or.**
18940 20 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69   if additional i
18950 6e 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62  nput is needed b
18960 65 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68  efore sending th
18970 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53  e text into.** S
18980 51 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e  QLite for parsin
18990 67 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69  g.  ^These routi
189a0 6e 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20  nes return 1 if 
189b0 74 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67  the input string
189c0 0a 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62  .** appears to b
189d0 65 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c  e a complete SQL
189e0 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20   statement.  ^A 
189f0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64  statement is jud
18a00 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d  ged to be.** com
18a10 70 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73  plete if it ends
18a20 20 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f   with a semicolo
18a30 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e  n token and is n
18a40 6f 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61  ot a prefix of a
18a50 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20  .** well-formed 
18a60 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73  CREATE TRIGGER s
18a70 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69  tatement.  ^Semi
18a80 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20  colons that are 
18a90 65 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a  embedded within.
18aa0 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61  ** string litera
18ab0 6c 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65  ls or quoted ide
18ac0 6e 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72  ntifier names or
18ad0 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f   comments are no
18ae0 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74  t.** independent
18af0 20 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72   tokens (they ar
18b00 65 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f  e part of the to
18b10 6b 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65  ken in which the
18b20 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65  y are.** embedde
18b30 64 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e  d) and thus do n
18b40 6f 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74  ot count as a st
18b50 61 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74  atement terminat
18b60 6f 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65  or.  ^Whitespace
18b70 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73  .** and comments
18b80 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65   that follow the
18b90 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e   final semicolon
18ba0 20 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a   are ignored..**
18bb0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
18bc0 6e 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20  nes return 0 if 
18bd0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
18be0 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49   incomplete.  ^I
18bf0 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  f a.** memory al
18c00 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20  location fails, 
18c10 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45  then SQLITE_NOME
18c20 4d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  M is returned..*
18c30 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74  *.** ^These rout
18c40 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73  ines do not pars
18c50 65 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  e the SQL statem
18c60 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c  ents thus.** wil
18c70 6c 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e  l not detect syn
18c80 74 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72  tactically incor
18c90 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20  rect SQL..**.** 
18ca0 5e 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20  ^(If SQLite has 
18cb0 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c  not been initial
18cc0 69 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ized using [sqli
18cd0 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
18ce0 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69  ] prior .** to i
18cf0 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f  nvoking sqlite3_
18d00 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65  complete16() the
18d10 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  n sqlite3_initia
18d20 6c 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  lize() is invoke
18d30 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  d.** automatical
18d40 6c 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ly by sqlite3_co
18d50 6d 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20  mplete16().  If 
18d60 74 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74  that initializat
18d70 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68  ion fails,.** th
18d80 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
18d90 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  lue from sqlite3
18da0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69  _complete16() wi
18db0 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a  ll be non-zero.*
18dc0 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
18dd0 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
18de0 68 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20  he input SQL is 
18df0 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a  complete.)^.**.*
18e00 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b  * The input to [
18e10 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
18e20 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
18e30 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
18e40 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a   UTF-8 string..*
18e50 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
18e60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
18e70 65 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65  ete16()] must be
18e80 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
18e90 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
18ea0 69 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79  ing in native by
18eb0 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74  te order..*/.int
18ec0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
18ed0 65 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  e(const char *sq
18ee0 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
18ef0 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74  complete16(const
18f00 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a   void *sql);../*
18f10 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
18f20 67 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63  gister A Callbac
18f30 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49  k To Handle SQLI
18f40 54 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a  TE_BUSY Errors.*
18f50 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
18f60 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 44  3_busy_handler(D
18f70 2c 58 2c 50 29 20 72 6f 75 74 69 6e 65 20 73 65  ,X,P) routine se
18f80 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
18f90 6e 63 74 69 6f 6e 20 58 0a 2a 2a 20 74 68 61 74  nction X.** that
18fa0 20 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65   might be invoke
18fb0 64 20 77 69 74 68 20 61 72 67 75 6d 65 6e 74 20  d with argument 
18fc0 50 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e  P whenever.** an
18fd0 20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65   attempt is made
18fe0 20 74 6f 20 61 63 63 65 73 73 20 61 20 64 61 74   to access a dat
18ff0 61 62 61 73 65 20 74 61 62 6c 65 20 61 73 73 6f  abase table asso
19000 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20 5b  ciated with.** [
19010 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19020 69 6f 6e 5d 20 44 20 77 68 65 6e 20 61 6e 6f 74  ion] D when anot
19030 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72  her thread.** or
19040 20 70 72 6f 63 65 73 73 20 68 61 73 20 74 68 65   process has the
19050 20 74 61 62 6c 65 20 6c 6f 63 6b 65 64 2e 0a 2a   table locked..*
19060 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 62 75  * The sqlite3_bu
19070 73 79 5f 68 61 6e 64 6c 65 72 28 29 20 69 6e 74  sy_handler() int
19080 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
19090 6f 20 69 6d 70 6c 65 6d 65 6e 74 0a 2a 2a 20 5b  o implement.** [
190a0 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69 6d  sqlite3_busy_tim
190b0 65 6f 75 74 28 29 5d 20 61 6e 64 20 5b 50 52 41  eout()] and [PRA
190c0 47 4d 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74  GMA busy_timeout
190d0 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  ]..**.** ^If the
190e0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
190f0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
19100 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 69 73  LITE_BUSY].** is
19110 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69   returned immedi
19120 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75  ately upon encou
19130 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b  ntering the lock
19140 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73 79 20  .  ^If the busy 
19150 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e  callback.** is n
19160 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68  ot NULL, then th
19170 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74  e callback might
19180 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   be invoked with
19190 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a   two arguments..
191a0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74  **.** ^The first
191b0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
191c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73   busy handler is
191d0 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76   a copy of the v
191e0 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69  oid* pointer whi
191f0 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69  ch.** is the thi
19200 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
19210 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19220 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63  ler().  ^The sec
19230 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a  ond argument to.
19240 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ** the busy hand
19250 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ler callback is 
19260 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69  the number of ti
19270 6d 65 73 20 74 68 61 74 20 74 68 65 20 62 75 73  mes that the bus
19280 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a  y handler has.**
19290 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f   been invoked fo
192a0 72 20 74 68 65 20 73 61 6d 65 20 6c 6f 63 6b 69  r the same locki
192b0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
192c0 68 65 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62  he.** busy callb
192d0 61 63 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74  ack returns 0, t
192e0 68 65 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61  hen no additiona
192f0 6c 20 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d  l attempts are m
19300 61 64 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73  ade to.** access
19310 20 74 68 65 20 64 61 74 61 62 61 73 65 20 61 6e   the database an
19320 64 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  d [SQLITE_BUSY] 
19330 69 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 74  is returned.** t
19340 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  o the applicatio
19350 6e 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61  n..** ^If the ca
19360 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e  llback returns n
19370 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e  on-zero, then an
19380 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a  other attempt.**
19390 20 69 73 20 6d 61 64 65 20 74 6f 20 61 63 63 65   is made to acce
193a0 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ss the database 
193b0 61 6e 64 20 74 68 65 20 63 79 63 6c 65 20 72 65  and the cycle re
193c0 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  peats..**.** The
193d0 20 70 72 65 73 65 6e 63 65 20 6f 66 20 61 20 62   presence of a b
193e0 75 73 79 20 68 61 6e 64 6c 65 72 20 64 6f 65 73  usy handler does
193f0 20 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 20 74   not guarantee t
19400 68 61 74 20 69 74 20 77 69 6c 6c 20 62 65 20 69  hat it will be i
19410 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68 65 6e 20 74  nvoked.** when t
19420 68 65 72 65 20 69 73 20 6c 6f 63 6b 20 63 6f 6e  here is lock con
19430 74 65 6e 74 69 6f 6e 2e 20 5e 49 66 20 53 51 4c  tention. ^If SQL
19440 69 74 65 20 64 65 74 65 72 6d 69 6e 65 73 20 74  ite determines t
19450 68 61 74 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65  hat invoking the
19460 20 62 75 73 79 0a 2a 2a 20 68 61 6e 64 6c 65 72   busy.** handler
19470 20 63 6f 75 6c 64 20 72 65 73 75 6c 74 20 69 6e   could result in
19480 20 61 20 64 65 61 64 6c 6f 63 6b 2c 20 69 74 20   a deadlock, it 
19490 77 69 6c 6c 20 67 6f 20 61 68 65 61 64 20 61 6e  will go ahead an
194a0 64 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  d return [SQLITE
194b0 5f 42 55 53 59 5d 0a 2a 2a 20 74 6f 20 74 68 65  _BUSY].** to the
194c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69 6e 73   application ins
194d0 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67  tead of invoking
194e0 20 74 68 65 20 0a 2a 2a 20 62 75 73 79 20 68 61   the .** busy ha
194f0 6e 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64  ndler..** Consid
19500 65 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68  er a scenario wh
19510 65 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20  ere one process 
19520 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61  is holding a rea
19530 64 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69  d lock that.** i
19540 74 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70  t is trying to p
19550 72 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65  romote to a rese
19560 72 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a  rved lock and.**
19570 20 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73   a second proces
19580 73 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72  s is holding a r
19590 65 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61  eserved lock tha
195a0 74 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a  t it is trying.*
195b0 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20  * to promote to 
195c0 61 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63  an exclusive loc
195d0 6b 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72  k.  The first pr
195e0 6f 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f  ocess cannot pro
195f0 63 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20  ceed.** because 
19600 69 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79  it is blocked by
19610 20 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20   the second and 
19620 74 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65  the second proce
19630 73 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f  ss cannot.** pro
19640 63 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20  ceed because it 
19650 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68  is blocked by th
19660 65 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74  e first.  If bot
19670 68 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69  h processes.** i
19680 6e 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68  nvoke the busy h
19690 61 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72  andlers, neither
196a0 20 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70   will make any p
196b0 72 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66  rogress.  Theref
196c0 6f 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72  ore,.** SQLite r
196d0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42  eturns [SQLITE_B
196e0 55 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72  USY] for the fir
196f0 73 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69  st process, hopi
19700 6e 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20  ng that this.** 
19710 77 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20  will induce the 
19720 66 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f  first process to
19730 20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61   release its rea
19740 64 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77  d lock and allow
19750 0a 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70  .** the second p
19760 72 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65  rocess to procee
19770 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  d..**.** ^The de
19780 66 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62  fault busy callb
19790 61 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a  ack is NULL..**.
197a0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
197b0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
197c0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
197d0 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
197e0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
197f0 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
19800 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
19810 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
19820 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
19830 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
19840 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
19850 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
19860 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 6f 72 20 65  meout()].** or e
19870 76 61 6c 75 61 74 69 6e 67 20 5b 50 52 41 47 4d  valuating [PRAGM
19880 41 20 62 75 73 79 5f 74 69 6d 65 6f 75 74 3d 4e  A busy_timeout=N
19890 5d 20 77 69 6c 6c 20 63 68 61 6e 67 65 20 74 68  ] will change th
198a0 65 0a 2a 2a 20 62 75 73 79 20 68 61 6e 64 6c 65  e.** busy handle
198b0 72 20 61 6e 64 20 74 68 75 73 20 63 6c 65 61 72  r and thus clear
198c0 20 61 6e 79 20 70 72 65 76 69 6f 75 73 6c 79 20   any previously 
198d0 73 65 74 20 62 75 73 79 20 68 61 6e 64 6c 65 72  set busy handler
198e0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79  ..**.** The busy
198f0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
19900 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63   not take any ac
19910 74 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69  tions which modi
19920 66 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  fy the.** databa
19930 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
19940 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62  at invoked the b
19950 75 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 49 6e  usy handler.  In
19960 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 0a 2a 2a   other words,.**
19970 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
19980 72 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61  r is not reentra
19990 6e 74 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  nt.  Any such ac
199a0 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
199b0 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
199c0 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
199d0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
199e0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
199f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19a00 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
19a10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
19a20 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
19a30 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
19a40 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
19a50 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
19a60 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
19a70 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
19a80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19a90 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
19aa0 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
19ab0 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
19ac0 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
19ad0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
19ae0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
19af0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
19b00 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
19b10 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
19b20 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
19b30 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
19b40 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
19b50 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
19b60 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
19b70 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
19b80 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
19b90 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
19ba0 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
19bb0 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
19bc0 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
19bd0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
19be0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
19bf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
19c00 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
19c10 54 45 5f 42 55 53 59 5d 2e 0a 2a 2a 0a 2a 2a 20  TE_BUSY]..**.** 
19c20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20 72 6f  ^Calling this ro
19c30 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20 61 72  utine with an ar
19c40 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68 61 6e  gument less than
19c50 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72   or equal to zer
19c60 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66 20 61  o.** turns off a
19c70 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73  ll busy handlers
19c80 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20  ..**.** ^(There 
19c90 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69  can only be a si
19ca0 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65  ngle busy handle
19cb0 72 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  r for a particul
19cc0 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  ar.** [database 
19cd0 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 79 20  connection] any 
19ce0 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65 6e 74  any given moment
19cf0 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20 62 75  .  If another bu
19d00 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 61  sy handler.** wa
19d10 73 20 64 65 66 69 6e 65 64 20 20 28 75 73 69 6e  s defined  (usin
19d20 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f  g [sqlite3_busy_
19d30 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72 69 6f  handler()]) prio
19d40 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20  r to calling.** 
19d50 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 74 68  this routine, th
19d60 61 74 20 6f 74 68 65 72 20 62 75 73 79 20 68 61  at other busy ha
19d70 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72 65 64  ndler is cleared
19d80 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
19d90 73 6f 3a 20 20 5b 50 52 41 47 4d 41 20 62 75 73  so:  [PRAGMA bus
19da0 79 5f 74 69 6d 65 6f 75 74 5d 0a 2a 2f 0a 69 6e  y_timeout].*/.in
19db0 74 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74  t sqlite3_busy_t
19dc0 69 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c  imeout(sqlite3*,
19dd0 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a   int ms);../*.**
19de0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65   CAPI3REF: Conve
19df0 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20  nience Routines 
19e00 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72  For Running Quer
19e10 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69  ies.**.** This i
19e20 73 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72  s a legacy inter
19e30 66 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65  face that is pre
19e40 73 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77  served for backw
19e50 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
19e60 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68  ty..** Use of th
19e70 69 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  is interface is 
19e80 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e  not recommended.
19e90 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f  .**.** Definitio
19ea0 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74  n: A <b>result t
19eb0 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f  able</b> is memo
19ec0 72 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72  ry data structur
19ed0 65 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65  e created by the
19ee0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  .** [sqlite3_get
19ef0 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66  _table()] interf
19f00 61 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74  ace.  A result t
19f10 61 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65  able records the
19f20 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65  .** complete que
19f30 72 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20  ry results from 
19f40 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72  one or more quer
19f50 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ies..**.** The t
19f60 61 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c  able conceptuall
19f70 79 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f  y has a number o
19f80 66 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d  f rows and colum
19f90 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73  ns.  But.** thes
19fa0 65 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f  e numbers are no
19fb0 74 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65  t part of the re
19fc0 73 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c  sult table itsel
19fd0 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d  f.  These.** num
19fe0 62 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65  bers are obtaine
19ff0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c  d separately.  L
1a000 65 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62  et N be the numb
1a010 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e  er of rows.** an
1a020 64 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65  d M be the numbe
1a030 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a  r of columns..**
1a040 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
1a050 6c 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f  le is an array o
1a060 66 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65  f pointers to ze
1a070 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
1a080 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  F-8 strings..** 
1a090 54 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a  There are (N+1)*
1a0a0 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68  M elements in th
1a0b0 65 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69  e array.  The fi
1a0c0 72 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70  rst M pointers p
1a0d0 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d  oint.** to zero-
1a0e0 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e  terminated strin
1a0f0 67 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e  gs that  contain
1a100 20 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68   the names of th
1a110 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68  e columns..** Th
1a120 65 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72  e remaining entr
1a130 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f  ies all point to
1a140 20 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20   query results. 
1a150 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73   NULL values res
1a160 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70  ult.** in NULL p
1a170 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74  ointers.  All ot
1a180 68 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69  her values are i
1a190 6e 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65  n their UTF-8 ze
1a1a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
1a1b0 20 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e   string represen
1a1c0 74 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e  tation as return
1a1d0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63  ed by [sqlite3_c
1a1e0 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a  olumn_text()]..*
1a1f0 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61  *.** A result ta
1a200 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73  ble might consis
1a210 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65  t of one or more
1a220 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
1a230 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f  ons..** It is no
1a240 74 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61  t safe to pass a
1a250 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69   result table di
1a260 72 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74  rectly to [sqlit
1a270 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41  e3_free()]..** A
1a280 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68   result table sh
1a290 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61  ould be dealloca
1a2a0 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
1a2b0 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d  e3_free_table()]
1a2c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20  ..**.** ^(As an 
1a2d0 65 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72  example of the r
1a2e0 65 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d  esult table form
1a2f0 61 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75  at, suppose a qu
1a300 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73  ery result.** is
1a310 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1a320 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1a330 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e  pre>.**        N
1a340 61 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65  ame        | Age
1a350 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d  .**        -----
1a360 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
1a370 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69  --.**        Ali
1a380 63 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a  ce       | 43.**
1a390 20 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20          Bob     
1a3a0 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20      | 28.**     
1a3b0 20 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c     Cindy       |
1a3c0 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62   21.** </pre></b
1a3d0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a  lockquote>.**.**
1a3e0 20 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63   There are two c
1a3f0 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64  olumn (M==2) and
1a400 20 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d   three rows (N==
1a410 33 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a  3).  Thus the.**
1a420 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61   result table ha
1a430 73 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75  s 8 entries.  Su
1a440 70 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74  ppose the result
1a450 20 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64   table is stored
1a460 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20  .** in an array 
1a470 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20  names azResult. 
1a480 20 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68   Then azResult h
1a490 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e  olds this conten
1a4a0 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71  t:.**.** <blockq
1a4b0 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20  uote><pre>.**   
1a4c0 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
1a4d0 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a  1;0] = "Name";.*
1a4e0 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
1a4f0 74 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22  t&#91;1] = "Age"
1a500 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
1a510 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41  sult&#91;2] = "A
1a520 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20  lice";.**       
1a530 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d   azResult&#91;3]
1a540 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20   = "43";.**     
1a550 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
1a560 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20  4] = "Bob";.**  
1a570 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
1a580 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a  91;5] = "28";.**
1a590 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
1a5a0 26 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79  &#91;6] = "Cindy
1a5b0 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52  ";.**        azR
1a5c0 65 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22  esult&#91;7] = "
1a5d0 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f  21";.** </pre></
1a5e0 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
1a5f0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
1a600 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e  _get_table() fun
1a610 63 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20  ction evaluates 
1a620 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73  one or more.** s
1a630 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
1a640 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ed SQL statement
1a650 73 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65  s in the zero-te
1a660 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a  rminated UTF-8.*
1a670 2a 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20  * string of its 
1a680 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e  2nd parameter an
1a690 64 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75  d returns a resu
1a6a0 6c 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a  lt table to the.
1a6b0 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e  ** pointer given
1a6c0 20 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61   in its 3rd para
1a6d0 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74  meter..**.** Aft
1a6e0 65 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  er the applicati
1a6f0 6f 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  on has finished 
1a700 77 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20  with the result 
1a710 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74  from sqlite3_get
1a720 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20  _table(),.** it 
1a730 6d 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65  must pass the re
1a740 73 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74  sult table point
1a750 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72  er to sqlite3_fr
1a760 65 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72  ee_table() in or
1a770 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73  der to.** releas
1a780 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61  e the memory tha
1a790 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20  t was malloced. 
1a7a0 20 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20   Because of the 
1a7b0 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  way the.** [sqli
1a7c0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61  te3_malloc()] ha
1a7d0 70 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c  ppens within sql
1a7e0 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
1a7f0 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a  , the calling.**
1a800 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e   function must n
1a810 6f 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b  ot try to call [
1a820 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20  sqlite3_free()] 
1a830 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a  directly.  Only.
1a840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
1a850 5f 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c  _table()] is abl
1a860 65 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65  e to release the
1a870 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79   memory properly
1a880 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a   and safely..**.
1a890 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67  ** The sqlite3_g
1a8a0 65 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72  et_table() inter
1a8b0 66 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e  face is implemen
1a8c0 74 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72  ted as a wrapper
1a8d0 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69   around.** [sqli
1a8e0 74 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68  te3_exec()].  Th
1a8f0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
1a900 62 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f  ble() routine do
1a910 65 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65  es not have acce
1a920 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74  ss.** to any int
1a930 65 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63  ernal data struc
1a940 74 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  tures of SQLite.
1a950 20 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74    It uses only t
1a960 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74  he public.** int
1a970 65 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68  erface defined h
1a980 65 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65  ere.  As a conse
1a990 71 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74  quence, errors t
1a9a0 68 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65  hat occur in the
1a9b0 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65  .** wrapper laye
1a9c0 72 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65  r outside of the
1a9d0 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74   internal [sqlit
1a9e0 65 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20  e3_exec()] call 
1a9f0 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65  are not.** refle
1aa00 63 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65  cted in subseque
1aa10 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  nt calls to [sql
1aa20 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20  ite3_errcode()] 
1aa30 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  or.** [sqlite3_e
1aa40 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  rrmsg()]..*/.int
1aa50 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
1aa60 6c 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  le(.  sqlite3 *d
1aa70 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41  b,          /* A
1aa80 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20  n open database 
1aa90 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
1aaa0 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51  *zSql,     /* SQ
1aab0 4c 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65  L to be evaluate
1aac0 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70  d */.  char ***p
1aad0 61 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20  azResult,    /* 
1aae0 52 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71  Results of the q
1aaf0 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  uery */.  int *p
1ab00 6e 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20  nRow,           
1ab10 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
1ab20 75 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e  ult rows written
1ab30 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a   here */.  int *
1ab40 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20  pnColumn,       
1ab50 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65   /* Number of re
1ab60 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69  sult columns wri
1ab70 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63  tten here */.  c
1ab80 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20  har **pzErrmsg  
1ab90 20 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73       /* Error ms
1aba0 67 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a  g written here *
1abb0 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  /.);.void sqlite
1abc0 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61  3_free_table(cha
1abd0 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a  r **result);../*
1abe0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f  .** CAPI3REF: Fo
1abf0 72 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50  rmatted String P
1ac00 72 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e  rinting Function
1ac10 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  s.**.** These ro
1ac20 75 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d  utines are work-
1ac30 61 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70  alikes of the "p
1ac40 72 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20  rintf()" family 
1ac50 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  of functions.** 
1ac60 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72  from the standar
1ac70 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a  d C library..**.
1ac80 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1ac90 6d 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71  mprintf() and sq
1aca0 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29  lite3_vmprintf()
1acb0 20 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20   routines write 
1acc0 74 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73  their.** results
1acd0 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
1ace0 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
1acf0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a  te3_malloc()]..*
1ad00 2a 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65  * The strings re
1ad10 74 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20  turned by these 
1ad20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f  two routines sho
1ad30 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73  uld be.** releas
1ad40 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
1ad50 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72  ree()].  ^Both r
1ad60 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61  outines return a
1ad70 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  .** NULL pointer
1ad80 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c   if [sqlite3_mal
1ad90 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65  loc()] is unable
1ada0 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f   to allocate eno
1adb0 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f  ugh.** memory to
1adc0 20 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74   hold the result
1add0 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  ing string..**.*
1ade0 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f  * ^(The sqlite3_
1adf0 73 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69  snprintf() routi
1ae00 6e 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f  ne is similar to
1ae10 20 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72   "snprintf()" fr
1ae20 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61  om.** the standa
1ae30 72 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54  rd C library.  T
1ae40 68 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69  he result is wri
1ae50 74 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a  tten into the.**
1ae60 20 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64   buffer supplied
1ae70 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70   as the second p
1ae80 61 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73  arameter whose s
1ae90 69 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a  ize is given by.
1aea0 2a 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72  ** the first par
1aeb0 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61  ameter. Note tha
1aec0 74 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74  t the order of t
1aed0 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20  he.** first two 
1aee0 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65  parameters is re
1aef0 76 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72  versed from snpr
1af00 69 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20  intf().)^  This 
1af10 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69  is an.** histori
1af20 63 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61  cal accident tha
1af30 74 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65  t cannot be fixe
1af40 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
1af50 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20  ng.** backwards 
1af60 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20  compatibility.  
1af70 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74  ^(Note also that
1af80 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74   sqlite3_snprint
1af90 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61  f().** returns a
1afa0 20 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20   pointer to its 
1afb0 62 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f  buffer instead o
1afc0 66 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a  f the number of.
1afd0 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63  ** characters ac
1afe0 74 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69  tually written i
1aff0 6e 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29  nto the buffer.)
1b000 5e 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74  ^  We admit that
1b010 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  .** the number o
1b020 66 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69  f characters wri
1b030 74 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20  tten would be a 
1b040 6d 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75  more useful retu
1b050 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20  rn.** value but 
1b060 77 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65  we cannot change
1b070 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
1b080 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73  ion of sqlite3_s
1b090 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77  nprintf().** now
1b0a0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
1b0b0 67 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e  g compatibility.
1b0c0 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20  .**.** ^As long 
1b0d0 61 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69  as the buffer si
1b0e0 7a 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68  ze is greater th
1b0f0 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33  an zero, sqlite3
1b100 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67  _snprintf().** g
1b110 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
1b120 68 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77  he buffer is alw
1b130 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  ays zero-termina
1b140 74 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ted.  ^The first
1b150 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e  .** parameter "n
1b160 22 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73  " is the total s
1b170 69 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65  ize of the buffe
1b180 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61  r, including spa
1b190 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65  ce for.** the ze
1b1a0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  ro terminator.  
1b1b0 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73  So the longest s
1b1c0 74 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62  tring that can b
1b1d0 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20  e completely.** 
1b1e0 77 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20  written will be 
1b1f0 6e 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a  n-1 characters..
1b200 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
1b210 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72  e3_vsnprintf() r
1b220 6f 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61  outine is a vara
1b230 72 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73  rgs version of s
1b240 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
1b250 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )..**.** These r
1b260 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c  outines all impl
1b270 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74  ement some addit
1b280 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67  ional formatting
1b290 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74  .** options that
1b2a0 20 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20   are useful for 
1b2b0 63 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c  constructing SQL
1b2c0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20   statements..** 
1b2d0 41 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c  All of the usual
1b2e0 20 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74   printf() format
1b2f0 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70  ting options app
1b300 6c 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e  ly.  In addition
1b310 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72  , there.** is ar
1b320 65 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e  e "%q", "%Q", an
1b330 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a  d "%z" options..
1b340 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f  **.** ^(The %q o
1b350 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65  ption works like
1b360 20 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73   %s in that it s
1b370 75 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c  ubstitutes a nul
1b380 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
1b390 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
1b3a0 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
1b3b0 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
1b3c0 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
1b3d0 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
1b3e0 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
1b3f0 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
1b400 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
1b410 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
1b420 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
1b430 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
1b440 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
1b450 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
1b460 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
1b470 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
1b480 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
1b490 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
1b4a0 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
1b4b0 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
1b4c0 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
1b4d0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
1b4e0 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
1b4f0 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
1b500 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
1b510 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
1b520 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
1b530 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
1b540 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1b550 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
1b560 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
1b570 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
1b580 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
1b590 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
1b5a0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
1b5b0 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
1b5c0 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
1b5d0 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
1b5e0 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
1b5f0 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
1b600 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
1b610 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
1b620 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
1b630 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
1b640 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
1b650 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
1b660 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
1b670 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
1b680 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
1b690 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
1b6a0 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
1b6b0 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
1b6c0 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
1b6d0 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
1b6e0 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
1b6f0 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
1b700 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
1b710 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
1b720 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
1b730 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
1b740 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
1b750 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
1b760 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
1b770 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
1b780 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
1b790 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
1b7a0 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
1b7b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
1b7c0 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
1b7d0 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
1b7e0 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
1b7f0 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
1b800 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
1b810 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
1b820 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
1b830 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
1b840 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
1b850 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
1b860 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
1b870 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
1b880 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
1b890 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
1b8a0 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
1b8b0 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
1b8c0 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
1b8d0 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
1b8e0 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
1b8f0 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
1b900 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
1b910 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
1b920 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
1b930 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
1b940 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
1b950 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
1b960 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
1b970 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
1b980 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
1b990 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
1b9a0 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
1b9b0 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
1b9c0 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
1b9d0 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
1b9e0 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
1b9f0 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
1ba00 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
1ba10 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
1ba20 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
1ba30 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
1ba40 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
1ba50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
1ba60 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
1ba70 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
1ba80 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
1ba90 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
1baa0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
1bab0 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
1bac0 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
1bad0 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
1bae0 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
1baf0 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
1bb00 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
1bb10 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
1bb20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
1bb30 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
1bb40 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
1bb50 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
1bb60 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
1bb70 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
1bb80 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
1bb90 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
1bba0 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
1bbb0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
1bbc0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
1bbd0 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
1bbe0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
1bbf0 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
1bc00 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
1bc10 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
1bc20 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
1bc30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1bc40 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
1bc50 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
1bc60 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
1bc70 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
1bc80 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
1bc90 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
1bca0 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
1bcb0 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
1bcc0 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
1bcd0 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
1bce0 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
1bcf0 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
1bd00 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
1bd10 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1bd20 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
1bd30 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
1bd40 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
1bd50 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
1bd60 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
1bd70 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
1bd80 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
1bd90 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
1bda0 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
1bdb0 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
1bdc0 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
1bdd0 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
1bde0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
1bdf0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
1be00 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
1be10 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
1be20 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
1be30 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
1be40 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
1be50 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
1be60 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
1be70 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
1be80 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
1be90 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
1bea0 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
1beb0 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
1bec0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
1bed0 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
1bee0 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
1bef0 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
1bf00 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
1bf10 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
1bf20 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
1bf30 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
1bf40 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
1bf50 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
1bf60 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1bf70 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
1bf80 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
1bf90 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
1bfa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
1bfb0 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
1bfc0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
1bfd0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
1bfe0 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
1bff0 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
1c000 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
1c010 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
1c020 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
1c030 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
1c040 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
1c050 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
1c060 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
1c070 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
1c080 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
1c090 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
1c0a0 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
1c0b0 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
1c0c0 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
1c0d0 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
1c0e0 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
1c0f0 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
1c100 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
1c110 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
1c120 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
1c130 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
1c140 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
1c150 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
1c160 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
1c170 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
1c180 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
1c190 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
1c1a0 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
1c1b0 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
1c1c0 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
1c1d0 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
1c1e0 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
1c1f0 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
1c200 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
1c210 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
1c220 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
1c230 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
1c240 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
1c250 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c260 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
1c270 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
1c280 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
1c290 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
1c2a0 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
1c2b0 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
1c2c0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
1c2d0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1c2e0 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
1c2f0 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
1c300 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1c310 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
1c320 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
1c330 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
1c340 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
1c350 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
1c360 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
1c370 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
1c380 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
1c390 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
1c3a0 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
1c3b0 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1c3c0 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
1c3d0 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
1c3e0 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
1c3f0 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
1c400 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
1c410 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
1c420 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
1c430 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
1c440 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
1c450 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1c460 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
1c470 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
1c480 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
1c490 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
1c4a0 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
1c4b0 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
1c4c0 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
1c4d0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
1c4e0 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
1c4f0 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
1c500 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
1c510 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
1c520 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
1c530 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
1c540 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
1c550 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
1c560 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
1c570 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
1c580 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
1c590 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
1c5a0 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
1c5b0 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
1c5c0 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
1c5d0 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
1c5e0 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
1c5f0 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
1c600 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
1c610 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
1c620 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
1c630 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
1c640 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
1c650 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
1c660 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
1c670 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
1c680 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
1c690 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
1c6a0 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
1c6b0 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
1c6c0 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
1c6d0 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
1c6e0 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
1c6f0 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
1c700 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
1c710 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
1c720 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
1c730 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
1c740 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74 6f 20 53  **.** Prior to S
1c750 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
1c760 37 2e 31 30 2c 20 74 68 65 20 57 69 6e 64 6f 77  7.10, the Window
1c770 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
1c780 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a 2a 20 74  ayer called.** t
1c790 68 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63  he system malloc
1c7a0 28 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69  () and free() di
1c7b0 72 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76  rectly when conv
1c7c0 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61  erting.** filena
1c7d0 6d 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20  mes between the 
1c7e0 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75  UTF-8 encoding u
1c7f0 73 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  sed by SQLite.**
1c800 20 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69   and whatever fi
1c810 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20  lename encoding 
1c820 69 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70  is used by the p
1c830 61 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77  articular Window
1c840 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f  s.** installatio
1c850 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63  n.  Memory alloc
1c860 61 74 69 6f 6e 20 65 72 72 6f 72 73 20 77 65 72  ation errors wer
1c870 65 20 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a  e detected, but.
1c880 2a 2a 20 74 68 65 79 20 77 65 72 65 20 72 65 70  ** they were rep
1c890 6f 72 74 65 64 20 62 61 63 6b 20 61 73 20 5b 53  orted back as [S
1c8a0 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
1c8b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f  or.** [SQLITE_IO
1c8c0 45 52 52 5d 20 72 61 74 68 65 72 20 74 68 61 6e  ERR] rather than
1c8d0 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e   [SQLITE_NOMEM].
1c8e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74  .**.** The point
1c8f0 65 72 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20  er arguments to 
1c900 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
1c910 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65   and [sqlite3_re
1c920 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74  alloc()].** must
1c930 20 62 65 20 65 69 74 68 65 72 20 4e 55 4c 4c 20   be either NULL 
1c940 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74 65 72 73  or else pointers
1c950 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61   obtained from a
1c960 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61   prior.** invoca
1c970 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33  tion of [sqlite3
1c980 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73  _malloc()] or [s
1c990 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
1c9a0 5d 20 74 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e  ] that have.** n
1c9b0 6f 74 20 79 65 74 20 62 65 65 6e 20 72 65 6c 65  ot yet been rele
1c9c0 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ased..**.** The 
1c9d0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
1c9e0 20 6e 6f 74 20 72 65 61 64 20 6f 72 20 77 72 69   not read or wri
1c9f0 74 65 20 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a  te any part of.*
1ca00 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d  * a block of mem
1ca10 6f 72 79 20 61 66 74 65 72 20 69 74 20 68 61 73  ory after it has
1ca20 20 62 65 65 6e 20 72 65 6c 65 61 73 65 64 20 75   been released u
1ca30 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  sing.** [sqlite3
1ca40 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c  _free()] or [sql
1ca50 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e  ite3_realloc()].
1ca60 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
1ca70 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76  3_malloc(int);.v
1ca80 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 65 61  oid *sqlite3_rea
1ca90 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29  lloc(void*, int)
1caa0 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66  ;.void sqlite3_f
1cab0 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  ree(void*);../*.
1cac0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
1cad0 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74  ory Allocator St
1cae0 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53  atistics.**.** S
1caf0 51 4c 69 74 65 20 70 72 6f 76 69 64 65 73 20 74  QLite provides t
1cb00 68 65 73 65 20 74 77 6f 20 69 6e 74 65 72 66 61  hese two interfa
1cb10 63 65 73 20 66 6f 72 20 72 65 70 6f 72 74 69 6e  ces for reportin
1cb20 67 20 6f 6e 20 74 68 65 20 73 74 61 74 75 73 0a  g on the status.
1cb30 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ** of the [sqlit
1cb40 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73  e3_malloc()], [s
1cb50 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2c 20  qlite3_free()], 
1cb60 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61  and [sqlite3_rea
1cb70 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69  lloc()].** routi
1cb80 6e 65 73 2c 20 77 68 69 63 68 20 66 6f 72 6d 20  nes, which form 
1cb90 74 68 65 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  the built-in mem
1cba0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73  ory allocation s
1cbb0 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20  ubsystem..**.** 
1cbc0 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65  ^The [sqlite3_me
1cbd0 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 72 6f 75  mory_used()] rou
1cbe0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1cbf0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
1cc00 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75  .** of memory cu
1cc10 72 72 65 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64  rrently outstand
1cc20 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75  ing (malloced bu
1cc30 74 20 6e 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a  t not freed)..**
1cc40 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d   ^The [sqlite3_m
1cc50 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
1cc60 29 5d 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  )] routine retur
1cc70 6e 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a  ns the maximum.*
1cc80 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69  * value of [sqli
1cc90 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
1cca0 29 5d 20 73 69 6e 63 65 20 74 68 65 20 68 69 67  )] since the hig
1ccb0 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20  h-water mark.** 
1ccc0 77 61 73 20 6c 61 73 74 20 72 65 73 65 74 2e 20  was last reset. 
1ccd0 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65 74   ^The values ret
1cce0 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
1ccf0 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d  3_memory_used()]
1cd00 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
1cd10 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1cd20 72 28 29 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79  r()] include any
1cd30 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20 61 64 64   overhead.** add
1cd40 65 64 20 62 79 20 53 51 4c 69 74 65 20 69 6e 20  ed by SQLite in 
1cd50 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  its implementati
1cd60 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d  on of [sqlite3_m
1cd70 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74  alloc()],.** but
1cd80 20 6e 6f 74 20 6f 76 65 72 68 65 61 64 20 61 64   not overhead ad
1cd90 64 65 64 20 62 79 20 74 68 65 20 61 6e 79 20 75  ded by the any u
1cda0 6e 64 65 72 6c 79 69 6e 67 20 73 79 73 74 65 6d  nderlying system
1cdb0 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74   library.** rout
1cdc0 69 6e 65 73 20 74 68 61 74 20 5b 73 71 6c 69 74  ines that [sqlit
1cdd0 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79  e3_malloc()] may
1cde0 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   call..**.** ^Th
1cdf0 65 20 6d 65 6d 6f 72 79 20 68 69 67 68 2d 77 61  e memory high-wa
1ce00 74 65 72 20 6d 61 72 6b 20 69 73 20 72 65 73 65  ter mark is rese
1ce10 74 20 74 6f 20 74 68 65 20 63 75 72 72 65 6e 74  t to the current
1ce20 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71   value of.** [sq
1ce30 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65  lite3_memory_use
1ce40 64 28 29 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79  d()] if and only
1ce50 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   if the paramete
1ce60 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  r to.** [sqlite3
1ce70 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
1ce80 72 28 29 5d 20 69 73 20 74 72 75 65 2e 20 20 5e  r()] is true.  ^
1ce90 54 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e  The value return
1cea0 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65  ed.** by [sqlite
1ceb0 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1cec0 65 72 28 31 29 5d 20 69 73 20 74 68 65 20 68 69  er(1)] is the hi
1ced0 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a  gh-water mark.**
1cee0 20 70 72 69 6f 72 20 74 6f 20 74 68 65 20 72 65   prior to the re
1cef0 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  set..*/.sqlite3_
1cf00 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 6d 65  int64 sqlite3_me
1cf10 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69 64 29 3b  mory_used(void);
1cf20 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
1cf30 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69  qlite3_memory_hi
1cf40 67 68 77 61 74 65 72 28 69 6e 74 20 72 65 73 65  ghwater(int rese
1cf50 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  tFlag);../*.** C
1cf60 41 50 49 33 52 45 46 3a 20 50 73 65 75 64 6f 2d  API3REF: Pseudo-
1cf70 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65  Random Number Ge
1cf80 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51  nerator.**.** SQ
1cf90 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73 20 61 20  Lite contains a 
1cfa0 68 69 67 68 2d 71 75 61 6c 69 74 79 20 70 73 65  high-quality pse
1cfb0 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65  udo-random numbe
1cfc0 72 20 67 65 6e 65 72 61 74 6f 72 20 28 50 52 4e  r generator (PRN
1cfd0 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65  G) used to.** se
1cfe0 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57  lect random [ROW
1cff0 49 44 20 7c 20 52 4f 57 49 44 73 5d 20 77 68 65  ID | ROWIDs] whe
1d000 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e 65 77 20  n inserting new 
1d010 72 65 63 6f 72 64 73 20 69 6e 74 6f 20 61 20 74  records into a t
1d020 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72  able that.** alr
1d030 65 61 64 79 20 75 73 65 73 20 74 68 65 20 6c 61  eady uses the la
1d040 72 67 65 73 74 20 70 6f 73 73 69 62 6c 65 20 5b  rgest possible [
1d050 52 4f 57 49 44 5d 2e 20 20 54 68 65 20 50 52 4e  ROWID].  The PRN
1d060 47 20 69 73 20 61 6c 73 6f 20 75 73 65 64 20 66  G is also used f
1d070 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d  or.** the build-
1d080 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20  in random() and 
1d090 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c  randomblob() SQL
1d0a0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69   functions.  Thi
1d0b0 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f  s interface allo
1d0c0 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  ws.** applicatio
1d0d0 6e 73 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ns to access the
1d0e0 20 73 61 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f   same PRNG for o
1d0f0 74 68 65 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a  ther purposes..*
1d100 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  *.** ^A call to 
1d110 74 68 69 73 20 72 6f 75 74 69 6e 65 20 73 74 6f  this routine sto
1d120 72 65 73 20 4e 20 62 79 74 65 73 20 6f 66 20 72  res N bytes of r
1d130 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62  andomness into b
1d140 75 66 66 65 72 20 50 2e 0a 2a 2a 20 5e 49 66 20  uffer P..** ^If 
1d150 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
1d160 6e 65 2c 20 74 68 65 6e 20 50 20 63 61 6e 20 62  ne, then P can b
1d170 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  e a NULL pointer
1d180 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 69 73  ..**.** ^If this
1d190 20 72 6f 75 74 69 6e 65 20 68 61 73 20 6e 6f 74   routine has not
1d1a0 20 62 65 65 6e 20 70 72 65 76 69 6f 75 73 6c 79   been previously
1d1b0 20 63 61 6c 6c 65 64 20 6f 72 20 69 66 20 74 68   called or if th
1d1c0 65 20 70 72 65 76 69 6f 75 73 0a 2a 2a 20 63 61  e previous.** ca
1d1d0 6c 6c 20 68 61 64 20 4e 20 6c 65 73 73 20 74 68  ll had N less th
1d1e0 61 6e 20 6f 6e 65 2c 20 74 68 65 6e 20 74 68 65  an one, then the
1d1f0 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
1d200 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
1d210 0a 2a 2a 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  .** obtained fro
1d220 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
1d230 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
1d240 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
1d250 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
1d260 20 5e 49 66 20 74 68 65 20 70 72 65 76 69 6f 75   ^If the previou
1d270 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72  s call to this r
1d280 6f 75 74 69 6e 65 20 68 61 64 20 61 6e 20 4e 20  outine had an N 
1d290 6f 66 20 31 20 6f 72 20 6d 6f 72 65 20 74 68 65  of 1 or more the
1d2a0 6e 0a 2a 2a 20 74 68 65 20 70 73 65 75 64 6f 2d  n.** the pseudo-
1d2b0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
1d2c0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
1d2d0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
1d2e0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
1d2f0 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
1d300 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
1d310 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
1d320 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
1d330 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
1d340 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1d350 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
1d360 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
1d370 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1d380 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
1d390 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
1d3a0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
1d3b0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
1d3c0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1d3d0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
1d3e0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
1d3f0 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
1d400 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1d410 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1d420 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
1d430 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
1d440 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
1d450 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
1d460 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
1d470 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d480 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
1d490 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
1d4a0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
1d4b0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
1d4c0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
1d4d0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
1d4e0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
1d4f0 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
1d500 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
1d510 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
1d520 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
1d530 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1d540 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1d550 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
1d560 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
1d570 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
1d580 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1d590 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
1d5a0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
1d5b0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
1d5c0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
1d5d0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
1d5e0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
1d5f0 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
1d600 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
1d610 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
1d620 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
1d630 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
1d640 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
1d650 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
1d660 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
1d670 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
1d680 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
1d690 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1d6a0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
1d6b0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
1d6c0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
1d6d0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
1d6e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
1d6f0 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
1d700 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1d710 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
1d720 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
1d730 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
1d740 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
1d750 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
1d760 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
1d770 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
1d780 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
1d790 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
1d7a0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
1d7b0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
1d7c0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
1d7d0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1d7e0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
1d7f0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
1d800 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
1d810 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
1d820 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
1d830 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
1d840 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
1d850 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
1d860 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
1d870 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
1d880 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
1d890 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
1d8a0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
1d8b0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
1d8c0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
1d8d0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
1d8e0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
1d8f0 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1d900 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
1d910 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
1d920 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
1d930 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1d940 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
1d950 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
1d960 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
1d970 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
1d980 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
1d990 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
1d9a0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
1d9b0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
1d9c0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
1d9d0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
1d9e0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
1d9f0 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
1da00 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
1da10 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
1da20 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
1da30 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1da40 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
1da50 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
1da60 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
1da70 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
1da80 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
1da90 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
1daa0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
1dab0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
1dac0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
1dad0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
1dae0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
1daf0 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
1db00 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
1db10 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
1db20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
1db30 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
1db40 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
1db50 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
1db60 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
1db70 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
1db80 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
1db90 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
1dba0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
1dbb0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
1dbc0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
1dbd0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
1dbe0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
1dbf0 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
1dc00 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
1dc10 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
1dc20 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
1dc30 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
1dc40 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
1dc50 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
1dc60 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
1dc70 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
1dc80 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
1dc90 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
1dca0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
1dcb0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
1dcc0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
1dcd0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
1dce0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
1dcf0 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
1dd00 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
1dd10 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
1dd20 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
1dd30 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
1dd40 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
1dd50 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
1dd60 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
1dd70 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
1dd80 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
1dd90 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
1dda0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
1ddb0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
1ddc0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
1ddd0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
1dde0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
1ddf0 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
1de00 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
1de10 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
1de20 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
1de30 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
1de40 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
1de50 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
1de60 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
1de70 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
1de80 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
1de90 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
1dea0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
1deb0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
1dec0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
1ded0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
1dee0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
1def0 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
1df00 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
1df10 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1df20 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
1df30 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
1df40 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
1df50 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
1df60 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
1df70 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
1df80 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
1df90 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
1dfa0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
1dfb0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
1dfc0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
1dfd0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
1dfe0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
1dff0 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
1e000 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
1e010 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
1e020 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
1e030 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
1e040 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
1e050 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
1e060 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
1e070 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
1e080 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
1e090 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
1e0a0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
1e0b0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
1e0c0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
1e0d0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
1e0e0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
1e0f0 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
1e100 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
1e110 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
1e120 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1e130 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1e140 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1e150 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1e160 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1e170 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1e180 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1e190 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
1e1a0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
1e1b0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
1e1c0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1e1d0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
1e1e0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1e1f0 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
1e200 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
1e210 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
1e220 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
1e230 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
1e240 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
1e250 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
1e260 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
1e270 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
1e280 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
1e290 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
1e2a0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
1e2b0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
1e2c0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
1e2d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
1e2e0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
1e2f0 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
1e300 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1e310 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
1e320 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
1e330 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1e340 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
1e350 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
1e360 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
1e370 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
1e380 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
1e390 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
1e3a0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
1e3b0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
1e3c0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
1e3d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
1e3e0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1e3f0 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1e400 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1e410 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1e420 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1e430 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1e440 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1e450 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1e460 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1e470 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1e480 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1e490 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1e4a0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1e4b0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1e4c0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1e4d0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1e4e0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1e4f0 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1e500 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1e510 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1e520 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1e530 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1e540 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1e550 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e560 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1e570 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1e580 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1e590 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1e5a0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1e5b0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1e5c0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1e5d0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1e5e0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1e5f0 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1e600 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1e610 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1e620 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1e630 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1e640 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1e650 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1e660 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1e670 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1e680 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1e690 20 61 73 20 61 20 5b 63 6f 6e 66 6c 69 63 74 20   as a [conflict 
1e6a0 72 65 73 6f 6c 75 74 69 6f 6e 20 6d 6f 64 65 5d  resolution mode]
1e6b0 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 66 72 6f  .** returned fro
1e6c0 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76  m the [sqlite3_v
1e6d0 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28  tab_on_conflict(
1e6e0 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2f  )] interface..*/
1e6f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1e700 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20 41 62  DENY   1   /* Ab
1e710 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74 61 74  ort the SQL stat
1e720 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20 65 72  ement with an er
1e730 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ror */.#define S
1e740 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32 20 20  QLITE_IGNORE 2  
1e750 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f 77 20   /* Don't allow 
1e760 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f 6e 27  access, but don'
1e770 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20 65 72  t generate an er
1e780 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41  ror */../*.** CA
1e790 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1e7a0 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65 73 0a  er Action Codes.
1e7b0 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1e7c0 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1e7d0 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  r()] interface r
1e7e0 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
1e7f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
1e800 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65 64 20  that is invoked 
1e810 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63 65 72  to authorize cer
1e820 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  tain SQL stateme
1e830 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54 68 65  nt actions.  The
1e840 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  .** second param
1e850 65 74 65 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  eter to the call
1e860 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67  back is an integ
1e870 65 72 20 63 6f 64 65 20 74 68 61 74 20 73 70 65  er code that spe
1e880 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74 20 61  cifies.** what a
1e890 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67 20 61  ction is being a
1e8a0 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65 73  uthorized.  Thes
1e8b0 65 20 61 72 65 20 74 68 65 20 69 6e 74 65 67 65  e are the intege
1e8c0 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73 20 74  r action codes t
1e8d0 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74 68 6f  hat.** the autho
1e8e0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d  rizer callback m
1e8f0 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a 2a 2a  ay be passed..**
1e900 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69 6f 6e  .** These action
1e910 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73 69 67   code values sig
1e920 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64 20 6f  nify what kind o
1e930 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 74  f operation is t
1e940 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a  o be.** authoriz
1e950 65 64 2e 20 20 54 68 65 20 33 72 64 20 61 6e 64  ed.  The 3rd and
1e960 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 73 20   4th parameters 
1e970 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 61  to the authoriza
1e980 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b  tion.** callback
1e990 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c 20 62   function will b
1e9a0 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f 72 20  e parameters or 
1e9b0 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67 20 6f  NULL depending o
1e9c0 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65 73 65  n which of these
1e9d0 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75 73 65  .** codes is use
1e9e0 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20  d as the second 
1e9f0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28 54 68  parameter.  ^(Th
1ea00 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
1ea10 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72  to the.** author
1ea20 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73  izer callback is
1ea30 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1ea40 20 64 61 74 61 62 61 73 65 20 28 22 6d 61 69 6e   database ("main
1ea50 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20 65 74  ", "temp",.** et
1ea60 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61 62 6c  c.) if applicabl
1ea70 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68 20 70  e.)^  ^The 6th p
1ea80 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1ea90 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1eaa0 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20 6e 61  ack.** is the na
1eab0 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65 72 2d  me of the inner-
1eac0 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f 72 20  most trigger or 
1ead0 76 69 65 77 20 74 68 61 74 20 69 73 20 72 65 73  view that is res
1eae0 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a 2a 20  ponsible for.** 
1eaf0 74 68 65 20 61 63 63 65 73 73 20 61 74 74 65 6d  the access attem
1eb00 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20 74 68  pt or NULL if th
1eb10 69 73 20 61 63 63 65 73 73 20 61 74 74 65 6d 70  is access attemp
1eb20 74 20 69 73 20 64 69 72 65 63 74 6c 79 20 66 72  t is directly fr
1eb30 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65 6c 20  om.** top-level 
1eb40 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a  SQL code..*/./**
1eb50 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eb60 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1eb70 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a  ********* 3rd **
1eb80 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a  ********** 4th *
1eb90 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66  **********/.#def
1eba0 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1ebb0 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20 20  E_INDEX         
1ebc0 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   1   /* Index Na
1ebd0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1ebe0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1ebf0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1ec00 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20  _TABLE          
1ec10 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  2   /* Table Nam
1ec20 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1ec30 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1ec40 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1ec50 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20 33  TEMP_INDEX     3
1ec60 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1ec70 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65        Table Name
1ec80 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ec90 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1eca0 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 34 20  EMP_TABLE     4 
1ecb0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1ecc0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1ecd0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1ece0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45  SQLITE_CREATE_TE
1ecf0 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35 20 20  MP_TRIGGER   5  
1ed00 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1ed10 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1ed20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ed30 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d  QLITE_CREATE_TEM
1ed40 50 5f 56 49 45 57 20 20 20 20 20 20 36 20 20 20  P_VIEW      6   
1ed50 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1ed60 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ed70 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ed80 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52 49 47  LITE_CREATE_TRIG
1ed90 47 45 52 20 20 20 20 20 20 20 20 37 20 20 20 2f  GER        7   /
1eda0 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20  * Trigger Name  
1edb0 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1edc0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1edd0 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45 57 20  ITE_CREATE_VIEW 
1ede0 20 20 20 20 20 20 20 20 20 20 38 20 20 20 2f 2a            8   /*
1edf0 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20   View Name      
1ee00 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1ee10 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ee20 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20  TE_DELETE       
1ee30 20 20 20 20 20 20 20 20 20 39 20 20 20 2f 2a 20           9   /* 
1ee40 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1ee50 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ee60 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ee70 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20 20 20  E_DROP_INDEX    
1ee80 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 49         10   /* I
1ee90 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1eea0 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1eeb0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1eec0 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20 20 20  _DROP_TABLE     
1eed0 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20 54 61        11   /* Ta
1eee0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1eef0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1ef00 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1ef10 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45 58 20  DROP_TEMP_INDEX 
1ef20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49 6e 64       12   /* Ind
1ef30 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62  ex Name      Tab
1ef40 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1ef50 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1ef60 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20  ROP_TEMP_TABLE  
1ef70 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61 62 6c      13   /* Tabl
1ef80 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1ef90 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1efa0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1efb0 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45 52 20  OP_TEMP_TRIGGER 
1efc0 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69 67 67     14   /* Trigg
1efd0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1efe0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1eff0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1f000 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20 20 20  P_TEMP_VIEW     
1f010 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77 20 4e    15   /* View N
1f020 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1f030 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1f040 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1f050 5f 54 52 49 47 47 45 52 20 20 20 20 20 20 20 20  _TRIGGER        
1f060 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67 65 72   16   /* Trigger
1f070 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e   Name    Table N
1f080 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1f090 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1f0a0 56 49 45 57 20 20 20 20 20 20 20 20 20 20 20 20  VIEW            
1f0b0 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d  17   /* View Nam
1f0c0 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  e       NULL    
1f0d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1f0e0 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45 52 54  ne SQLITE_INSERT
1f0f0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31                 1
1f100 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  8   /* Table Nam
1f110 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1f120 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1f130 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d 41 20  e SQLITE_PRAGMA 
1f140 20 20 20 20 20 20 20 20 20 20 20 20 20 20 31 39                19
1f150 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e 61 6d     /* Pragma Nam
1f160 65 20 20 20 20 20 31 73 74 20 61 72 67 20 6f 72  e     1st arg or
1f170 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69 6e 65   NULL */.#define
1f180 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20 20 20   SQLITE_READ    
1f190 20 20 20 20 20 20 20 20 20 20 20 20 20 32 30 20               20 
1f1a0 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1f1b0 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65       Column Name
1f1c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1f1d0 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20 20 20  SQLITE_SELECT   
1f1e0 20 20 20 20 20 20 20 20 20 20 20 20 32 31 20 20              21  
1f1f0 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20   /* NULL        
1f200 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1f210 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1f220 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54 49 4f  QLITE_TRANSACTIO
1f230 4e 20 20 20 20 20 20 20 20 20 20 32 32 20 20 20  N          22   
1f240 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20  /* Operation    
1f250 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1f260 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1f270 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20 20 20  LITE_UPDATE     
1f280 20 20 20 20 20 20 20 20 20 20 32 33 20 20 20 2f            23   /
1f290 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1f2a0 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20    Column Name   
1f2b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1f2c0 49 54 45 5f 41 54 54 41 43 48 20 20 20 20 20 20  ITE_ATTACH      
1f2d0 20 20 20 20 20 20 20 20 20 32 34 20 20 20 2f 2a           24   /*
1f2e0 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20 20 20   Filename       
1f2f0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1f300 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1f310 54 45 5f 44 45 54 41 43 48 20 20 20 20 20 20 20  TE_DETACH       
1f320 20 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20          25   /* 
1f330 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20  Database Name   
1f340 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1f350 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1f360 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20 20 20  E_ALTER_TABLE   
1f370 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 44         26   /* D
1f380 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20 20 54  atabase Name   T
1f390 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1f3a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1f3b0 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20 20 20  _REINDEX        
1f3c0 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20 49 6e        27   /* In
1f3d0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  dex Name      NU
1f3e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1f3f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1f400 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20 20 20  ANALYZE         
1f410 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54 61 62       28   /* Tab
1f420 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1f430 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1f440 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1f450 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20 20 20  REATE_VTABLE    
1f460 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61 62 6c      29   /* Tabl
1f470 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75  e Name      Modu
1f480 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23  le Name     */.#
1f490 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1f4a0 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20  OP_VTABLE       
1f4b0 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62 6c 65     30   /* Table
1f4c0 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c   Name      Modul
1f4d0 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64  e Name     */.#d
1f4e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 55 4e  efine SQLITE_FUN
1f4f0 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20 20 20  CTION           
1f500 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c 20 20    31   /* NULL  
1f510 20 20 20 20 20 20 20 20 20 20 46 75 6e 63 74 69            Functi
1f520 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23 64 65  on Name   */.#de
1f530 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41 56 45  fine SQLITE_SAVE
1f540 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20 20 20  POINT           
1f550 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61 74 69   32   /* Operati
1f560 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70 6f 69  on       Savepoi
1f570 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64 65 66  nt Name  */.#def
1f580 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50 59 20  ine SQLITE_COPY 
1f590 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
1f5a0 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65   0   /* No longe
1f5b0 72 20 75 73 65 64 20 2a 2f 0a 23 64 65 66 69 6e  r used */.#defin
1f5c0 65 20 53 51 4c 49 54 45 5f 52 45 43 55 52 53 49  e SQLITE_RECURSI
1f5d0 56 45 20 20 20 20 20 20 20 20 20 20 20 20 33 33  VE            33
1f5e0 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1f5f0 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1f600 20 20 20 20 20 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20        */../*.** 
1f610 43 41 50 49 33 52 45 46 3a 20 54 72 61 63 69 6e  CAPI3REF: Tracin
1f620 67 20 41 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20  g And Profiling 
1f630 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  Functions.**.** 
1f640 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
1f650 65 67 69 73 74 65 72 20 63 61 6c 6c 62 61 63 6b  egister callback
1f660 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
1f670 63 61 6e 20 62 65 20 75 73 65 64 20 66 6f 72 0a  can be used for.
1f680 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e 64 20 70  ** tracing and p
1f690 72 6f 66 69 6c 69 6e 67 20 74 68 65 20 65 78 65  rofiling the exe
1f6a0 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74  cution of SQL st
1f6b0 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
1f6c0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1f6d0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1f6e0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 74 72 61  d by sqlite3_tra
1f6f0 63 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 20  ce() is invoked 
1f700 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73 20 74 69  at.** various ti
1f710 6d 65 73 20 77 68 65 6e 20 61 6e 20 53 51 4c 20  mes when an SQL 
1f720 73 74 61 74 65 6d 65 6e 74 20 69 73 20 62 65 69  statement is bei
1f730 6e 67 20 72 75 6e 20 62 79 20 5b 73 71 6c 69 74  ng run by [sqlit
1f740 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e  e3_step()]..** ^
1f750 54 68 65 20 73 71 6c 69 74 65 33 5f 74 72 61 63  The sqlite3_trac
1f760 65 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  e() callback is 
1f770 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 55  invoked with a U
1f780 54 46 2d 38 20 72 65 6e 64 65 72 69 6e 67 20 6f  TF-8 rendering o
1f790 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61  f the.** SQL sta
1f7a0 74 65 6d 65 6e 74 20 74 65 78 74 20 61 73 20 74  tement text as t
1f7b0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 66 69 72  he statement fir
1f7c0 73 74 20 62 65 67 69 6e 73 20 65 78 65 63 75 74  st begins execut
1f7d0 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69  ing..** ^(Additi
1f7e0 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f 74 72 61  onal sqlite3_tra
1f7f0 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d  ce() callbacks m
1f800 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73  ight occur.** as
1f810 20 65 61 63 68 20 74 72 69 67 67 65 72 65 64 20   each triggered 
1f820 73 75 62 70 72 6f 67 72 61 6d 20 69 73 20 65 6e  subprogram is en
1f830 74 65 72 65 64 2e 20 20 54 68 65 20 63 61 6c 6c  tered.  The call
1f840 62 61 63 6b 73 20 66 6f 72 20 74 72 69 67 67 65  backs for trigge
1f850 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20  rs.** contain a 
1f860 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e  UTF-8 SQL commen
1f870 74 20 74 68 61 74 20 69 64 65 6e 74 69 66 69 65  t that identifie
1f880 73 20 74 68 65 20 74 72 69 67 67 65 72 2e 29 5e  s the trigger.)^
1f890 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
1f8a0 54 45 5f 54 52 41 43 45 5f 53 49 5a 45 5f 4c 49  TE_TRACE_SIZE_LI
1f8b0 4d 49 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  MIT] compile-tim
1f8c0 65 20 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20  e option can be 
1f8d0 75 73 65 64 20 74 6f 20 6c 69 6d 69 74 0a 2a 2a  used to limit.**
1f8e0 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 5b   the length of [
1f8f0 62 6f 75 6e 64 20 70 61 72 61 6d 65 74 65 72 5d  bound parameter]
1f900 20 65 78 70 61 6e 73 69 6f 6e 20 69 6e 20 74 68   expansion in th
1f910 65 20 6f 75 74 70 75 74 20 6f 66 20 73 71 6c 69  e output of sqli
1f920 74 65 33 5f 74 72 61 63 65 28 29 2e 0a 2a 2a 0a  te3_trace()..**.
1f930 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1f940 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1f950 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1f960 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e 76  profile() is inv
1f970 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68 20  oked.** as each 
1f980 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66 69  SQL statement fi
1f990 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70 72  nishes.  ^The pr
1f9a0 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63  ofile callback c
1f9b0 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f  ontains.** the o
1f9c0 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e  riginal statemen
1f9d0 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65 73  t text and an es
1f9e0 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63  timate of wall-c
1f9f0 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20  lock time.** of 
1fa00 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73 74  how long that st
1fa10 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20  atement took to 
1fa20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  run.  ^The profi
1fa30 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74  le callback.** t
1fa40 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73 20  ime is in units 
1fa50 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20  of nanoseconds, 
1fa60 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72 72  however the curr
1fa70 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ent implementati
1fa80 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61  on.** is only ca
1fa90 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65  pable of millise
1faa0 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20  cond resolution 
1fab0 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73 74  so the six least
1fac0 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20   significant.** 
1fad0 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74 69  digits in the ti
1fae0 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65  me are meaningle
1faf0 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  ss.  Future vers
1fb00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a  ions of SQLite.*
1fb10 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65 20  * might provide 
1fb20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74 69  greater resoluti
1fb30 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c  on on the profil
1fb40 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68  er callback.  Th
1fb50 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f  e.** sqlite3_pro
1fb60 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e 20  file() function 
1fb70 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65 78  is considered ex
1fb80 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69  perimental and i
1fb90 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f 20  s.** subject to 
1fba0 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72 65  change in future
1fbb0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
1fbc0 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ite..*/.void *sq
1fbd0 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c 69  lite3_trace(sqli
1fbe0 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61  te3*, void(*xTra
1fbf0 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  ce)(void*,const 
1fc00 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  char*), void*);.
1fc10 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45 4e  SQLITE_EXPERIMEN
1fc20 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  TAL void *sqlite
1fc30 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74 65  3_profile(sqlite
1fc40 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50 72  3*,.   void(*xPr
1fc50 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e  ofile)(void*,con
1fc60 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65 33  st char*,sqlite3
1fc70 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29  _uint64), void*)
1fc80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
1fc90 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65 73  F: Query Progres
1fca0 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  s Callbacks.**.*
1fcb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 70  * ^The sqlite3_p
1fcc0 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28  rogress_handler(
1fcd0 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66 61  D,N,X,P) interfa
1fce0 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63 61  ce causes the ca
1fcf0 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69  llback.** functi
1fd00 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b  on X to be invok
1fd10 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79 20  ed periodically 
1fd20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e  during long runn
1fd30 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  ing calls to.** 
1fd40 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d  [sqlite3_exec()]
1fd50 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  , [sqlite3_step(
1fd60 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
1fd70 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72  get_table()] for
1fd80 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
1fd90 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65  nection D.  An e
1fda0 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20 74  xample use for t
1fdb0 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  his.** interface
1fdc0 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47 55   is to keep a GU
1fdd0 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e 67  I updated during
1fde0 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e 0a   a large query..
1fdf0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d  **.** ^The param
1fe00 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65 64  eter P is passed
1fe10 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
1fe20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74  only parameter t
1fe30 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61  o the .** callba
1fe40 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20  ck function X.  
1fe50 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20 4e  ^The parameter N
1fe60 20 69 73 20 74 68 65 20 61 70 70 72 6f 78 69 6d   is the approxim
1fe70 61 74 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a 2a  ate number of .*
1fe80 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68 69  * [virtual machi
1fe90 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 5d  ne instructions]
1fea0 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75 61   that are evalua
1feb0 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63 63  ted between succ
1fec0 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63 61  essive.** invoca
1fed0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61 6c  tions of the cal
1fee0 6c 62 61 63 6b 20 58 2e 20 20 5e 49 66 20 4e 20  lback X.  ^If N 
1fef0 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f 6e 65  is less than one
1ff00 20 74 68 65 6e 20 74 68 65 20 70 72 6f 67 72 65   then the progre
1ff10 73 73 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 69 73  ss.** handler is
1ff20 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
1ff30 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20   ^Only a single 
1ff40 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1ff50 20 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20   may be defined 
1ff60 61 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a  at one time per.
1ff70 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
1ff80 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e  nection]; settin
1ff90 67 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73  g a new progress
1ffa0 20 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73   handler cancels
1ffb0 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e   the.** old one.
1ffc0 20 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d    ^Setting param
1ffd0 65 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64  eter X to NULL d
1ffe0 69 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67  isables the prog
1fff0 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
20000 20 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68   ^The progress h
20010 61 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64  andler is also d
20020 69 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69  isabled by setti
20030 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20  ng N to a value 
20040 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a  less.** than 1..
20050 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72  **.** ^If the pr
20060 6f 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20  ogress callback 
20070 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f  returns non-zero
20080 2c 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20  , the operation 
20090 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65  is.** interrupte
200a0 64 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65  d.  This feature
200b0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
200c0 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22  implement a.** "
200d0 43 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f  Cancel" button o
200e0 6e 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73  n a GUI progress
200f0 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a   dialog box..**.
20100 2a 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20  ** The progress 
20110 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b  handler callback
20120 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79   must not do any
20130 74 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20  thing that will 
20140 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61  modify.** the da
20150 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
20160 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74  n that invoked t
20170 68 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  he progress hand
20180 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ler..** Note tha
20190 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  t [sqlite3_prepa
201a0 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71  re_v2()] and [sq
201b0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f  lite3_step()] bo
201c0 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a  th modify their.
201d0 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  ** database conn
201e0 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20  ections for the 
201f0 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69  meaning of "modi
20200 66 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61  fy" in this para
20210 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69  graph..**.*/.voi
20220 64 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65  d sqlite3_progre
20230 73 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74  ss_handler(sqlit
20240 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29  e3*, int, int(*)
20250 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
20260 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
20270 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20  : Opening A New 
20280 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
20290 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ion.**.** ^These
202a0 20 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61   routines open a
202b0 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73  n SQLite databas
202c0 65 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66  e file as specif
202d0 69 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66  ied by the .** f
202e0 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74  ilename argument
202f0 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20  . ^The filename 
20300 61 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65  argument is inte
20310 72 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38  rpreted as UTF-8
20320 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
20330 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
20340 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64  e3_open_v2() and
20350 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68   as UTF-16 in th
20360 65 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a  e native byte.**
20370 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
20380 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41  e3_open16(). ^(A
20390 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
203a0 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73  ction] handle is
203b0 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75   usually.** retu
203c0 72 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65  rned in *ppDb, e
203d0 76 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20  ven if an error 
203e0 6f 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c  occurs.  The onl
203f0 79 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74  y exception is t
20400 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65  hat.** if SQLite
20410 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c   is unable to al
20420 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f  locate memory to
20430 20 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74   hold the [sqlit
20440 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61  e3] object,.** a
20450 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72   NULL will be wr
20460 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62  itten into *ppDb
20470 20 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f   instead of a po
20480 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
20490 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74  lite3].** object
204a0 2e 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74  .)^ ^(If the dat
204b0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
204c0 28 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29  (and/or created)
204d0 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74   successfully, t
204e0 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  hen.** [SQLITE_O
204f0 4b 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  K] is returned. 
20500 20 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65   Otherwise an [e
20510 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
20520 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a  turned.)^ ^The.*
20530 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  * [sqlite3_errms
20540 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  g()] or [sqlite3
20550 5f 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75  _errmsg16()] rou
20560 74 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65  tines can be use
20570 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61  d to obtain.** a
20580 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61  n English langua
20590 67 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f  ge description o
205a0 66 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c  f the error foll
205b0 6f 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20  owing a failure 
205c0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
205d0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
205e0 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20  routines..**.** 
205f0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63  ^The default enc
20600 6f 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61  oding for the da
20610 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55  tabase will be U
20620 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74  TF-8 if.** sqlit
20630 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
20640 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
20650 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20  s called and.** 
20660 55 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61  UTF-16 in the na
20670 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20  tive byte order 
20680 69 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  if sqlite3_open1
20690 36 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  6() is used..**.
206a0 2a 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f  ** Whether or no
206b0 74 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72  t an error occur
206c0 73 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65  s when it is ope
206d0 6e 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a  ned, resources.*
206e0 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  * associated wit
206f0 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
20700 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64  connection] hand
20710 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c  le should be rel
20720 65 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73  eased by.** pass
20730 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74  ing it to [sqlit
20740 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e  e3_close()] when
20750 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72   it is no longer
20760 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
20770 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65   The sqlite3_ope
20780 6e 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65  n_v2() interface
20790 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69   works like sqli
207a0 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78  te3_open().** ex
207b0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63  cept that it acc
207c0 65 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f  epts two additio
207d0 6e 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66  nal parameters f
207e0 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f  or additional co
207f0 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68  ntrol.** over th
20800 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
20810 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68  onnection.  ^(Th
20820 65 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  e flags paramete
20830 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  r to.** sqlite3_
20840 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61  open_v2() can ta
20850 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65  ke one of.** the
20860 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65   following three
20870 20 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61   values, optiona
20880 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74  lly combined wit
20890 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54  h the .** [SQLIT
208a0 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c  E_OPEN_NOMUTEX],
208b0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55   [SQLITE_OPEN_FU
208c0 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  LLMUTEX], [SQLIT
208d0 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43  E_OPEN_SHAREDCAC
208e0 48 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  HE],.** [SQLITE_
208f0 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
20900 45 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49  E], and/or [SQLI
20910 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61  TE_OPEN_URI] fla
20920 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
20930 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
20940 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
20950 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
20960 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
20970 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
20980 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
20990 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
209a0 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
209b0 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
209c0 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
209d0 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
209e0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
209f0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
20a00 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
20a10 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
20a20 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
20a30 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
20a40 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
20a50 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
20a60 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
20a70 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
20a80 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
20a90 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
20aa0 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
20ab0 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
20ac0 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
20ad0 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
20ae0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
20af0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
20b00 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
20b10 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
20b20 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
20b30 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
20b40 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
20b50 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
20b60 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
20b70 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
20b80 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
20b90 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
20ba0 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
20bb0 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
20bc0 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
20bd0 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
20be0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
20bf0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
20c00 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
20c10 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
20c20 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
20c30 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
20c40 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69  shown above opti
20c50 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
20c60 77 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53  with other.** [S
20c70 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f  QLITE_OPEN_READO
20c80 4e 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45  NLY | SQLITE_OPE
20c90 4e 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65  N_* bits].** the
20ca0 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69  n the behavior i
20cb0 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  s undefined..**.
20cc0 2a 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  ** ^If the [SQLI
20cd0 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d  TE_OPEN_NOMUTEX]
20ce0 20 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68   flag is set, th
20cf0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20d00 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70  connection.** op
20d10 65 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69  ens in the multi
20d20 2d 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69  -thread [threadi
20d30 6e 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67  ng mode] as long
20d40 20 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74   as the single-t
20d50 68 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61  hread.** mode ha
20d60 73 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61  s not been set a
20d70 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  t compile-time o
20d80 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e  r start-time.  ^
20d90 49 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  If the.** [SQLIT
20da0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
20db0 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68  ] flag is set th
20dc0 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
20dd0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73  connection opens
20de0 0a 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61  .** in the seria
20df0 6c 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67  lized [threading
20e00 20 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69   mode] unless si
20e10 6e 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a  ngle-thread was.
20e20 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65  ** previously se
20e30 6c 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c  lected at compil
20e40 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d  e-time or start-
20e50 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53  time..** ^The [S
20e60 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45  QLITE_OPEN_SHARE
20e70 44 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75  DCACHE] flag cau
20e80 73 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ses the database
20e90 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62   connection to b
20ea0 65 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f  e.** eligible to
20eb0 20 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63   use [shared cac
20ec0 68 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64  he mode], regard
20ed0 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
20ee0 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a  or not shared.**
20ef0 20 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65   cache is enable
20f00 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
20f10 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
20f20 61 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a  ache()].  ^The.*
20f30 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  * [SQLITE_OPEN_P
20f40 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
20f50 67 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74  g causes the dat
20f60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
20f70 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69   to not.** parti
20f80 63 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65  cipate in [share
20f90 64 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76  d cache mode] ev
20fa0 65 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62  en if it is enab
20fb0 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
20fc0 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
20fd0 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e   to sqlite3_open
20fe0 5f 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d  _v2() is the nam
20ff0 65 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c  e of the.** [sql
21000 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
21010 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68   that defines th
21020 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
21030 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  em interface tha
21040 74 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74  t.** the new dat
21050 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
21060 20 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49   should use.  ^I
21070 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
21080 61 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e  ameter is.** a N
21090 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e  ULL pointer then
210a0 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71   the default [sq
210b0 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63  lite3_vfs] objec
210c0 74 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a  t is used..**.**
210d0 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d   ^If the filenam
210e0 65 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c  e is ":memory:",
210f0 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c   then a private,
21100 20 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65   temporary in-me
21110 6d 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a  mory database.**
21120 20 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20   is created for 
21130 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20  the connection. 
21140 20 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79   ^This in-memory
21150 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76   database will v
21160 61 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68  anish when.** th
21170 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
21180 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e  ction is closed.
21190 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
211a0 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68  s of SQLite migh
211b0 74 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66  t.** make use of
211c0 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63   additional spec
211d0 69 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68  ial filenames th
211e0 61 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68  at begin with th
211f0 65 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e  e ":" character.
21200 0a 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d  .** It is recomm
21210 65 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20  ended that when 
21220 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e  a database filen
21230 61 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65  ame actually doe
21240 73 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20  s begin with.** 
21250 61 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20  a ":" character 
21260 79 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69  you should prefi
21270 78 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77  x the filename w
21280 69 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73  ith a pathname s
21290 75 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74  uch as.** "./" t
212a0 6f 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74  o avoid ambiguit
212b0 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  y..**.** ^If the
212c0 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20   filename is an 
212d0 65 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68  empty string, th
212e0 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65  en a private, te
212f0 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69  mporary.** on-di
21300 73 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c  sk database will
21310 20 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54   be created.  ^T
21320 68 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61  his private data
21330 62 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  base will be.** 
21340 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65  automatically de
21350 6c 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73  leted as soon as
21360 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   the database co
21370 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73  nnection is clos
21380 65 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20  ed..**.** [[URI 
21390 66 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c  filenames in sql
213a0 69 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68  ite3_open()]] <h
213b0 33 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c  3>URI Filenames<
213c0 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b  /h3>.**.** ^If [
213d0 55 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e  URI filename] in
213e0 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20  terpretation is 
213f0 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65  enabled, and the
21400 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65   filename argume
21410 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74  nt.** begins wit
21420 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20  h "file:", then 
21430 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20  the filename is 
21440 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
21450 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69   URI. ^URI.** fi
21460 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74  lename interpret
21470 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
21480 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f   if the [SQLITE_
21490 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69  OPEN_URI] flag i
214a0 73 0a 2a 2a 20 73 65 74 20 69 6e 20 74 68 65 20  s.** set in the 
214b0 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20  fourth argument 
214c0 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
214d0 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74 20 68  v2(), or if it h
214e0 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61 62 6c  as.** been enabl
214f0 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73 69 6e  ed globally usin
21500 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 43 4f  g the [SQLITE_CO
21510 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69 6f 6e  NFIG_URI] option
21520 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 73 71   with the.** [sq
21530 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
21540 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74 68 65  method or by the
21550 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55 52 49   [SQLITE_USE_URI
21560 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f  ] compile-time o
21570 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f 66 20  ption..** As of 
21580 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33  SQLite version 3
21590 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65 6e 61  .7.7, URI filena
215a0 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  me interpretatio
215b0 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66 66 0a  n is turned off.
215c0 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c 20 62  ** by default, b
215d0 75 74 20 66 75 74 75 72 65 20 72 65 6c 65 61 73  ut future releas
215e0 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  es of SQLite mig
215f0 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20 66 69  ht enable URI fi
21600 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65 72 70  lename.** interp
21610 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66 61  retation by defa
21620 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49 20  ult.  See "[URI 
21630 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72 20  filenames]" for 
21640 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e  additional.** in
21650 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
21660 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20 61   URI filenames a
21670 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72 64  re parsed accord
21680 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36 2e  ing to RFC 3986.
21690 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f 6e   ^If the URI con
216a0 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74 68  tains an.** auth
216b0 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20 6d  ority, then it m
216c0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61 6e  ust be either an
216d0 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f 72   empty string or
216e0 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a 20   the string .** 
216f0 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49 66  "localhost". ^If
21700 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20 69   the authority i
21710 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20 73  s not an empty s
21720 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c 68  tring or "localh
21730 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72 72  ost", an .** err
21740 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20 74  or is returned t
21750 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e 54  o the caller. ^T
21760 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d 70  he fragment comp
21770 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c 20  onent of a URI, 
21780 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c 20  if .** present, 
21790 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a  is ignored..**.*
217a0 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74  * ^SQLite uses t
217b0 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65 6e  he path componen
217c0 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73 20  t of the URI as 
217d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
217e0 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68 69  disk file.** whi
217f0 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20  ch contains the 
21800 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74 68  database. ^If th
21810 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77 69  e path begins wi
21820 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63 74  th a '/' charact
21830 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74 20  er, .** then it 
21840 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20 61  is interpreted a
21850 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61  s an absolute pa
21860 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68  th. ^If the path
21870 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e 20   does not begin 
21880 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20 28  .** with a '/' (
21890 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68 65  meaning that the
218a0 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74 69   authority secti
218b0 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72  on is omitted fr
218c0 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20 74  om the URI).** t
218d0 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73 20  hen the path is 
218e0 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61  interpreted as a
218f0 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e 20   relative path. 
21900 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73 2c  .** ^On windows,
21910 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70 6f   the first compo
21920 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f 6c  nent of an absol
21930 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73 20  ute path .** is 
21940 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69 63  a drive specific
21950 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a 22  ation (e.g. "C:"
21960 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65 20  )..**.** [[core 
21970 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d 65  URI query parame
21980 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71 75  ters]].** The qu
21990 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  ery component of
219a0 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74 61   a URI may conta
219b0 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74 68  in parameters th
219c0 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  at are interpret
219d0 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79 20  ed.** either by 
219e0 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20 6f  SQLite itself, o
219f0 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63 75  r by a [VFS | cu
21a00 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
21a10 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
21a20 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
21a30 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
21a40 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
21a50 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
21a60 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
21a70 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
21a80 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
21a90 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
21aa0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
21ab0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
21ac0 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
21ad0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
21ae0 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
21af0 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
21b00 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
21b10 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
21b20 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
21b30 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
21b40 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
21b50 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
21b60 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
21b70 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
21b80 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
21b90 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
21ba0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
21bb0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
21bc0 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
21bd0 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
21be0 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
21bf0 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
21c00 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
21c10 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
21c20 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
21c30 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
21c40 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
21c50 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
21c60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
21c70 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
21c80 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
21c90 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
21ca0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
21cb0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
21cc0 77 22 2c 0a 2a 2a 20 20 20 20 20 22 72 77 63 22  w",.**     "rwc"
21cd0 2c 20 6f 72 20 22 6d 65 6d 6f 72 79 22 2e 20 41  , or "memory". A
21ce0 74 74 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74  ttempting to set
21cf0 20 69 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72   it to any other
21d00 20 76 61 6c 75 65 20 69 73 0a 2a 2a 20 20 20 20   value is.**    
21d10 20 61 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a   an error)^. .**
21d20 20 20 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73       ^If "ro" is
21d30 20 73 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e   specified, then
21d40 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73   the database is
21d50 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64   opened for read
21d60 2d 6f 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63  -only .**     ac
21d70 63 65 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66  cess, just as if
21d80 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
21d90 4e 5f 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67  N_READONLY] flag
21da0 20 68 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e   had been set in
21db0 20 74 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69   the .**     thi
21dc0 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  rd argument to s
21dd0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
21de0 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20 6f  . ^If the mode o
21df0 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f 20  ption is set to 
21e00 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74 68  .**     "rw", th
21e10 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
21e20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65  is opened for re
21e30 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e 6f  ad-write (but no
21e40 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20 20  t create) .**   
21e50 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66 20    access, as if 
21e60 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
21e70 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20 53  WRITE (but not S
21e80 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54  QLITE_OPEN_CREAT
21e90 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20 62  E) had .**     b
21ea0 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65 20  een set. ^Value 
21eb0 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61 6c  "rwc" is equival
21ec0 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20 62  ent to setting b
21ed0 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c 49  oth .**     SQLI
21ee0 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
21ef0 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50 45  E and SQLITE_OPE
21f00 4e 5f 43 52 45 41 54 45 2e 20 20 5e 49 66 20 74  N_CREATE.  ^If t
21f10 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20 69  he mode option i
21f20 73 0a 2a 2a 20 20 20 20 20 73 65 74 20 74 6f 20  s.**     set to 
21f30 22 6d 65 6d 6f 72 79 22 20 74 68 65 6e 20 61 20  "memory" then a 
21f40 70 75 72 65 20 5b 69 6e 2d 6d 65 6d 6f 72 79 20  pure [in-memory 
21f50 64 61 74 61 62 61 73 65 5d 20 74 68 61 74 20 6e  database] that n
21f60 65 76 65 72 20 72 65 61 64 73 0a 2a 2a 20 20 20  ever reads.**   
21f70 20 20 6f 72 20 77 72 69 74 65 73 20 66 72 6f 6d    or writes from
21f80 20 64 69 73 6b 20 69 73 20 75 73 65 64 2e 20 5e   disk is used. ^
21f90 49 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 74  It is an error t
21fa0 6f 20 73 70 65 63 69 66 79 20 61 20 76 61 6c 75  o specify a valu
21fb0 65 20 66 6f 72 0a 2a 2a 20 20 20 20 20 74 68 65  e for.**     the
21fc0 20 6d 6f 64 65 20 70 61 72 61 6d 65 74 65 72 20   mode parameter 
21fd0 74 68 61 74 20 69 73 20 6c 65 73 73 20 72 65 73  that is less res
21fe0 74 72 69 63 74 69 76 65 20 74 68 61 6e 20 74 68  trictive than th
21ff0 61 74 20 73 70 65 63 69 66 69 65 64 20 62 79 0a  at specified by.
22000 2a 2a 20 20 20 20 20 74 68 65 20 66 6c 61 67 73  **     the flags
22010 20 70 61 73 73 65 64 20 69 6e 20 74 68 65 20 74   passed in the t
22020 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
22030 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  o sqlite3_open_v
22040 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69  2()..**.**   <li
22050 3e 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20  > <b>cache</b>: 
22060 5e 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d  ^The cache param
22070 65 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20  eter may be set 
22080 74 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65  to either "share
22090 64 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72  d" or.**     "pr
220a0 69 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67  ivate". ^Setting
220b0 20 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20   it to "shared" 
220c0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
220d0 20 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20   setting the.** 
220e0 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f      SQLITE_OPEN_
220f0 53 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20  SHAREDCACHE bit 
22100 69 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67  in the flags arg
22110 75 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a  ument passed to.
22120 2a 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f  **     sqlite3_o
22130 70 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69  pen_v2(). ^Setti
22140 6e 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72  ng the cache par
22150 61 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61  ameter to "priva
22160 74 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65  te" is .**     e
22170 71 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74  quivalent to set
22180 74 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f  ting the SQLITE_
22190 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
221a0 45 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49  E bit..**     ^I
221b0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  f sqlite3_open_v
221c0 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20  2() is used and 
221d0 74 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61  the "cache" para
221e0 6d 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74  meter is present
221f0 20 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49   in.**     a URI
22200 20 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76   filename, its v
22210 61 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61  alue overrides a
22220 6e 79 20 62 65 68 61 76 69 6f 72 20 72 65 71 75  ny behavior requ
22230 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
22240 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
22250 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
22260 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
22270 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
22280 2e 0a 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62  ..**.**  <li> <b
22290 3e 70 73 6f 77 3c 2f 62 3e 3a 20 5e 54 68 65 20  >psow</b>: ^The 
222a0 70 73 6f 77 20 70 61 72 61 6d 65 74 65 72 20 6d  psow parameter m
222b0 61 79 20 62 65 20 22 74 72 75 65 22 20 28 6f 72  ay be "true" (or
222c0 20 22 6f 6e 22 20 6f 72 20 22 79 65 73 22 20 6f   "on" or "yes" o
222d0 72 0a 2a 2a 20 20 20 20 20 22 31 22 29 20 6f 72  r.**     "1") or
222e0 20 22 66 61 6c 73 65 22 20 28 6f 72 20 22 6f 66   "false" (or "of
222f0 66 22 20 6f 72 20 22 6e 6f 22 20 6f 72 20 22 30  f" or "no" or "0
22300 22 29 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ") to indicate t
22310 68 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 5b  hat the.**     [
22320 70 6f 77 65 72 73 61 66 65 20 6f 76 65 72 77 72  powersafe overwr
22330 69 74 65 5d 20 70 72 6f 70 65 72 74 79 20 64 6f  ite] property do
22340 65 73 20 6f 72 20 64 6f 65 73 20 6e 6f 74 20 61  es or does not a
22350 70 70 6c 79 20 74 6f 20 74 68 65 0a 2a 2a 20 20  pply to the.**  
22360 20 20 20 73 74 6f 72 61 67 65 20 6d 65 64 69 61     storage media
22370 20 6f 6e 20 77 68 69 63 68 20 74 68 65 20 64 61   on which the da
22380 74 61 62 61 73 65 20 66 69 6c 65 20 72 65 73 69  tabase file resi
22390 64 65 73 2e 20 20 5e 54 68 65 20 70 73 6f 77 20  des.  ^The psow 
223a0 71 75 65 72 79 0a 2a 2a 20 20 20 20 20 70 61 72  query.**     par
223b0 61 6d 65 74 65 72 20 6f 6e 6c 79 20 77 6f 72 6b  ameter only work
223c0 73 20 66 6f 72 20 74 68 65 20 62 75 69 6c 74 2d  s for the built-
223d0 69 6e 20 75 6e 69 78 20 61 6e 64 20 57 69 6e 64  in unix and Wind
223e0 6f 77 73 20 56 46 53 65 73 2e 0a 2a 2a 0a 2a 2a  ows VFSes..**.**
223f0 20 20 3c 6c 69 3e 20 3c 62 3e 6e 6f 6c 6f 63 6b    <li> <b>nolock
22400 3c 2f 62 3e 3a 20 5e 54 68 65 20 6e 6f 6c 6f 63  </b>: ^The noloc
22410 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  k parameter is a
22420 20 62 6f 6f 6c 65 61 6e 20 71 75 65 72 79 20 70   boolean query p
22430 61 72 61 6d 65 74 65 72 0a 2a 2a 20 20 20 20 20  arameter.**     
22440 77 68 69 63 68 20 69 66 20 73 65 74 20 64 69 73  which if set dis
22450 61 62 6c 65 73 20 66 69 6c 65 20 6c 6f 63 6b 69  ables file locki
22460 6e 67 20 69 6e 20 72 6f 6c 6c 62 61 63 6b 20 6a  ng in rollback j
22470 6f 75 72 6e 61 6c 20 6d 6f 64 65 73 2e 20 20 54  ournal modes.  T
22480 68 69 73 0a 2a 2a 20 20 20 20 20 69 73 20 75 73  his.**     is us
22490 65 66 75 6c 20 66 6f 72 20 61 63 63 65 73 73 69  eful for accessi
224a0 6e 67 20 61 20 64 61 74 61 62 61 73 65 20 6f 6e  ng a database on
224b0 20 61 20 66 69 6c 65 73 79 73 74 65 6d 20 74 68   a filesystem th
224c0 61 74 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 20  at does not.**  
224d0 20 20 20 73 75 70 70 6f 72 74 20 6c 6f 63 6b 69     support locki
224e0 6e 67 2e 20 20 43 61 75 74 69 6f 6e 3a 20 20 44  ng.  Caution:  D
224f0 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69  atabase corrupti
22500 6f 6e 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  on might result 
22510 69 66 20 74 77 6f 0a 2a 2a 20 20 20 20 20 6f 72  if two.**     or
22520 20 6d 6f 72 65 20 70 72 6f 63 65 73 73 65 73 20   more processes 
22530 77 72 69 74 65 20 74 6f 20 74 68 65 20 73 61 6d  write to the sam
22540 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  e database and a
22550 6e 79 20 6f 6e 65 20 6f 66 20 74 68 6f 73 65 0a  ny one of those.
22560 2a 2a 20 20 20 20 20 70 72 6f 63 65 73 73 65 73  **     processes
22570 20 75 73 65 73 20 6e 6f 6c 6f 63 6b 3d 31 2e 0a   uses nolock=1..
22580 2a 2a 0a 2a 2a 20 20 3c 6c 69 3e 20 3c 62 3e 69  **.**  <li> <b>i
22590 6d 6d 75 74 61 62 6c 65 3c 2f 62 3e 3a 20 5e 54  mmutable</b>: ^T
225a0 68 65 20 69 6d 6d 75 74 61 62 6c 65 20 70 61 72  he immutable par
225b0 61 6d 65 74 65 72 20 69 73 20 61 20 62 6f 6f 6c  ameter is a bool
225c0 65 61 6e 20 71 75 65 72 79 0a 2a 2a 20 20 20 20  ean query.**    
225d0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
225e0 69 6e 64 69 63 61 74 65 73 20 74 68 61 74 20 74  indicates that t
225f0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22600 20 69 73 20 73 74 6f 72 65 64 20 6f 6e 0a 2a 2a   is stored on.**
22610 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20 6d       read-only m
22620 65 64 69 61 2e 20 20 5e 57 68 65 6e 20 69 6d 6d  edia.  ^When imm
22630 75 74 61 62 6c 65 20 69 73 20 73 65 74 2c 20 53  utable is set, S
22640 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20 74 68  QLite assumes th
22650 61 74 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61  at the.**     da
22660 74 61 62 61 73 65 20 66 69 6c 65 20 63 61 6e 6e  tabase file cann
22670 6f 74 20 62 65 20 63 68 61 6e 67 65 64 2c 20 65  ot be changed, e
22680 76 65 6e 20 62 79 20 61 20 70 72 6f 63 65 73 73  ven by a process
22690 20 77 69 74 68 20 68 69 67 68 65 72 0a 2a 2a 20   with higher.** 
226a0 20 20 20 20 70 72 69 76 69 6c 65 67 65 2c 20 61      privilege, a
226b0 6e 64 20 73 6f 20 74 68 65 20 64 61 74 61 62 61  nd so the databa
226c0 73 65 20 69 73 20 6f 70 65 6e 65 64 20 72 65 61  se is opened rea
226d0 64 2d 6f 6e 6c 79 20 61 6e 64 20 61 6c 6c 20 6c  d-only and all l
226e0 6f 63 6b 69 6e 67 0a 2a 2a 20 20 20 20 20 61 6e  ocking.**     an
226f0 64 20 63 68 61 6e 67 65 20 64 65 74 65 63 74 69  d change detecti
22700 6f 6e 20 69 73 20 64 69 73 61 62 6c 65 64 2e 20  on is disabled. 
22710 20 43 61 75 74 69 6f 6e 3a 20 53 65 74 74 69 6e   Caution: Settin
22720 67 20 74 68 65 20 69 6d 6d 75 74 61 62 6c 65 0a  g the immutable.
22730 2a 2a 20 20 20 20 20 70 72 6f 70 65 72 74 79 20  **     property 
22740 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20 66 69  on a database fi
22750 6c 65 20 74 68 61 74 20 64 6f 65 73 20 69 6e 20  le that does in 
22760 66 61 63 74 20 63 68 61 6e 67 65 20 63 61 6e 20  fact change can 
22770 72 65 73 75 6c 74 0a 2a 2a 20 20 20 20 20 69 6e  result.**     in
22780 20 69 6e 63 6f 72 72 65 63 74 20 71 75 65 72 79   incorrect query
22790 20 72 65 73 75 6c 74 73 20 61 6e 64 2f 6f 72 20   results and/or 
227a0 5b 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d  [SQLITE_CORRUPT]
227b0 20 65 72 72 6f 72 73 2e 0a 2a 2a 20 20 20 20 20   errors..**     
227c0 53 65 65 20 61 6c 73 6f 3a 20 5b 53 51 4c 49 54  See also: [SQLIT
227d0 45 5f 49 4f 43 41 50 5f 49 4d 4d 55 54 41 42 4c  E_IOCAP_IMMUTABL
227e0 45 5d 2e 0a 2a 2a 20 20 20 20 20 20 20 0a 2a 2a  E]..**       .**
227f0 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70   </ul>.**.** ^Sp
22800 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e  ecifying an unkn
22810 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20 69 6e  own parameter in
22820 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d 70 6f   the query compo
22830 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 69 73  nent of a URI is
22840 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72   not an.** error
22850 2e 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f  .  Future versio
22860 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67  ns of SQLite mig
22870 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20 61 64  ht understand ad
22880 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a  ditional query.*
22890 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20 53  * parameters.  S
228a0 65 65 20 22 5b 71 75 65 72 79 20 70 61 72 61 6d  ee "[query param
228b0 65 74 65 72 73 20 77 69 74 68 20 73 70 65 63 69  eters with speci
228c0 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51  al meaning to SQ
228d0 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64  Lite]" for.** ad
228e0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
228f0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52  tion..**.** [[UR
22900 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70  I filename examp
22910 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69  les]] <h3>URI fi
22920 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c  lename examples<
22930 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c  /h3>.**.** <tabl
22940 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69  e border="1" ali
22950 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61  gn=center cellpa
22960 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e  dding=5>.** <tr>
22970 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d  <th> URI filenam
22980 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a  es <th> Results.
22990 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65  ** <tr><td> file
229a0 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a  :data.db <td> .*
229b0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
229c0 74 68 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64  the file "data.d
229d0 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e  b" in the curren
229e0 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20  t directory..** 
229f0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68  <tr><td> file:/h
22a00 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62  ome/fred/data.db
22a10 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20  <br>.**         
22a20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72   file:///home/fr
22a30 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20  ed/data.db <br> 
22a40 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c  .**          fil
22a50 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f  e://localhost/ho
22a60 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
22a70 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  <br> <td> .**   
22a80 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20         Open the 
22a90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f  database file "/
22aa0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22ab0 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  b"..** <tr><td> 
22ac0 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f  file://darkstar/
22ad0 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
22ae0 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  b <td> .**      
22af0 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64      An error. "d
22b00 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20  arkstar" is not 
22b10 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74  a recognized aut
22b20 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c  hority..** <tr><
22b30 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d  td style="white-
22b40 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a  space:nowrap"> .
22b50 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65  **          file
22b60 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73  :///C:/Documents
22b70 25 32 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67  %20and%20Setting
22b80 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64  s/fred/Desktop/d
22b90 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74  ata.db.**     <t
22ba0 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a  d> Windows only:
22bb0 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22   Open the file "
22bc0 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64  data.db" on fred
22bd0 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72  's desktop on dr
22be0 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  ive.**          
22bf0 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68  C:. Note that th
22c00 65 20 25 32 30 20 65 73 63 61 70 69 6e 67 20 69  e %20 escaping i
22c10 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69  n this example i
22c20 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a  s not strictly .
22c30 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65 63 65  **          nece
22c40 73 73 61 72 79 20 2d 20 73 70 61 63 65 20 63 68  ssary - space ch
22c50 61 72 61 63 74 65 72 73 20 63 61 6e 20 62 65 20  aracters can be 
22c60 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a  used literally.*
22c70 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52  *          in UR
22c80 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20  I filenames..** 
22c90 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
22ca0 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61  ta.db?mode=ro&ca
22cb0 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e  che=private <td>
22cc0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70   .**          Op
22cd0 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62  en file "data.db
22ce0 22 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74  " in the current
22cf0 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72   directory for r
22d00 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e  ead-only access.
22d10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52 65 67  .**          Reg
22d20 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
22d30 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64  er or not shared
22d40 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65  -cache mode is e
22d50 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20  nabled by.**    
22d60 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75        default, u
22d70 73 65 20 61 20 70 72 69 76 61 74 65 20 63 61 63  se a private cac
22d80 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  he..** <tr><td> 
22d90 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f  file:/home/fred/
22da0 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78  data.db?vfs=unix
22db0 2d 64 6f 74 66 69 6c 65 20 3c 74 64 3e 0a 2a 2a  -dotfile <td>.**
22dc0 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 66            Open f
22dd0 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f  ile "/home/fred/
22de0 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74 68  data.db". Use th
22df0 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22 75  e special VFS "u
22e00 6e 69 78 2d 64 6f 74 66 69 6c 65 22 0a 2a 2a 20  nix-dotfile".** 
22e10 20 20 20 20 20 20 20 20 20 74 68 61 74 20 75 73           that us
22e20 65 73 20 64 6f 74 2d 66 69 6c 65 73 20 69 6e 20  es dot-files in 
22e30 70 6c 61 63 65 20 6f 66 20 70 6f 73 69 78 20 61  place of posix a
22e40 64 76 69 73 6f 72 79 20 6c 6f 63 6b 69 6e 67 2e  dvisory locking.
22e50 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
22e60 65 3a 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72  e:data.db?mode=r
22e70 65 61 64 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a  eadonly <td> .**
22e80 20 20 20 20 20 20 20 20 20 20 41 6e 20 65 72 72            An err
22e90 6f 72 2e 20 22 72 65 61 64 6f 6e 6c 79 22 20 69  or. "readonly" i
22ea0 73 20 6e 6f 74 20 61 20 76 61 6c 69 64 20 6f 70  s not a valid op
22eb0 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f  tion for the "mo
22ec0 64 65 22 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  de" parameter..*
22ed0 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a  * </table>.**.**
22ee0 20 5e 55 52 49 20 68 65 78 61 64 65 63 69 6d 61   ^URI hexadecima
22ef0 6c 20 65 73 63 61 70 65 20 73 65 71 75 65 6e 63  l escape sequenc
22f00 65 73 20 28 25 48 48 29 20 61 72 65 20 73 75 70  es (%HH) are sup
22f10 70 6f 72 74 65 64 20 77 69 74 68 69 6e 20 74 68  ported within th
22f20 65 20 70 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75  e path and.** qu
22f30 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f  ery components o
22f40 66 20 61 20 55 52 49 2e 20 41 20 68 65 78 61 64  f a URI. A hexad
22f50 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
22f60 71 75 65 6e 63 65 20 63 6f 6e 73 69 73 74 73 20  quence consists 
22f70 6f 66 20 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20  of a.** percent 
22f80 73 69 67 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c  sign - "%" - fol
22f90 6c 6f 77 65 64 20 62 79 20 65 78 61 63 74 6c 79  lowed by exactly
22fa0 20 74 77 6f 20 68 65 78 61 64 65 63 69 6d 61 6c   two hexadecimal
22fb0 20 64 69 67 69 74 73 20 0a 2a 2a 20 73 70 65 63   digits .** spec
22fc0 69 66 79 69 6e 67 20 61 6e 20 6f 63 74 65 74 20  ifying an octet 
22fd0 76 61 6c 75 65 2e 20 5e 42 65 66 6f 72 65 20 74  value. ^Before t
22fe0 68 65 20 70 61 74 68 20 6f 72 20 71 75 65 72 79  he path or query
22ff0 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
23000 0a 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65  .** URI filename
23010 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64   are interpreted
23020 2c 20 74 68 65 79 20 61 72 65 20 65 6e 63 6f 64  , they are encod
23030 65 64 20 75 73 69 6e 67 20 55 54 46 2d 38 20 61  ed using UTF-8 a
23040 6e 64 20 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64  nd all .** hexad
23050 65 63 69 6d 61 6c 20 65 73 63 61 70 65 20 73 65  ecimal escape se
23060 71 75 65 6e 63 65 73 20 72 65 70 6c 61 63 65 64  quences replaced
23070 20 62 79 20 61 20 73 69 6e 67 6c 65 20 62 79 74   by a single byt
23080 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
23090 0a 2a 2a 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  .** correspondin
230a0 67 20 6f 63 74 65 74 2e 20 49 66 20 74 68 69 73  g octet. If this
230b0 20 70 72 6f 63 65 73 73 20 67 65 6e 65 72 61 74   process generat
230c0 65 73 20 61 6e 20 69 6e 76 61 6c 69 64 20 55 54  es an invalid UT
230d0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a  F-8 encoding,.**
230e0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
230f0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
23100 2a 20 3c 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e  * <b>Note to Win
23110 64 6f 77 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20  dows users:</b> 
23120 20 54 68 65 20 65 6e 63 6f 64 69 6e 67 20 75 73   The encoding us
23130 65 64 20 66 6f 72 20 74 68 65 20 66 69 6c 65 6e  ed for the filen
23140 61 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  ame argument.** 
23150 6f 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  of sqlite3_open(
23160 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70  ) and sqlite3_op
23170 65 6e 5f 76 32 28 29 20 6d 75 73 74 20 62 65 20  en_v2() must be 
23180 55 54 46 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65  UTF-8, not whate
23190 76 65 72 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20  ver.** codepage 
231a0 69 73 20 63 75 72 72 65 6e 74 6c 79 20 64 65 66  is currently def
231b0 69 6e 65 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73  ined.  Filenames
231c0 20 63 6f 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65   containing inte
231d0 72 6e 61 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61  rnational.** cha
231e0 72 61 63 74 65 72 73 20 6d 75 73 74 20 62 65 20  racters must be 
231f0 63 6f 6e 76 65 72 74 65 64 20 74 6f 20 55 54 46  converted to UTF
23200 2d 38 20 70 72 69 6f 72 20 74 6f 20 70 61 73 73  -8 prior to pass
23210 69 6e 67 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a  ing them into.**
23220 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
23230 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  or sqlite3_open_
23240 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e  v2()..**.** <b>N
23250 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 52  ote to Windows R
23260 75 6e 74 69 6d 65 20 75 73 65 72 73 3a 3c 2f 62  untime users:</b
23270 3e 20 20 54 68 65 20 74 65 6d 70 6f 72 61 72 79  >  The temporary
23280 20 64 69 72 65 63 74 6f 72 79 20 6d 75 73 74 20   directory must 
23290 62 65 20 73 65 74 0a 2a 2a 20 70 72 69 6f 72 20  be set.** prior 
232a0 74 6f 20 63 61 6c 6c 69 6e 67 20 73 71 6c 69 74  to calling sqlit
232b0 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c  e3_open() or sql
232c0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 20  ite3_open_v2(). 
232d0 20 4f 74 68 65 72 77 69 73 65 2c 20 76 61 72 69   Otherwise, vari
232e0 6f 75 73 0a 2a 2a 20 66 65 61 74 75 72 65 73 20  ous.** features 
232f0 74 68 61 74 20 72 65 71 75 69 72 65 20 74 68 65  that require the
23300 20 75 73 65 20 6f 66 20 74 65 6d 70 6f 72 61 72   use of temporar
23310 79 20 66 69 6c 65 73 20 6d 61 79 20 66 61 69 6c  y files may fail
23320 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
23330 3a 20 5b 73 71 6c 69 74 65 33 5f 74 65 6d 70 5f  : [sqlite3_temp_
23340 64 69 72 65 63 74 6f 72 79 5d 0a 2a 2f 0a 69 6e  directory].*/.in
23350 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 0a  t sqlite3_open(.
23360 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23370 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23380 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
23390 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
233a0 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
233b0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
233c0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
233d0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
233e0 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73 74 20 76  pen16(.  const v
233f0 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20  oid *filename,  
23400 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69 6c   /* Database fil
23410 65 6e 61 6d 65 20 28 55 54 46 2d 31 36 29 20 2a  ename (UTF-16) *
23420 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
23430 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
23440 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
23450 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
23460 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 0a  qlite3_open_v2(.
23470 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 66 69    const char *fi
23480 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74  lename,   /* Dat
23490 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28  abase filename (
234a0 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73 71 6c 69  UTF-8) */.  sqli
234b0 74 65 33 20 2a 2a 70 70 44 62 2c 20 20 20 20 20  te3 **ppDb,     
234c0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
234d0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
234e0 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 20 20 20    int flags,    
234f0 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 6c 61            /* Fla
23500 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  gs */.  const ch
23510 61 72 20 2a 7a 56 66 73 20 20 20 20 20 20 20 20  ar *zVfs        
23520 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46 53 20 6d  /* Name of VFS m
23530 6f 64 75 6c 65 20 74 6f 20 75 73 65 20 2a 2f 0a  odule to use */.
23540 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23550 45 46 3a 20 4f 62 74 61 69 6e 20 56 61 6c 75 65  EF: Obtain Value
23560 73 20 46 6f 72 20 55 52 49 20 50 61 72 61 6d 65  s For URI Parame
23570 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ters.**.** These
23580 20 61 72 65 20 75 74 69 6c 69 74 79 20 72 6f 75   are utility rou
23590 74 69 6e 65 73 2c 20 75 73 65 66 75 6c 20 74 6f  tines, useful to
235a0 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74   VFS implementat
235b0 69 6f 6e 73 2c 20 74 68 61 74 20 63 68 65 63 6b  ions, that check
235c0 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66 20 61 20  .** to see if a 
235d0 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77 61  database file wa
235e0 73 20 61 20 55 52 49 20 74 68 61 74 20 63 6f 6e  s a URI that con
235f0 74 61 69 6e 65 64 20 61 20 73 70 65 63 69 66 69  tained a specifi
23600 63 20 71 75 65 72 79 20 0a 2a 2a 20 70 61 72 61  c query .** para
23610 6d 65 74 65 72 2c 20 61 6e 64 20 69 66 20 73 6f  meter, and if so
23620 20 6f 62 74 61 69 6e 73 20 74 68 65 20 76 61 6c   obtains the val
23630 75 65 20 6f 66 20 74 68 61 74 20 71 75 65 72 79  ue of that query
23640 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
23650 2a 20 49 66 20 46 20 69 73 20 74 68 65 20 64 61  * If F is the da
23660 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20  tabase filename 
23670 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
23680 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 20  nto the xOpen() 
23690 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a 20 61 20  method of .** a 
236a0 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
236b0 6f 6e 20 77 68 65 6e 20 74 68 65 20 66 6c 61 67  on when the flag
236c0 73 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  s parameter to x
236d0 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e 65 20 6f  Open() has one o
236e0 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66 20 74 68  r .** more of th
236f0 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  e [SQLITE_OPEN_U
23700 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4f  RI] or [SQLITE_O
23710 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20 62 69 74  PEN_MAIN_DB] bit
23720 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20 50 20 69  s set and.** P i
23730 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
23740 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
23750 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  r, then.** sqlit
23760 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
23770 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 74 68  (F,P) returns th
23780 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 50  e value of the P
23790 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 66  .** parameter if
237a0 20 69 74 20 65 78 69 73 74 73 20 6f 72 20 61 20   it exists or a 
237b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20  NULL pointer if 
237c0 50 20 64 6f 65 73 20 6e 6f 74 20 61 70 70 65 61  P does not appea
237d0 72 20 61 73 20 61 20 0a 2a 2a 20 71 75 65 72 79  r as a .** query
237e0 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46 2e   parameter on F.
237f0 20 20 49 66 20 50 20 69 73 20 61 20 71 75 65 72    If P is a quer
23800 79 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 46  y parameter of F
23810 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78 70 6c 69  .** has no expli
23820 63 69 74 20 76 61 6c 75 65 2c 20 74 68 65 6e 20  cit value, then 
23830 73 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61  sqlite3_uri_para
23840 6d 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72  meter(F,P) retur
23850 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74 65 72 20  ns.** a pointer 
23860 74 6f 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69  to an empty stri
23870 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ng..**.** The sq
23880 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23890 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74 69 6e 65  n(F,P,B) routine
238a0 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 50 20   assumes that P 
238b0 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a 2a 2a 20  is a boolean.** 
238c0 70 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65  parameter and re
238d0 74 75 72 6e 73 20 74 72 75 65 20 28 31 29 20 6f  turns true (1) o
238e0 72 20 66 61 6c 73 65 20 28 30 29 20 61 63 63 6f  r false (0) acco
238f0 72 64 69 6e 67 20 74 6f 20 74 68 65 20 76 61 6c  rding to the val
23900 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20 54 68 65  ue.** of P.  The
23910 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
23920 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
23930 69 6e 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ine returns true
23940 20 28 31 29 20 69 66 20 74 68 65 0a 2a 2a 20 76   (1) if the.** v
23950 61 6c 75 65 20 6f 66 20 71 75 65 72 79 20 70 61  alue of query pa
23960 72 61 6d 65 74 65 72 20 50 20 69 73 20 6f 6e 65  rameter P is one
23970 20 6f 66 20 22 79 65 73 22 2c 20 22 74 72 75 65   of "yes", "true
23980 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e 20 61 6e  ", or "on" in an
23990 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20 69 66 20  y.** case or if 
239a0 74 68 65 20 76 61 6c 75 65 20 62 65 67 69 6e 73  the value begins
239b0 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a 65 72 6f   with a non-zero
239c0 20 6e 75 6d 62 65 72 2e 20 20 54 68 65 20 0a 2a   number.  The .*
239d0 2a 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  * sqlite3_uri_bo
239e0 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75  olean(F,P,B) rou
239f0 74 69 6e 65 73 20 72 65 74 75 72 6e 73 20 66 61  tines returns fa
23a00 6c 73 65 20 28 30 29 20 69 66 20 74 68 65 20 76  lse (0) if the v
23a10 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75 65 72 79  alue of.** query
23a20 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
23a30 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20 22 66 61  one of "no", "fa
23a40 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66 22 20 69  lse", or "off" i
23a50 6e 20 61 6e 79 20 63 61 73 65 20 6f 72 0a 2a 2a  n any case or.**
23a60 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65   if the value be
23a70 67 69 6e 73 20 77 69 74 68 20 61 20 6e 75 6d 65  gins with a nume
23a80 72 69 63 20 7a 65 72 6f 2e 20 20 49 66 20 50 20  ric zero.  If P 
23a90 69 73 20 6e 6f 74 20 61 20 71 75 65 72 79 0a 2a  is not a query.*
23aa0 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 46  * parameter on F
23ab0 20 6f 72 20 69 66 20 74 68 65 20 76 61 6c 75 65   or if the value
23ac0 20 6f 66 20 50 20 69 73 20 64 6f 65 73 20 6e 6f   of P is does no
23ad0 74 20 6d 61 74 63 68 20 61 6e 79 20 6f 66 20 74  t match any of t
23ae0 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20 74 68 65  he.** above, the
23af0 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f  n sqlite3_uri_bo
23b00 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 65 74  olean(F,P,B) ret
23b10 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a 2a 2a 0a  urns (B!=0)..**.
23b20 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 75  ** The sqlite3_u
23b30 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c 44 29 20  ri_int64(F,P,D) 
23b40 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65 72 74 73  routine converts
23b50 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 50 20   the value of P 
23b60 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d 62 69 74  into a.** 64-bit
23b70 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72 20   signed integer 
23b80 61 6e 64 20 72 65 74 75 72 6e 73 20 74 68 61 74  and returns that
23b90 20 69 6e 74 65 67 65 72 2c 20 6f 72 20 44 20 69   integer, or D i
23ba0 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  f P does not.** 
23bb0 65 78 69 73 74 2e 20 20 49 66 20 74 68 65 20 76  exist.  If the v
23bc0 61 6c 75 65 20 6f 66 20 50 20 69 73 20 73 6f 6d  alue of P is som
23bd0 65 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61  ething other tha
23be0 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c 20 74 68  n an integer, th
23bf0 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73 20 72 65  en.** zero is re
23c00 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a 2a 20 49  turned..** .** I
23c10 66 20 46 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  f F is a NULL po
23c20 69 6e 74 65 72 2c 20 74 68 65 6e 20 73 71 6c 69  inter, then sqli
23c30 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65  te3_uri_paramete
23c40 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73 20 4e  r(F,P) returns N
23c50 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74  ULL and.** sqlit
23c60 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61 6e 28 46  e3_uri_boolean(F
23c70 2c 50 2c 42 29 20 72 65 74 75 72 6e 73 20 42 2e  ,P,B) returns B.
23c80 20 20 49 66 20 46 20 69 73 20 6e 6f 74 20 61 20    If F is not a 
23c90 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 61 6e 64  NULL pointer and
23ca0 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20 64 61 74  .** is not a dat
23cb0 61 62 61 73 65 20 66 69 6c 65 20 70 61 74 68 6e  abase file pathn
23cc0 61 6d 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  ame pointer that
23cd0 20 53 51 4c 69 74 65 20 70 61 73 73 65 64 20 69   SQLite passed i
23ce0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 0a 2a 2a  nto the xOpen.**
23cf0 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
23d00 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
23d10 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  f this routine i
23d20 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
23d30 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75 6e 64 65  probably.** unde
23d40 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
23d50 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
23d60 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
23d70 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
23d80 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
23d90 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74 20 73 71  *zParam);.int sq
23da0 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
23db0 6e 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46  n(const char *zF
23dc0 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ile, const char 
23dd0 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20 62 44 65  *zParam, int bDe
23de0 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74 65 33 5f  fault);.sqlite3_
23df0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75 72  int64 sqlite3_ur
23e00 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74 20 63 68  i_int64(const ch
23e10 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a  ar*, const char*
23e20 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29  , sqlite3_int64)
23e30 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  ;.../*.** CAPI3R
23e40 45 46 3a 20 45 72 72 6f 72 20 43 6f 64 65 73 20  EF: Error Codes 
23e50 41 6e 64 20 4d 65 73 73 61 67 65 73 0a 2a 2a 0a  And Messages.**.
23e60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
23e70 65 72 72 63 6f 64 65 28 29 20 69 6e 74 65 72 66  errcode() interf
23e80 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
23e90 6e 75 6d 65 72 69 63 20 5b 72 65 73 75 6c 74 20  numeric [result 
23ea0 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74  code] or.** [ext
23eb0 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
23ec0 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f 73 74 20  e] for the most 
23ed0 72 65 63 65 6e 74 20 66 61 69 6c 65 64 20 73 71  recent failed sq
23ee0 6c 69 74 65 33 5f 2a 20 41 50 49 20 63 61 6c 6c  lite3_* API call
23ef0 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
23f00 69 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20  ith a [database 
23f10 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 49 66 20  connection]. If 
23f20 61 20 70 72 69 6f 72 20 41 50 49 20 63 61 6c 6c  a prior API call
23f30 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75 74 20 74   failed.** but t
23f40 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 41  he most recent A
23f50 50 49 20 63 61 6c 6c 20 73 75 63 63 65 65 64 65  PI call succeede
23f60 64 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  d, the return va
23f70 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c 69  lue from.** sqli
23f80 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 73  te3_errcode() is
23f90 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 5e 54 68   undefined.  ^Th
23fa0 65 20 73 71 6c 69 74 65 33 5f 65 78 74 65 6e 64  e sqlite3_extend
23fb0 65 64 5f 65 72 72 63 6f 64 65 28 29 0a 2a 2a 20  ed_errcode().** 
23fc0 69 6e 74 65 72 66 61 63 65 20 69 73 20 74 68 65  interface is the
23fd0 20 73 61 6d 65 20 65 78 63 65 70 74 20 74 68 61   same except tha
23fe0 74 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  t it always retu
23ff0 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b 65 78 74  rns the .** [ext
24000 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24010 65 5d 20 65 76 65 6e 20 77 68 65 6e 20 65 78 74  e] even when ext
24020 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64  ended result cod
24030 65 73 20 61 72 65 0a 2a 2a 20 64 69 73 61 62 6c  es are.** disabl
24040 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ed..**.** ^The s
24050 71 6c 69 74 65 33 5f 65 72 72 6d 73 67 28 29 20  qlite3_errmsg() 
24060 61 6e 64 20 73 71 6c 69 74 65 33 5f 65 72 72 6d  and sqlite3_errm
24070 73 67 31 36 28 29 20 72 65 74 75 72 6e 20 45 6e  sg16() return En
24080 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67 65 0a 2a  glish-language.*
24090 2a 20 74 65 78 74 20 74 68 61 74 20 64 65 73 63  * text that desc
240a0 72 69 62 65 73 20 74 68 65 20 65 72 72 6f 72 2c  ribes the error,
240b0 20 61 73 20 65 69 74 68 65 72 20 55 54 46 2d 38   as either UTF-8
240c0 20 6f 72 20 55 54 46 2d 31 36 20 72 65 73 70 65   or UTF-16 respe
240d0 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 28 4d 65  ctively..** ^(Me
240e0 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65  mory to hold the
240f0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73   error message s
24100 74 72 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64  tring is managed
24110 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a 2a 2a 20   internally..** 
24120 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
24130 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f  does not need to
24140 20 77 6f 72 72 79 20 61 62 6f 75 74 20 66 72 65   worry about fre
24150 65 69 6e 67 20 74 68 65 20 72 65 73 75 6c 74 2e  eing the result.
24160 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 74 68 65  .** However, the
24170 20 65 72 72 6f 72 20 73 74 72 69 6e 67 20 6d 69   error string mi
24180 67 68 74 20 62 65 20 6f 76 65 72 77 72 69 74 74  ght be overwritt
24190 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63 61 74 65  en or deallocate
241a0 64 20 62 79 0a 2a 2a 20 73 75 62 73 65 71 75 65  d by.** subseque
241b0 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f 74 68 65  nt calls to othe
241c0 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  r SQLite interfa
241d0 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e 29 5e 0a  ce functions.)^.
241e0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
241f0 65 33 5f 65 72 72 73 74 72 28 29 20 69 6e 74 65  e3_errstr() inte
24200 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
24210 65 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  e English-langua
24220 67 65 20 74 65 78 74 0a 2a 2a 20 74 68 61 74 20  ge text.** that 
24230 64 65 73 63 72 69 62 65 73 20 74 68 65 20 5b 72  describes the [r
24240 65 73 75 6c 74 20 63 6f 64 65 5d 2c 20 61 73 20  esult code], as 
24250 55 54 46 2d 38 2e 0a 2a 2a 20 5e 28 4d 65 6d 6f  UTF-8..** ^(Memo
24260 72 79 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 65  ry to hold the e
24270 72 72 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72  rror message str
24280 69 6e 67 20 69 73 20 6d 61 6e 61 67 65 64 20 69  ing is managed i
24290 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a 20 61 6e 64  nternally.** and
242a0 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 66 72 65   must not be fre
242b0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
242c0 61 74 69 6f 6e 29 5e 2e 0a 2a 2a 0a 2a 2a 20 57  ation)^..**.** W
242d0 68 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a  hen the serializ
242e0 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
242f0 64 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69  de] is in use, i
24300 74 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a  t might be the.*
24310 2a 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65  * case that a se
24320 63 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72  cond error occur
24330 73 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20  s on a separate 
24340 74 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65  thread in betwee
24350 6e 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66  n.** the time of
24360 20 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72   the first error
24370 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f   and the call to
24380 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
24390 73 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20  s..** When that 
243a0 68 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63  happens, the sec
243b0 6f 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62  ond error will b
243c0 65 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65  e reported since
243d0 20 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66   these.** interf
243e0 61 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f  aces always repo
243f0 72 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  rt the most rece
24400 6e 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61  nt result.  To a
24410 76 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61  void.** this, ea
24420 63 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62  ch thread can ob
24430 74 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75  tain exclusive u
24440 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62  se of the [datab
24450 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
24460 44 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67  D.** by invoking
24470 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
24480 65 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f  enter]([sqlite3_
24490 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65  db_mutex](D)) be
244a0 66 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a  fore beginning.*
244b0 2a 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69  * to use D and i
244c0 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33  nvoking [sqlite3
244d0 5f 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73  _mutex_leave]([s
244e0 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d  qlite3_db_mutex]
244f0 28 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c  (D)) after.** al
24500 6c 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69  l calls to the i
24510 6e 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64  nterfaces listed
24520 20 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65   here are comple
24530 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e  ted..**.** If an
24540 20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73   interface fails
24550 20 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53   with SQLITE_MIS
24560 55 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  USE, that means 
24570 74 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  the interface.**
24580 20 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63   was invoked inc
24590 6f 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20  orrectly by the 
245a0 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e  application.  In
245b0 20 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a   that case, the.
245c0 2a 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e  ** error code an
245d0 64 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72  d message may or
245e0 20 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e   may not be set.
245f0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
24600 65 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20  errcode(sqlite3 
24610 2a 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *db);.int sqlite
24620 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
24630 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
24640 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24650 69 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69  ite3_errmsg(sqli
24660 74 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  te3*);.const voi
24670 64 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  d *sqlite3_errms
24680 67 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 63  g16(sqlite3*);.c
24690 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
246a0 65 33 5f 65 72 72 73 74 72 28 69 6e 74 29 3b 0a  e3_errstr(int);.
246b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
246c0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f   SQL Statement O
246d0 62 6a 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44  bject.** KEYWORD
246e0 53 3a 20 7b 70 72 65 70 61 72 65 64 20 73 74 61  S: {prepared sta
246f0 74 65 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65  tement} {prepare
24700 64 20 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a  d statements}.**
24710 0a 2a 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20  .** An instance 
24720 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72  of this object r
24730 65 70 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67  epresents a sing
24740 6c 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  le SQL statement
24750 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  ..** This object
24760 20 69 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e   is variously kn
24770 6f 77 6e 20 61 73 20 61 20 22 70 72 65 70 61 72  own as a "prepar
24780 65 64 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72  ed statement" or
24790 20 61 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20   a.** "compiled 
247a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f  SQL statement" o
247b0 72 20 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73  r simply as a "s
247c0 74 61 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a  tatement"..**.**
247d0 20 54 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73   The life of a s
247e0 74 61 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20  tatement object 
247f0 67 6f 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c  goes something l
24800 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
24810 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65  <ol>.** <li> Cre
24820 61 74 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75  ate the object u
24830 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72  sing [sqlite3_pr
24840 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61  epare_v2()] or a
24850 20 72 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20   related.**     
24860 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c   function..** <l
24870 69 3e 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74  i> Bind values t
24880 6f 20 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  o [host paramete
24890 72 73 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71  rs] using the sq
248a0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a  lite3_bind_*().*
248b0 2a 20 20 20 20 20 20 69 6e 74 65 72 66 61 63 65  *      interface
248c0 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74  s..** <li> Run t
248d0 68 65 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e  he SQL by callin
248e0 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  g [sqlite3_step(
248f0 29 5d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74  )] one or more t
24900 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65  imes..** <li> Re
24910 73 65 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  set the statemen
24920 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
24930 5f 72 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67  _reset()] then g
24940 6f 20 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74  o back.**      t
24950 6f 20 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68  o step 2.  Do th
24960 69 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20  is zero or more 
24970 74 69 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44  times..** <li> D
24980 65 73 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63  estroy the objec
24990 74 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  t using [sqlite3
249a0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a  _finalize()]..**
249b0 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66   </ol>.**.** Ref
249c0 65 72 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74  er to documentat
249d0 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61  ion on individua
249e0 6c 20 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20  l methods above 
249f0 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  for additional.*
24a00 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a  * information..*
24a10 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
24a20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71   sqlite3_stmt sq
24a30 6c 69 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a  lite3_stmt;../*.
24a40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e  ** CAPI3REF: Run
24a50 2d 74 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a  -time Limits.**.
24a60 2a 2a 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66  ** ^(This interf
24a70 61 63 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73  ace allows the s
24a80 69 7a 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63  ize of various c
24a90 6f 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20  onstructs to be 
24aa0 6c 69 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20  limited.** on a 
24ab0 63 6f 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f  connection by co
24ac0 6e 6e 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20  nnection basis. 
24ad0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
24ae0 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b  eter is the.** [
24af0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
24b00 69 6f 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74  ion] whose limit
24b10 20 69 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72   is to be set or
24b20 20 71 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a   queried.  The.*
24b30 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
24b40 65 72 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65  er is one of the
24b50 20 5b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69   [limit categori
24b60 65 73 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20  es] that define 
24b70 61 0a 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f  a.** class of co
24b80 6e 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 73  nstructs to be s
24b90 69 7a 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68  ize limited.  Th
24ba0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
24bb0 72 20 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20  r is the.** new 
24bc0 6c 69 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63  limit for that c
24bd0 6f 6e 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a  onstruct.)^.**.*
24be0 2a 20 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69  * ^If the new li
24bf0 6d 69 74 20 69 73 20 61 20 6e 65 67 61 74 69 76  mit is a negativ
24c00 65 20 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69  e number, the li
24c10 6d 69 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64  mit is unchanged
24c20 2e 0a 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20  ..** ^(For each 
24c30 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53  limit category S
24c40 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e  QLITE_LIMIT_<i>N
24c50 41 4d 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73  AME</i> there is
24c60 20 61 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c   a .** [limits |
24c70 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e   hard upper boun
24c80 64 5d 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d  d].** set at com
24c90 70 69 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43  pile-time by a C
24ca0 20 70 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61   preprocessor ma
24cb0 63 72 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c  cro called.** [l
24cc0 69 6d 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d  imits | SQLITE_M
24cd0 41 58 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e  AX_<i>NAME</i>].
24ce0 0a 2a 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54  .** (The "_LIMIT
24cf0 5f 22 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69  _" in the name i
24d00 73 20 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d  s changed to "_M
24d10 41 58 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74  AX_".))^.** ^Att
24d20 65 6d 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73  empts to increas
24d30 65 20 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20  e a limit above 
24d40 69 74 73 20 68 61 72 64 20 75 70 70 65 72 20 62  its hard upper b
24d50 6f 75 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65  ound are.** sile
24d60 6e 74 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74  ntly truncated t
24d70 6f 20 74 68 65 20 68 61 72 64 20 75 70 70 65 72  o the hard upper
24d80 20 62 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52   bound..**.** ^R
24d90 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
24da0 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
24db0 6c 69 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65  limit was change
24dc0 64 2c 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69  d, the .** [sqli
24dd0 74 65 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74  te3_limit()] int
24de0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
24df0 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
24e00 66 20 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20  f the limit..** 
24e10 5e 48 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20  ^Hence, to find 
24e20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75  the current valu
24e30 65 20 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74  e of a limit wit
24e40 68 6f 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74  hout changing it
24e50 2c 0a 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f  ,.** simply invo
24e60 6b 65 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ke this interfac
24e70 65 20 77 69 74 68 20 74 68 65 20 74 68 69 72 64  e with the third
24e80 20 70 61 72 61 6d 65 74 65 72 20 73 65 74 20 74   parameter set t
24e90 6f 20 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d  o -1..**.** Run-
24ea0 74 69 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20  time limits are 
24eb0 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
24ec0 20 69 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   in applications
24ed0 20 74 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20   that manage.** 
24ee0 62 6f 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69  both their own i
24ef0 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65  nternal database
24f00 20 61 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61   and also databa
24f10 73 65 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e  ses that are con
24f20 74 72 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e  trolled.** by un
24f30 74 72 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c  trusted external
24f40 20 73 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78   sources.  An ex
24f50 61 6d 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f  ample applicatio
24f60 6e 20 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20  n might be a.** 
24f70 77 65 62 20 62 72 6f 77 73 65 72 20 74 68 61 74  web browser that
24f80 20 68 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74   has its own dat
24f90 61 62 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69  abases for stori
24fa0 6e 67 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a  ng history and.*
24fb0 2a 20 73 65 70 61 72 61 74 65 20 64 61 74 61 62  * separate datab
24fc0 61 73 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20  ases controlled 
24fd0 62 79 20 4a 61 76 61 53 63 72 69 70 74 20 61 70  by JavaScript ap
24fe0 70 6c 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c  plications downl
24ff0 6f 61 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65  oaded.** off the
25000 20 49 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20   Internet.  The 
25010 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73  internal databas
25020 65 73 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20  es can be given 
25030 74 68 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65  the.** large, de
25040 66 61 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44  fault limits.  D
25050 61 74 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64  atabases managed
25060 20 62 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75   by external sou
25070 72 63 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67  rces can.** be g
25080 69 76 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65  iven much smalle
25090 72 20 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65  r limits designe
250a0 64 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64  d to prevent a d
250b0 65 6e 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65  enial of service
250c0 0a 2a 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76  .** attack.  Dev
250d0 65 6c 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c  elopers might al
250e0 73 6f 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74  so want to use t
250f0 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  he [sqlite3_set_
25100 61 75 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a  authorizer()].**
25110 20 69 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75   interface to fu
25120 72 74 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e  rther control un
25130 74 72 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68  trusted SQL.  Th
25140 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61  e size of the da
25150 74 61 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65  tabase.** create
25160 64 20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65  d by an untruste
25170 64 20 73 63 72 69 70 74 20 63 61 6e 20 62 65 20  d script can be 
25180 63 6f 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20  contained using 
25190 74 68 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65  the.** [max_page
251a0 5f 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d  _count] [PRAGMA]
251b0 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d  ..**.** New run-
251c0 74 69 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67  time limit categ
251d0 6f 72 69 65 73 20 6d 61 79 20 62 65 20 61 64 64  ories may be add
251e0 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
251f0 65 61 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71  eases..*/.int sq
25200 6c 69 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69  lite3_limit(sqli
25210 74 65 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e  te3*, int id, in
25220 74 20 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a  t newVal);../*.*
25230 2a 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d  * CAPI3REF: Run-
25240 54 69 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67  Time Limit Categ
25250 6f 72 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ories.** KEYWORD
25260 53 3a 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f  S: {limit catego
25270 72 79 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65  ry} {*limit cate
25280 67 6f 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68  gories}.**.** Th
25290 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65  ese constants de
252a0 66 69 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72  fine various per
252b0 66 6f 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a  formance limits.
252c0 2a 2a 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c  ** that can be l
252d0 6f 77 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69  owered at run-ti
252e0 6d 65 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  me using [sqlite
252f0 33 5f 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54  3_limit()]..** T
25300 68 65 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74  he synopsis of t
25310 68 65 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74  he meanings of t
25320 68 65 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74  he various limit
25330 73 20 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77  s is shown below
25340 2e 0a 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20  ..** Additional 
25350 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61  information is a
25360 76 61 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d  vailable at [lim
25370 69 74 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20  its | Limits in 
25380 53 51 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c  SQLite]..**.** <
25390 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  dl>.** [[SQLITE_
253a0 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e  LIMIT_LENGTH]] ^
253b0 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
253c0 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a  T_LENGTH</dt>.**
253d0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
253e0 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72   size of any str
253f0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74  ing or BLOB or t
25400 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74  able row, in byt
25410 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  es.<dd>)^.**.** 
25420 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  [[SQLITE_LIMIT_S
25430 51 4c 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64  QL_LENGTH]] ^(<d
25440 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53  t>SQLITE_LIMIT_S
25450 51 4c 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  QL_LENGTH</dt>.*
25460 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25470 6d 20 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53  m length of an S
25480 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e  QL statement, in
25490 20 62 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a   bytes.</dd>)^.*
254a0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
254b0 4d 49 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c  MIT_COLUMN]] ^(<
254c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
254d0 43 4f 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c  COLUMN</dt>.** <
254e0 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
254f0 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
25500 20 69 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69   in a table defi
25510 6e 69 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65  nition or in the
25520 0a 2a 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f  .** result set o
25530 66 20 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20  f a [SELECT] or 
25540 74 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62  the maximum numb
25550 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e  er of columns in
25560 20 61 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20   an index.** or 
25570 69 6e 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f  in an ORDER BY o
25580 72 20 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73  r GROUP BY claus
25590 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  e.</dd>)^.**.** 
255a0 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  [[SQLITE_LIMIT_E
255b0 58 50 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64  XPR_DEPTH]] ^(<d
255c0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45  t>SQLITE_LIMIT_E
255d0 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a  XPR_DEPTH</dt>.*
255e0 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
255f0 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65 20 70  m depth of the p
25600 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79  arse tree on any
25610 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64   expression.</dd
25620 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
25630 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e  TE_LIMIT_COMPOUN
25640 44 5f 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74  D_SELECT]] ^(<dt
25650 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
25660 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64  MPOUND_SELECT</d
25670 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
25680 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20  ximum number of 
25690 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f  terms in a compo
256a0 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74 65  und SELECT state
256b0 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ment.</dd>)^.**.
256c0 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
256d0 54 5f 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64  T_VDBE_OP]] ^(<d
256e0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
256f0 44 42 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c  DBE_OP</dt>.** <
25700 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
25710 75 6d 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63  umber of instruc
25720 74 69 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75  tions in a virtu
25730 61 6c 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72  al machine progr
25740 61 6d 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d  am.** used to im
25750 70 6c 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73  plement an SQL s
25760 74 61 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20  tatement.  This 
25770 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72  limit is not cur
25780 72 65 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63  rently.** enforc
25790 65 64 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20  ed, though that 
257a0 6d 69 67 68 74 20 62 65 20 61 64 64 65 64 20 69  might be added i
257b0 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65  n some future re
257c0 6c 65 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69  lease of.** SQLi
257d0 74 65 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  te.</dd>)^.**.**
257e0 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
257f0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e  FUNCTION_ARG]] ^
25800 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25810 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f  T_FUNCTION_ARG</
25820 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
25830 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
25840 20 61 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20   arguments on a 
25850 66 75 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e  function.</dd>)^
25860 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
25870 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d  LIMIT_ATTACHED]]
25880 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
25890 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
258a0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
258b0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
258c0 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
258d0 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
258e0 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
258f0 49 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50  ITE_LIMIT_LIKE_P
25900 41 54 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a  ATTERN_LENGTH]].
25910 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f  ** ^(<dt>SQLITE_
25920 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45  LIMIT_LIKE_PATTE
25930 52 4e 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a  RN_LENGTH</dt>.*
25940 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75  * <dd>The maximu
25950 6d 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20  m length of the 
25960 70 61 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74  pattern argument
25970 20 74 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f   to the [LIKE] o
25980 72 0a 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72  r.** [GLOB] oper
25990 61 74 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ators.</dd>)^.**
259a0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
259b0 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
259c0 45 52 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51  ER]].** ^(<dt>SQ
259d0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41  LITE_LIMIT_VARIA
259e0 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a  BLE_NUMBER</dt>.
259f0 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
25a00 75 6d 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20  um index number 
25a10 6f 66 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65  of any [paramete
25a20 72 5d 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61  r] in an SQL sta
25a30 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  tement.)^.**.** 
25a40 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54  [[SQLITE_LIMIT_T
25a50 52 49 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e  RIGGER_DEPTH]] ^
25a60 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
25a70 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c  T_TRIGGER_DEPTH<
25a80 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
25a90 6d 61 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66  maximum depth of
25aa0 20 72 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74   recursion for t
25ab0 72 69 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a  riggers.</dd>)^.
25ac0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
25ad0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
25ae0 5f 4c 45 4e 47 54 48 20 20 20 20 20 20 20 20 20  _LENGTH         
25af0 20 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65             0.#de
25b00 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
25b10 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20  T_SQL_LENGTH    
25b20 20 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64              1.#d
25b30 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
25b40 49 54 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20  IT_COLUMN       
25b50 20 20 20 20 20 20 20 20 20 20 20 20 20 32 0a 23               2.#
25b60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
25b70 4d 49 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20  MIT_EXPR_DEPTH  
25b80 20 20 20 20 20 20 20 20 20 20 20 20 20 20 33 0a                3.
25b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
25ba0 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45  IMIT_COMPOUND_SE
25bb0 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20 34  LECT           4
25bc0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
25bd0 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20  LIMIT_VDBE_OP   
25be0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25bf0 35 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  5.#define SQLITE
25c00 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
25c10 41 52 47 20 20 20 20 20 20 20 20 20 20 20 20 20  ARG             
25c20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   6.#define SQLIT
25c30 45 5f 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44  E_LIMIT_ATTACHED
25c40 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
25c50 20 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    7.#define SQLI
25c60 54 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41  TE_LIMIT_LIKE_PA
25c70 54 54 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20  TTERN_LENGTH    
25c80 20 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c     8.#define SQL
25c90 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
25ca0 4c 45 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20  LE_NUMBER       
25cb0 20 20 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51      9.#define SQ
25cc0 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
25cd0 45 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20  ER_DEPTH        
25ce0 20 20 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41      10../*.** CA
25cf0 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e  PI3REF: Compilin
25d00 67 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  g An SQL Stateme
25d10 6e 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  nt.** KEYWORDS: 
25d20 7b 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63  {SQL statement c
25d30 6f 6d 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54  ompiler}.**.** T
25d40 6f 20 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c  o execute an SQL
25d50 20 71 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20   query, it must 
25d60 66 69 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65  first be compile
25d70 64 20 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f  d into a byte-co
25d80 64 65 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73  de.** program us
25d90 69 6e 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65  ing one of these
25da0 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a   routines..**.**
25db0 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
25dc0 65 6e 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20  ent, "db", is a 
25dd0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
25de0 74 69 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66  tion] obtained f
25df0 72 6f 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73  rom a.** prior s
25e00 75 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74  uccessful call t
25e10 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
25e20 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
25e30 6e 5f 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  n_v2()] or.** [s
25e40 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
25e50 2e 20 20 54 68 65 20 64 61 74 61 62 61 73 65 20  .  The database 
25e60 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
25e70 6e 6f 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c  not have been cl
25e80 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  osed..**.** The 
25e90 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c  second argument,
25ea0 20 22 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20   "zSql", is the 
25eb0 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20  statement to be 
25ec0 63 6f 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65  compiled, encode
25ed0 64 0a 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55  d.** as either U
25ee0 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20  TF-8 or UTF-16. 
25ef0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65   The sqlite3_pre
25f00 70 61 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74  pare() and sqlit
25f10 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a  e3_prepare_v2().
25f20 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 75 73  ** interfaces us
25f30 65 20 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c  e UTF-8, and sql
25f40 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
25f50 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65   and sqlite3_pre
25f60 70 61 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75  pare16_v2().** u
25f70 73 65 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a  se UTF-16..**.**
25f80 20 5e 49 66 20 74 68 65 20 6e 42 79 74 65 20 61   ^If the nByte a
25f90 72 67 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20  rgument is less 
25fa0 74 68 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20  than zero, then 
25fb0 7a 53 71 6c 20 69 73 20 72 65 61 64 20 75 70 20  zSql is read up 
25fc0 74 6f 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  to the.** first 
25fd0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e  zero terminator.
25fe0 20 5e 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f   ^If nByte is no
25ff0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
26000 20 69 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d   it is the maxim
26010 75 6d 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  um.** number of 
26020 20 62 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d   bytes read from
26030 20 7a 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42   zSql.  ^When nB
26040 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
26050 69 76 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c  ive, the.** zSql
26060 20 73 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20   string ends at 
26070 65 69 74 68 65 72 20 74 68 65 20 66 69 72 73 74  either the first
26080 20 27 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30   '\000' or '\u00
26090 30 30 27 20 63 68 61 72 61 63 74 65 72 20 6f 72  00' character or
260a0 0a 2a 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68  .** the nByte-th
260b0 20 62 79 74 65 2c 20 77 68 69 63 68 65 76 65 72   byte, whichever
260c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66   comes first. If
260d0 20 74 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77   the caller know
260e0 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75  s.** that the su
260f0 70 70 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73  pplied string is
26100 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c   nul-terminated,
26110 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20 61   then there is a
26120 20 73 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72   small.** perfor
26130 6d 61 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20  mance advantage 
26140 74 6f 20 62 65 20 67 61 69 6e 65 64 20 62 79 20  to be gained by 
26150 70 61 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65  passing an nByte
26160 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a   parameter that.
26170 2a 2a 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74  ** is equal to t
26180 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
26190 65 73 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20  es in the input 
261a0 73 74 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64  string <i>includ
261b0 69 6e 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e  ing</i>.** the n
261c0 75 6c 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79  ul-terminator by
261d0 74 65 73 20 61 73 20 74 68 69 73 20 73 61 76 65  tes as this save
261e0 73 20 53 51 4c 69 74 65 20 66 72 6f 6d 20 68 61  s SQLite from ha
261f0 76 69 6e 67 20 74 6f 0a 2a 2a 20 6d 61 6b 65 20  ving to.** make 
26200 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 69 6e  a copy of the in
26210 70 75 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a  put string..**.*
26220 2a 20 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20  * ^If pzTail is 
26230 6e 6f 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70  not NULL then *p
26240 7a 54 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f  zTail is made to
26250 20 70 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69   point to the fi
26260 72 73 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74  rst byte.** past
26270 20 74 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20   the end of the 
26280 66 69 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d  first SQL statem
26290 65 6e 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68  ent in zSql.  Th
262a0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c  ese routines onl
262b0 79 0a 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65  y.** compile the
262c0 20 66 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74   first statement
262d0 20 69 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a   in zSql, so *pz
262e0 54 61 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69  Tail is left poi
262f0 6e 74 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74  nting to.** what
26300 20 72 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69   remains uncompi
26310 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53  led..**.** ^*ppS
26320 74 6d 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e  tmt is left poin
26330 74 69 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c  ting to a compil
26340 65 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ed [prepared sta
26350 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e  tement] that can
26360 20 62 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20   be.** executed 
26370 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73  using [sqlite3_s
26380 74 65 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65  tep()].  ^If the
26390 72 65 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20  re is an error, 
263a0 2a 70 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a  *ppStmt is set.*
263b0 2a 20 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20  * to NULL.  ^If 
263c0 74 68 65 20 69 6e 70 75 74 20 74 65 78 74 20 63  the input text c
263d0 6f 6e 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28  ontains no SQL (
263e0 69 66 20 74 68 65 20 69 6e 70 75 74 20 69 73 20  if the input is 
263f0 61 6e 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69  an empty.** stri
26400 6e 67 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29  ng or a comment)
26410 20 74 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73   then *ppStmt is
26420 20 73 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a   set to NULL..**
26430 20 54 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f   The calling pro
26440 63 65 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e  cedure is respon
26450 73 69 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69  sible for deleti
26460 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a  ng the compiled.
26470 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
26480 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
26490 66 69 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65  finalize()] afte
264a0 72 20 69 74 20 68 61 73 20 66 69 6e 69 73 68 65  r it has finishe
264b0 64 20 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70  d with it..** pp
264c0 53 74 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20  Stmt may not be 
264d0 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20  NULL..**.** ^On 
264e0 73 75 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c  success, the sql
264f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20 66  ite3_prepare() f
26500 61 6d 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65  amily of routine
26510 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45  s return [SQLITE
26520 5f 4f 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69  _OK];.** otherwi
26530 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  se an [error cod
26540 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
26550 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
26560 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 20 61  3_prepare_v2() a
26570 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
26580 72 65 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66  re16_v2() interf
26590 61 63 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f  aces are.** reco
265a0 6d 6d 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20  mmended for all 
265b0 6e 65 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68  new programs. Th
265c0 65 20 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65  e two older inte
265d0 72 66 61 63 65 73 20 61 72 65 20 72 65 74 61 69  rfaces are retai
265e0 6e 65 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77  ned.** for backw
265f0 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
26600 74 79 2c 20 62 75 74 20 74 68 65 69 72 20 75 73  ty, but their us
26610 65 20 69 73 20 64 69 73 63 6f 75 72 61 67 65 64  e is discouraged
26620 2e 0a 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32  ..** ^In the "v2
26630 22 20 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68  " interfaces, th
26640 65 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  e prepared state
26650 6d 65 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20  ment.** that is 
26660 72 65 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73  returned (the [s
26670 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
26680 65 63 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20  ect) contains a 
26690 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f  copy of the.** o
266a0 72 69 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74  riginal SQL text
266b0 2e 20 54 68 69 73 20 63 61 75 73 65 73 20 74 68  . This causes th
266c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
266d0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a  )] interface to.
266e0 2a 2a 20 62 65 68 61 76 65 20 64 69 66 66 65 72  ** behave differ
266f0 65 6e 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77  ently in three w
26700 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a  ays:.**.** <ol>.
26710 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
26720 68 65 20 64 61 74 61 62 61 73 65 20 73 63 68 65  he database sche
26730 6d 61 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74  ma changes, inst
26740 65 61 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67  ead of returning
26750 20 5b 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d   [SQLITE_SCHEMA]
26760 20 61 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73   as it.** always
26770 20 75 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71   used to do, [sq
26780 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69  lite3_step()] wi
26790 6c 6c 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ll automatically
267a0 20 72 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53   recompile the S
267b0 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
267c0 61 6e 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69  and try to run i
267d0 74 20 61 67 61 69 6e 2e 20 41 73 20 6d 61 6e 79  t again. As many
267e0 20 61 73 20 5b 53 51 4c 49 54 45 5f 4d 41 58 5f   as [SQLITE_MAX_
267f0 53 43 48 45 4d 41 5f 52 45 54 52 59 5d 0a 2a 2a  SCHEMA_RETRY].**
26800 20 72 65 74 72 69 65 73 20 77 69 6c 6c 20 6f 63   retries will oc
26810 63 75 72 20 62 65 66 6f 72 65 20 73 71 6c 69 74  cur before sqlit
26820 65 33 5f 73 74 65 70 28 29 20 67 69 76 65 73 20  e3_step() gives 
26830 75 70 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61  up and returns a
26840 6e 20 65 72 72 6f 72 2e 0a 2a 2a 20 3c 2f 6c 69  n error..** </li
26850 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20  >.**.** <li>.** 
26860 5e 57 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f  ^When an error o
26870 63 63 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f  ccurs, [sqlite3_
26880 73 74 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74  step()] will ret
26890 75 72 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64  urn one of the d
268a0 65 74 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f  etailed.** [erro
268b0 72 20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74  r codes] or [ext
268c0 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65  ended error code
268d0 73 5d 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79  s].  ^The legacy
268e0 20 62 65 68 61 76 69 6f 72 20 77 61 73 20 74 68   behavior was th
268f0 61 74 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  at.** [sqlite3_s
26900 74 65 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c  tep()] would onl
26910 79 20 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72  y return a gener
26920 69 63 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ic [SQLITE_ERROR
26930 5d 20 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a  ] result code.**
26940 20 61 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61   and the applica
26950 74 69 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20  tion would have 
26960 74 6f 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64  to make a second
26970 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
26980 33 5f 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e  3_reset()].** in
26990 20 6f 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74   order to find t
269a0 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61  he underlying ca
269b0 75 73 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c  use of the probl
269c0 65 6d 2e 20 57 69 74 68 20 74 68 65 20 22 76 32  em. With the "v2
269d0 22 20 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74  " prepare.** int
269e0 65 72 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64  erfaces, the und
269f0 65 72 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66  erlying reason f
26a00 6f 72 20 74 68 65 20 65 72 72 6f 72 20 69 73 20  or the error is 
26a10 72 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61  returned immedia
26a20 74 65 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a  tely..** </li>.*
26a30 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66  *.** <li>.** ^If
26a40 20 74 68 65 20 73 70 65 63 69 66 69 63 20 76 61   the specific va
26a50 6c 75 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61  lue bound to [pa
26a60 72 61 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70  rameter | host p
26a70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65  arameter] in the
26a80 20 0a 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73   .** WHERE claus
26a90 65 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  e might influenc
26aa0 65 20 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20  e the choice of 
26ab0 71 75 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61  query plan for a
26ac0 20 73 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74   statement,.** t
26ad0 68 65 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e  hen the statemen
26ae0 74 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61  t will be automa
26af0 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
26b00 65 64 2c 20 61 73 20 69 66 20 74 68 65 72 65 20  ed, as if there 
26b10 68 61 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73  had been .** a s
26b20 63 68 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e  chema change, on
26b30 20 74 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c   the first  [sql
26b40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c  ite3_step()] cal
26b50 6c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20  l following any 
26b60 63 68 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65  change.** to the
26b70 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74   [sqlite3_bind_t
26b80 65 78 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  ext | bindings] 
26b90 6f 66 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74  of that [paramet
26ba0 65 72 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70  er]. .** ^The sp
26bb0 65 63 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20  ecific value of 
26bc0 57 48 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61  WHERE-clause [pa
26bd0 72 61 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69  rameter] might i
26be0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a  nfluence the .**
26bf0 20 63 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79   choice of query
26c00 20 70 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72   plan if the par
26c10 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6c 65  ameter is the le
26c20 66 74 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20  ft-hand side of 
26c30 61 20 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b  a [LIKE].** or [
26c40 47 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f  GLOB] operator o
26c50 72 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  r if the paramet
26c60 65 72 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74  er is compared t
26c70 6f 20 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c  o an indexed col
26c80 75 6d 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b  umn.** and the [
26c90 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54  SQLITE_ENABLE_ST
26ca0 41 54 33 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  AT3] compile-tim
26cb0 65 20 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62  e option is enab
26cc0 6c 65 64 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a  led..** </li>.**
26cd0 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71   </ol>.*/.int sq
26ce0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20  lite3_prepare(. 
26cf0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
26d00 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61           /* Data
26d10 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  base handle */. 
26d20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71   const char *zSq
26d30 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20  l,       /* SQL 
26d40 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38  statement, UTF-8
26d50 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e   encoded */.  in
26d60 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20  t nByte,        
26d70 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d        /* Maximum
26d80 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20   length of zSql 
26d90 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73  in bytes. */.  s
26da0 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70  qlite3_stmt **pp
26db0 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53  Stmt,  /* OUT: S
26dc0 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20  tatement handle 
26dd0 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
26de0 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20  **pzTail     /* 
26df0 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20  OUT: Pointer to 
26e00 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f  unused portion o
26e10 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74  f zSql */.);.int
26e20 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
26e30 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  _v2(.  sqlite3 *
26e40 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
26e50 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
26e60 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
26e70 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
26e80 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
26e90 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
26ea0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
26eb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
26ec0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
26ed0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
26ee0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
26ef0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
26f00 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
26f10 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
26f20 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
26f30 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
26f40 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
26f50 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
26f60 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
26f70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69  repare16(.  sqli
26f80 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
26f90 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
26fa0 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
26fb0 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20  t void *zSql,   
26fc0 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65      /* SQL state
26fd0 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63  ment, UTF-16 enc
26fe0 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
26ff0 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
27000 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
27010 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
27020 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
27030 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
27040 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
27050 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
27060 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a   const void **pz
27070 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
27080 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
27090 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
270a0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
270b0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
270c0 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
270d0 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  ,            /* 
270e0 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20  Database handle 
270f0 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20  */.  const void 
27100 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20  *zSql,       /* 
27110 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55  SQL statement, U
27120 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f  TF-16 encoded */
27130 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
27140 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
27150 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
27160 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
27170 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
27180 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
27190 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
271a0 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
271b0 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20  void **pzTail   
271c0 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
271d0 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
271e0 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
271f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
27200 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74  F: Retrieving St
27210 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a  atement SQL.**.*
27220 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
27230 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
27240 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65   retrieve a save
27250 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72  d copy of the or
27260 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65  iginal.** SQL te
27270 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74  xt used to creat
27280 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  e a [prepared st
27290 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74  atement] if that
272a0 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a   statement was.*
272b0 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67  * compiled using
272c0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
272d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
272e0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
272f0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63  re16_v2()]..*/.c
27300 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27310 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73  e3_sql(sqlite3_s
27320 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
27330 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65  .** CAPI3REF: De
27340 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51  termine If An SQ
27350 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74  L Statement Writ
27360 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a  es The Database.
27370 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27380 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
27390 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  (X) interface re
273a0 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d  turns true (non-
273b0 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20  zero) if.** and 
273c0 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65  only if the [pre
273d0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
273e0 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65   X makes no dire
273f0 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a  ct changes to.**
27400 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
27410 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
27420 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68  e..**.** Note th
27430 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  at [application-
27440 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
27450 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69  tions] or.** [vi
27460 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69  rtual tables] mi
27470 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64  ght change the d
27480 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74  atabase indirect
27490 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66  ly as a side eff
274a0 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20  ect.  .** ^(For 
274b0 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61  example, if an a
274c0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
274d0 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65  es a function "e
274e0 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20  val()" that .** 
274f0 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65  calls [sqlite3_e
27500 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65  xec()], then the
27510 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73   following SQL s
27520 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a  tatement would.*
27530 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74  * change the dat
27540 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75  abase file throu
27550 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a  gh side-effects:
27560 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
27570 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53  te><pre>.**    S
27580 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45  ELECT eval('DELE
27590 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f  TE FROM t1') FRO
275a0 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  M t2;.** </pre><
275b0 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
275c0 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74  ** But because t
275d0 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  he [SELECT] stat
275e0 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63  ement does not c
275f0 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61  hange the databa
27600 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63  se file.** direc
27610 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  tly, sqlite3_stm
27620 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75  t_readonly() wou
27630 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20  ld still return 
27640 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54  true.)^.**.** ^T
27650 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72  ransaction contr
27660 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75  ol statements su
27670 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b  ch as [BEGIN], [
27680 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41  COMMIT], [ROLLBA
27690 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49  CK],.** [SAVEPOI
276a0 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53  NT], and [RELEAS
276b0 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33  E] cause sqlite3
276c0 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29  _stmt_readonly()
276d0 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c   to return true,
276e0 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74  .** since the st
276f0 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c  atements themsel
27700 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61  ves do not actua
27710 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64  lly modify the d
27720 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72  atabase but.** r
27730 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72  ather they contr
27740 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66  ol the timing of
27750 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74   when other stat
27760 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68  ements modify th
27770 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20  e .** database. 
27780 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61   ^The [ATTACH] a
27790 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74  nd [DETACH] stat
277a0 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73  ements also caus
277b0 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d  e.** sqlite3_stm
277c0 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20  t_readonly() to 
277d0 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63  return true sinc
277e0 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73  e, while those s
277f0 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61  tatements.** cha
27800 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72  nge the configur
27810 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62  ation of a datab
27820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20  ase connection, 
27830 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65  they do not make
27840 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20   .** changes to 
27850 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
27860 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
27870 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e  s on disk..*/.in
27880 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72  t sqlite3_stmt_r
27890 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f  eadonly(sqlite3_
278a0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
278b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
278c0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50 72  etermine If A Pr
278d0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
278e0 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74 0a   Has Been Reset.
278f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27900 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 20  e3_stmt_busy(S) 
27910 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
27920 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72 6f  s true (non-zero
27930 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72 65  ) if the.** [pre
27940 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
27950 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65 70   S has been step
27960 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e 63  ped at least onc
27970 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c  e using .** [sql
27980 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62 75  ite3_step(S)] bu
27990 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74 6f  t has not run to
279a0 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64 2f   completion and/
279b0 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20 62  or has not .** b
279c0 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67 20  een reset using 
279d0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53  [sqlite3_reset(S
279e0 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  )].  ^The sqlite
279f0 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a 2a  3_stmt_busy(S).*
27a00 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  * interface retu
27a10 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20 69  rns false if S i
27a20 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
27a30 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20 61  .  If S is not a
27a40 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65   .** NULL pointe
27a50 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20 70  r and is not a p
27a60 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c 69  ointer to a vali
27a70 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  d [prepared stat
27a80 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74  ement].** object
27a90 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76  , then the behav
27aa0 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ior is undefined
27ab0 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e   and probably un
27ac0 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a  desirable..**.**
27ad0 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   This interface 
27ae0 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20 63  can be used in c
27af0 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c 69  ombination [sqli
27b00 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29 5d  te3_next_stmt()]
27b10 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61 6c  .** to locate al
27b20 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  l prepared state
27b30 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65 64  ments associated
27b40 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73 65   with a database
27b50 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20   .** connection 
27b60 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65 64  that are in need
27b70 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74 2e   of being reset.
27b80 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75 73    This can be us
27b90 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d 70  ed,.** for examp
27ba0 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74 69  le, in diagnosti
27bb0 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73 65  c routines to se
27bc0 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72 65  arch for prepare
27bd0 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 73  d .** statements
27be0 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69 6e   that are holdin
27bf0 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  g a transaction 
27c00 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  open..*/.int sql
27c10 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 73  ite3_stmt_busy(s
27c20 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a  qlite3_stmt*);..
27c30 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
27c40 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65  Dynamically Type
27c50 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a  d Value Object.*
27c60 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f  * KEYWORDS: {pro
27c70 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
27c80 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74  alue} {unprotect
27c90 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
27ca0 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75  }.**.** SQLite u
27cb0 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ses the sqlite3_
27cc0 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20  value object to 
27cd0 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61  represent all va
27ce0 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e  lues.** that can
27cf0 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20   be stored in a 
27d00 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20  database table. 
27d10 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61  SQLite uses dyna
27d20 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f  mic typing.** fo
27d30 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74 20  r the values it 
27d40 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73  stores.  ^Values
27d50 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74   stored in sqlit
27d60 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
27d70 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67  .** can be integ
27d80 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f  ers, floating po
27d90 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69  int values, stri
27da0 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e  ngs, BLOBs, or N
27db0 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71  ULL..**.** An sq
27dc0 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
27dd0 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65 72  ct may be either
27de0 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20   "protected" or 
27df0 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a  "unprotected"..*
27e00 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65  * Some interface
27e10 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f 74  s require a prot
27e20 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27e30 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65  lue.  Other inte
27e40 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61  rfaces.** will a
27e50 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20 70  ccept either a p
27e60 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75  rotected or an u
27e70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
27e80 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65  e3_value..** Eve
27e90 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68 61  ry interface tha
27ea0 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74 65  t accepts sqlite
27eb0 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74  3_value argument
27ec0 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77  s specifies.** w
27ed0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74  hether or not it
27ee0 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f 74   requires a prot
27ef0 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
27f00 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  lue..**.** The t
27f10 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22  erms "protected"
27f20 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65   and "unprotecte
27f30 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65 74  d" refer to whet
27f40 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20  her or not.** a 
27f50 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20  mutex is held.  
27f60 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65  An internal mute
27f70 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20  x is held for a 
27f80 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
27f90 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27fa0 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69  t but no mutex i
27fb0 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e  s held for an un
27fc0 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c  protected.** sql
27fd0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
27fe0 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69 73  t.  If SQLite is
27ff0 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20   compiled to be 
28000 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a  single-threaded.
28010 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45  ** (with [SQLITE
28020 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61  _THREADSAFE=0] a
28030 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  nd with [sqlite3
28040 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20 72  _threadsafe()] r
28050 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f  eturning 0).** o
28060 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 72  r if SQLite is r
28070 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64  un in one of red
28080 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73  uced mutex modes
28090 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e   .** [SQLITE_CON
280a0 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44  FIG_SINGLETHREAD
280b0 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  ] or [SQLITE_CON
280c0 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d  FIG_MULTITHREAD]
280d0 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69  .** then there i
280e0 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e  s no distinction
280f0 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74   between protect
28100 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74  ed and unprotect
28110 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61  ed.** sqlite3_va
28120 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20  lue objects and 
28130 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65 64  they can be used
28140 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79   interchangeably
28150 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66  .  However,.** f
28160 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20  or maximum code 
28170 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20 69  portability it i
28180 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68  s recommended th
28190 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a  at applications.
281a0 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68  ** still make th
281b0 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65  e distinction be
281c0 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20  tween protected 
281d0 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a  and unprotected.
281e0 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ** sqlite3_value
281f0 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68   objects even wh
28200 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20  en not strictly 
28210 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
28220 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  ^The sqlite3_val
28230 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20  ue objects that 
28240 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70 61  are passed as pa
28250 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68  rameters into th
28260 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74  e.** implementat
28270 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74  ion of [applicat
28280 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20  ion-defined SQL 
28290 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70  functions] are p
282a0 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68  rotected..** ^Th
282b0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  e sqlite3_value 
282c0 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20  object returned 
282d0 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  by.** [sqlite3_c
282e0 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69  olumn_value()] i
282f0 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a  s unprotected..*
28300 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71  * Unprotected sq
28310 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
28320 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  cts may only be 
28330 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71  used with.** [sq
28340 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
28350 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
28360 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d  e3_bind_value()]
28370 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65  ..** The [sqlite
28380 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73  3_value_blob | s
28390 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
283a0 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a  e()] family of.*
283b0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65 71  * interfaces req
283c0 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20 73  uire protected s
283d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
283e0 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  ects..*/.typedef
283f0 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69   struct Mem sqli
28400 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a  te3_value;../*.*
28410 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20  * CAPI3REF: SQL 
28420 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74  Function Context
28430 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
28440 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69  e context in whi
28450 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69  ch an SQL functi
28460 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20 73  on executes is s
28470 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73  tored in an.** s
28480 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f  qlite3_context o
28490 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74  bject.  ^A point
284a0 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33  er to an sqlite3
284b0 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a  _context object.
284c0 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69 72  ** is always fir
284d0 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  st parameter to 
284e0 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  [application-def
284f0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
28500 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  ns]..** The appl
28510 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
28520 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70  SQL function imp
28530 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c  lementation will
28540 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f   pass this.** po
28550 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e  inter through in
28560 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  to calls to [sql
28570 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20  ite3_result_int 
28580 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  | sqlite3_result
28590 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ()],.** [sqlite3
285a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
285b0 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  xt()], [sqlite3_
285c0 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a  user_data()],.**
285d0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78   [sqlite3_contex
285e0 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20  t_db_handle()], 
285f0 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78  [sqlite3_get_aux
28600 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f  data()],.** and/
28610 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  or [sqlite3_set_
28620 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74  auxdata()]..*/.t
28630 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
28640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71  lite3_context sq
28650 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a  lite3_context;..
28660 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
28670 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54  Binding Values T
28680 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  o Prepared State
28690 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  ments.** KEYWORD
286a0 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74  S: {host paramet
286b0 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  er} {host parame
286c0 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61  ters} {host para
286d0 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b  meter name}.** K
286e0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61  EYWORDS: {SQL pa
286f0 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61  rameter} {SQL pa
28700 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d  rameters} {param
28710 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a  eter binding}.**
28720 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c  .** ^(In the SQL
28730 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20   statement text 
28740 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65  input to [sqlite
28750 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
28760 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74 73  and its variants
28770 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61  ,.** literals ma
28780 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62 79  y be replaced by
28790 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74   a [parameter] t
287a0 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20  hat matches one 
287b0 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20  of following.** 
287c0 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a  templates:.**.**
287d0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f   <ul>.** <li>  ?
287e0 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a  .** <li>  ?NNN.*
287f0 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20  * <li>  :VVV.** 
28800 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c  <li>  @VVV.** <l
28810 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c  i>  $VVV.** </ul
28820 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74  >.**.** In the t
28830 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20  emplates above, 
28840 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61  NNN represents a
28850 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61  n integer litera
28860 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65  l,.** and VVV re
28870 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68  presents an alph
28880 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66  anumeric identif
28890 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c  ier.)^  ^The val
288a0 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ues of these.** 
288b0 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f  parameters (also
288c0 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61   called "host pa
288d0 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f  rameter names" o
288e0 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72  r "SQL parameter
288f0 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65  s").** can be se
28900 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  t using the sqli
28910 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
28920 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65  tines defined he
28930 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  re..**.** ^The f
28940 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
28950 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
28960 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69  d_*() routines i
28970 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f  s always.** a po
28980 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71  inter to the [sq
28990 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65  lite3_stmt] obje
289a0 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d  ct returned from
289b0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
289c0 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74  pare_v2()] or it
289d0 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a  s variants..**.*
289e0 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  * ^The second ar
289f0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e  gument is the in
28a00 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70  dex of the SQL p
28a10 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73  arameter to be s
28a20 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74  et..** ^The left
28a30 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74  most SQL paramet
28a40 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20  er has an index 
28a50 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65  of 1.  ^When the
28a60 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53   same named.** S
28a70 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  QL parameter is 
28a80 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  used more than o
28a90 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20  nce, second and 
28aa0 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63  subsequent.** oc
28ab0 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20 74  currences have t
28ac0 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73  he same index as
28ad0 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75 72   the first occur
28ae0 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69  rence..** ^The i
28af0 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70  ndex for named p
28b00 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65  arameters can be
28b10 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67   looked up using
28b20 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
28b30 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
28b40 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66 20  index()] API if 
28b50 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69  desired.  ^The i
28b60 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e  ndex.** for "?NN
28b70 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  N" parameters is
28b80 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e   the value of NN
28b90 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76  N..** ^The NNN v
28ba0 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65 74  alue must be bet
28bb0 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b  ween 1 and the [
28bc0 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d  sqlite3_limit()]
28bd0 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53  .** parameter [S
28be0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
28bf0 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65  ABLE_NUMBER] (de
28c00 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39  fault value: 999
28c10 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  )..**.** ^The th
28c20 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
28c30 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e  the value to bin
28c40 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74  d to the paramet
28c50 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74  er..** ^If the t
28c60 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
28c70 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  o sqlite3_bind_t
28c80 65 78 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33  ext() or sqlite3
28c90 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 0a 2a  _bind_text16().*
28ca0 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
28cb0 64 5f 62 6c 6f 62 28 29 20 69 73 20 61 20 4e 55  d_blob() is a NU
28cc0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
28cd0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
28ce0 65 74 65 72 0a 2a 2a 20 69 73 20 69 67 6e 6f 72  eter.** is ignor
28cf0 65 64 20 61 6e 64 20 74 68 65 20 65 6e 64 20 72  ed and the end r
28d00 65 73 75 6c 74 20 69 73 20 74 68 65 20 73 61 6d  esult is the sam
28d10 65 20 61 73 20 73 71 6c 69 74 65 33 5f 62 69 6e  e as sqlite3_bin
28d20 64 5f 6e 75 6c 6c 28 29 2e 0a 2a 2a 0a 2a 2a 20  d_null()..**.** 
28d30 5e 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69  ^(In those routi
28d40 6e 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20  nes that have a 
28d50 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c  fourth argument,
28d60 20 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68   its value is th
28d70 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62  e.** number of b
28d80 79 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61  ytes in the para
28d90 6d 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c  meter.  To be cl
28da0 65 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69  ear: the value i
28db0 73 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20  s the.** number 
28dc0 6f 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20  of <u>bytes</u> 
28dd0 69 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f  in the value, no
28de0 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  t the number of 
28df0 63 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a  characters.)^.**
28e00 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20   ^If the fourth 
28e10 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
28e20 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29  ite3_bind_text()
28e30 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
28e40 5f 74 65 78 74 31 36 28 29 0a 2a 2a 20 69 73 20  _text16().** is 
28e50 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 74  negative, then t
28e60 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
28e70 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
28e80 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
28e90 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
28ea0 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
28eb0 72 2e 0a 2a 2a 20 49 66 20 74 68 65 20 66 6f 75  r..** If the fou
28ec0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
28ed0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
28ee0 6f 62 28 29 20 69 73 20 6e 65 67 61 74 69 76 65  ob() is negative
28ef0 2c 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 62 65  , then.** the be
28f00 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
28f10 6e 65 64 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f 6e  ned..** If a non
28f20 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74 68  -negative fourth
28f30 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70 72   parameter is pr
28f40 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74 65  ovided to sqlite
28f50 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a 2a  3_bind_text().**
28f60 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   or sqlite3_bind
28f70 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20 74  _text16() then t
28f80 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d 75  hat parameter mu
28f90 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f  st be the byte o
28fa0 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20 74  ffset.** where t
28fb0 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 6f  he NUL terminato
28fc0 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61 73  r would occur as
28fd0 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69 6e  suming the strin
28fe0 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74 65  g were NUL.** te
28ff0 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61 6e  rminated.  If an
29000 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72 73  y NUL characters
29010 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20 6f   occur at byte o
29020 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61 6e  ffsets less than
29030 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20 6f   .** the value o
29040 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  f the fourth par
29050 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65 20  ameter then the 
29060 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67  resulting string
29070 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20 63   value will.** c
29080 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64 20  ontain embedded 
29090 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75 6c  NULs.  The resul
290a0 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
290b0 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69 6e   involving strin
290c0 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65 64  gs.** with embed
290d0 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
290e0 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  fined..**.** ^Th
290f0 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74  e fifth argument
29100 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e 64   to sqlite3_bind
29110 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33  _blob(), sqlite3
29120 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61 6e  _bind_text(), an
29130 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  d.** sqlite3_bin
29140 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61 20  d_text16() is a 
29150 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64 20  destructor used 
29160 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68  to dispose of th
29170 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74 72  e BLOB or.** str
29180 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74 65  ing after SQLite
29190 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77 69   has finished wi
291a0 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65 73  th it.  ^The des
291b0 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c 65  tructor is calle
291c0 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65 20  d.** to dispose 
291d0 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20 73  of the BLOB or s
291e0 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74 68  tring even if th
291f0 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  e call to sqlite
29200 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a  3_bind_blob(),.*
29210 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74  * sqlite3_bind_t
29220 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74 65  ext(), or sqlite
29230 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20  3_bind_text16() 
29240 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66 20  fails.  .** ^If 
29250 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65  the fifth argume
29260 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70 65  nt is.** the spe
29270 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c 49  cial value [SQLI
29280 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65 6e  TE_STATIC], then
29290 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73 20   SQLite assumes 
292a0 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66 6f  that the.** info
292b0 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73 74  rmation is in st
292c0 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64 20  atic, unmanaged 
292d0 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20 6e  space and does n
292e0 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66 72  ot need to be fr
292f0 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  eed..** ^If the 
29300 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 68  fifth argument h
29310 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53 51  as the value [SQ
29320 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d 2c  LITE_TRANSIENT],
29330 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
29340 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70 72  makes its own pr
29350 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
29360 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74 65  e data immediate
29370 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74 68  ly, before.** th
29380 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
29390 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  () routine retur
293a0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ns..**.** ^The s
293b0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f  qlite3_bind_zero
293c0 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20 62  blob() routine b
293d0 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20 6c  inds a BLOB of l
293e0 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a 20  ength N that.** 
293f0 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20 7a  is filled with z
29400 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f 62  eroes.  ^A zerob
29410 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65 64  lob uses a fixed
29420 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f 72   amount of memor
29430 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69 6e  y.** (just an in
29440 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69 74  teger to hold it
29450 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69 74  s size) while it
29460 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65 73   is being proces
29470 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62  sed..** Zeroblob
29480 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20 74  s are intended t
29490 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63 65  o serve as place
294a0 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f 42  holders for BLOB
294b0 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65  s whose.** conte
294c0 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69 74  nt is later writ
294d0 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ten using.** [sq
294e0 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20  lite3_blob_open 
294f0 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42 4c  | incremental BL
29500 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65 73  OB I/O] routines
29510 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76 65  ..** ^A negative
29520 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20 7a   value for the z
29530 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73 20  eroblob results 
29540 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68  in a zero-length
29550 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66   BLOB..**.** ^If
29560 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c 69   any of the sqli
29570 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75  te3_bind_*() rou
29580 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
29590 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69   with a NULL poi
295a0 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65 20  nter.** for the 
295b0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
295c0 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20 70  ent] or with a p
295d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
295e0 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20 5b  t for which.** [
295f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
29600 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  has been called 
29610 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74 68  more recently th
29620 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  an [sqlite3_rese
29630 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  t()],.** then th
29640 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74 75  e call will retu
29650 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  rn [SQLITE_MISUS
29660 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c 69  E].  If any sqli
29670 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20 72  te3_bind_().** r
29680 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65 64  outine is passed
29690 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
296a0 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61 73  tement] that has
296b0 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2c   been finalized,
296c0 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 69   the.** result i
296d0 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 20  s undefined and 
296e0 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75 6c  probably harmful
296f0 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67  ..**.** ^Binding
29700 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72 65  s are not cleare
29710 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65  d by the [sqlite
29720 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74 69  3_reset()] routi
29730 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20  ne..** ^Unbound 
29740 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 69  parameters are i
29750 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e 55  nterpreted as NU
29760 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  LL..**.** ^The s
29770 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72 6f  qlite3_bind_* ro
29780 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b 53  utines return [S
29790 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
297a0 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65  cess or an.** [e
297b0 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61 6e  rror code] if an
297c0 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f 6e  ything goes wron
297d0 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 52  g..** ^[SQLITE_R
297e0 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e 65  ANGE] is returne
297f0 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65 74  d if the paramet
29800 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20 6f  er.** index is o
29810 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e 5b  ut of range.  ^[
29820 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73  SQLITE_NOMEM] is
29830 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61 6c   returned if mal
29840 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a  loc() fails..**.
29850 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29860 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
29870 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a  eter_count()],.*
29880 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
29890 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29  parameter_name()
298a0 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
298b0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
298c0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  ndex()]..*/.int 
298d0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
298e0 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
298f0 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64   int, const void
29900 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28 2a  *, int n, void(*
29910 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20 73  )(void*));.int s
29920 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75 62  qlite3_bind_doub
29930 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  le(sqlite3_stmt*
29940 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b 0a  , int, double);.
29950 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
29960 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  _int(sqlite3_stm
29970 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a 69  t*, int, int);.i
29980 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
29990 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74  int64(sqlite3_st
299a0 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65  mt*, int, sqlite
299b0 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73 71  3_int64);.int sq
299c0 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28  lite3_bind_null(
299d0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
299e0 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  nt);.int sqlite3
299f0 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69 74  _bind_text(sqlit
29a00 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
29a10 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 20  onst char*, int 
29a20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  n, void(*)(void*
29a30 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
29a40 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c 69  bind_text16(sqli
29a50 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
29a60 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74  const void*, int
29a70 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29  , void(*)(void*)
29a80 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
29a90 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74 65  ind_value(sqlite
29aa0 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f  3_stmt*, int, co
29ab0 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  nst sqlite3_valu
29ac0 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  e*);.int sqlite3
29ad0 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28 73  _bind_zeroblob(s
29ae0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29af0 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  t, int n);../*.*
29b00 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d 62  * CAPI3REF: Numb
29b10 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d 65  er Of SQL Parame
29b20 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  ters.**.** ^This
29b30 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
29b40 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68 65  used to find the
29b50 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c 20   number of [SQL 
29b60 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20 69  parameters].** i
29b70 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
29b80 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20 70  atement].  SQL p
29b90 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74 6f  arameters are to
29ba0 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20 66  kens of the.** f
29bb0 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c  orm "?", "?NNN",
29bc0 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22 2c   ":AAA", "$AAA",
29bd0 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74 20   or "@AAA" that 
29be0 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61 63  serve as.** plac
29bf0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61 6c  eholders for val
29c00 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73 71  ues that are [sq
29c10 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
29c20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74  | bound].** to t
29c30 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61 74  he parameters at
29c40 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a 2a   a later time..*
29c50 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75 74  *.** ^(This rout
29c60 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65 74  ine actually ret
29c70 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20 6f  urns the index o
29c80 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28 72  f the largest (r
29c90 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61 72  ightmost).** par
29ca0 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c 20  ameter. For all 
29cb0 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e 4e  forms except ?NN
29cc0 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f 72  N, this will cor
29cd0 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a 2a  respond to the.*
29ce0 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69 71  * number of uniq
29cf0 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20 20  ue parameters.  
29d00 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f 66  If parameters of
29d10 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61   the ?NNN form a
29d20 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65 72  re used,.** ther
29d30 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69 6e  e may be gaps in
29d40 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a   the list.)^.**.
29d50 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71  ** See also: [sq
29d60 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29d70 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c  sqlite3_bind()],
29d80 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  .** [sqlite3_bin
29d90 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65  d_parameter_name
29da0 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
29db0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
29dc0 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
29dd0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
29de0 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e  d_parameter_coun
29df0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29  t(sqlite3_stmt*)
29e00 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
29e10 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f 73  F: Name Of A Hos
29e20 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a  t Parameter.**.*
29e30 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 62  * ^The sqlite3_b
29e40 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
29e50 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(P,N) interfac
29e60 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65  e returns.** the
29e70 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d 74   name of the N-t
29e80 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72  h [SQL parameter
29e90 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61 72  ] in the [prepar
29ea0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50 2e  ed statement] P.
29eb0 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d 65  .** ^(SQL parame
29ec0 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72 6d  ters of the form
29ed0 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41 41   "?NNN" or ":AAA
29ee0 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20 22  " or "@AAA" or "
29ef0 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61 20  $AAA".** have a 
29f00 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74 68  name which is th
29f10 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22 20  e string "?NNN" 
29f20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40 41  or ":AAA" or "@A
29f30 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a 2a  AA" or "$AAA".**
29f40 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a   respectively..*
29f50 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73  * In other words
29f60 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22 3a  , the initial ":
29f70 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22 20  " or "$" or "@" 
29f80 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e 63  or "?".** is inc
29f90 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f 66  luded as part of
29fa0 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20   the name.)^.** 
29fb0 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74  ^Parameters of t
29fc0 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74 68  he form "?" with
29fd0 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67 20  out a following 
29fe0 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f 20  integer have no 
29ff0 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65 20  name.** and are 
2a000 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20 22  referred to as "
2a010 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61 6e  nameless" or "an
2a020 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74 65  onymous paramete
2a030 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rs"..**.** ^The 
2a040 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61 6d  first host param
2a050 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65  eter has an inde
2a060 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a 2a  x of 1, not 0..*
2a070 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61 6c  *.** ^If the val
2a080 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20 72  ue N is out of r
2a090 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20 4e  ange or if the N
2a0a0 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  -th parameter is
2a0b0 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74 68  .** nameless, th
2a0c0 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75 72  en NULL is retur
2a0d0 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75 72  ned.  ^The retur
2a0e0 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  ned string is.**
2a0f0 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d 38   always in UTF-8
2a100 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20 69   encoding even i
2a110 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72 61  f the named para
2a120 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72 69  meter was.** ori
2a130 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69 65  ginally specifie
2a140 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20 5b  d as UTF-16 in [
2a150 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a160 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  6()] or.** [sqli
2a170 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
2a180 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ()]..**.** See a
2a190 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62 69  lso: [sqlite3_bi
2a1a0 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33 5f  nd_blob|sqlite3_
2a1b0 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c  bind()],.** [sql
2a1c0 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
2a1d0 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61 6e  ter_count()], an
2a1e0 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  d.** [sqlite3_bi
2a1f0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64  nd_parameter_ind
2a200 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  ex()]..*/.const 
2a210 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62 69  char *sqlite3_bi
2a220 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
2a230 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
2a240 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   int);../*.** CA
2a250 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f 66  PI3REF: Index Of
2a260 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69 74   A Parameter Wit
2a270 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a 2a  h A Given Name.*
2a280 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68 65  *.** ^Return the
2a290 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51 4c   index of an SQL
2a2a0 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65 6e   parameter given
2a2b0 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68 65   its name.  ^The
2a2c0 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65 20  .** index value 
2a2d0 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69 74  returned is suit
2a2e0 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73 20  able for use as 
2a2f0 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70 61  the second.** pa
2a300 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2a310 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
2a320 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20 20  lite3_bind()].  
2a330 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72 65  ^A zero.** is re
2a340 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61 74  turned if no mat
2a350 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20  ching parameter 
2a360 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65 20  is found.  ^The 
2a370 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61 6d  parameter.** nam
2a380 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e 20  e must be given 
2a390 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69 66  in UTF-8 even if
2a3a0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73 74   the original st
2a3b0 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20 70  atement.** was p
2a3c0 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54 46  repared from UTF
2a3d0 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20 5b  -16 text using [
2a3e0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
2a3f0 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53  6_v2()]..**.** S
2a400 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
2a410 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
2a420 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
2a430 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
2a440 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
2a450 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65  , and.** [sqlite
2a460 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
2a470 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e  _index()]..*/.in
2a480 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70  t sqlite3_bind_p
2a490 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 73  arameter_index(s
2a4a0 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63 6f  qlite3_stmt*, co
2a4b0 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29  nst char *zName)
2a4c0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2a4d0 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69 6e  F: Reset All Bin
2a4e0 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70 61  dings On A Prepa
2a4f0 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a  red Statement.**
2a500 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74 6f  .** ^Contrary to
2a510 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20 6f   the intuition o
2a520 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65 33  f many, [sqlite3
2a530 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20 6e  _reset()] does n
2a540 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65 20  ot reset.** the 
2a550 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2a560 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f  ob | bindings] o
2a570 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  n a [prepared st
2a580 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55 73  atement]..** ^Us
2a590 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 74  e this routine t
2a5a0 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73 74  o reset all host
2a5b0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 4e   parameters to N
2a5c0 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ULL..*/.int sqli
2a5d0 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2a5e0 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  gs(sqlite3_stmt*
2a5f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2a600 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43 6f  EF: Number Of Co
2a610 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75 6c  lumns In A Resul
2a620 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65 74  t Set.**.** ^Ret
2a630 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  urn the number o
2a640 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2a650 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74 75   result set retu
2a660 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  rned by the.** [
2a670 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a680 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74 69  nt]. ^This routi
2a690 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66 20  ne returns 0 if 
2a6a0 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c 0a  pStmt is an SQL.
2a6b0 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61  ** statement tha
2a6c0 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75 72  t does not retur
2a6d0 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61 6d  n data (for exam
2a6e0 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d 29  ple an [UPDATE])
2a6f0 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
2a700 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  : [sqlite3_data_
2a710 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20  count()].*/.int 
2a720 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63  sqlite3_column_c
2a730 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
2a740 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2a750 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 75  * CAPI3REF: Colu
2a760 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52 65  mn Names In A Re
2a770 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
2a780 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
2a790 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 61  eturn the name a
2a7a0 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61 72  ssigned to a par
2a7b0 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a 2a  ticular column.*
2a7c0 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20  * in the result 
2a7d0 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43 54  set of a [SELECT
2a7e0 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 54  ] statement.  ^T
2a7f0 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2a800 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74 65  n_name().** inte
2a810 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20  rface returns a 
2a820 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65 72  pointer to a zer
2a830 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
2a840 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e 64  -8 string.** and
2a850 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a860 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e 73  name16() returns
2a870 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
2a880 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a  zero-terminated.
2a890 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67  ** UTF-16 string
2a8a0 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70 61  .  ^The first pa
2a8b0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b  rameter is the [
2a8c0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2a8d0 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70 6c  nt].** that impl
2a8e0 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c 45  ements the [SELE
2a8f0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 5e  CT] statement. ^
2a900 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
2a910 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 63  eter is the.** c
2a920 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20 5e  olumn number.  ^
2a930 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f 6c  The leftmost col
2a940 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30 2e  umn is number 0.
2a950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75  .**.** ^The retu
2a960 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69 6e  rned string poin
2a970 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e 74  ter is valid unt
2a980 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b 70  il either the [p
2a990 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2a9a0 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f 79  t].** is destroy
2a9b0 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66  ed by [sqlite3_f
2a9c0 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75 6e  inalize()] or un
2a9d0 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65 6e  til the statemen
2a9e0 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61 6c  t is automatical
2a9f0 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65 64  ly.** reprepared
2aa00 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63 61   by the first ca
2aa10 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ll to [sqlite3_s
2aa20 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61 72  tep()] for a par
2aa30 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20 6f  ticular run.** o
2aa40 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78 74  r until the next
2aa50 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69   call to.** sqli
2aa60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
2aa70 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ) or sqlite3_col
2aa80 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e 20  umn_name16() on 
2aa90 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e 2e  the same column.
2aaa0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74  .**.** ^If sqlit
2aab0 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c  e3_malloc() fail
2aac0 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72 6f  s during the pro
2aad0 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68 65  cessing of eithe
2aae0 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66 6f  r routine.** (fo
2aaf0 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e 67  r example during
2ab00 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66 72   a conversion fr
2ab10 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46 2d  om UTF-8 to UTF-
2ab20 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e 55  16) then a.** NU
2ab30 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
2ab40 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2ab50 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65 73  he name of a res
2ab60 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74 68  ult column is th
2ab70 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 22  e value of the "
2ab80 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a 2a  AS" clause for.*
2ab90 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20 69  * that column, i
2aba0 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41 53  f there is an AS
2abb0 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68 65   clause.  If the
2abc0 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61 75  re is no AS clau
2abd0 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 6e  se.** then the n
2abe0 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75 6d  ame of the colum
2abf0 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65 64  n is unspecified
2ac00 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65 20   and may change 
2ac10 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c 65  from.** one rele
2ac20 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74 6f  ase of SQLite to
2ac30 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63 6f   the next..*/.co
2ac40 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
2ac50 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73 71  3_column_name(sq
2ac60 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2ac70 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20   N);.const void 
2ac80 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2ac90 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
2aca0 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a 2f  tmt*, int N);../
2acb0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
2acc0 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49 6e  ource Of Data In
2acd0 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74 0a   A Query Result.
2ace0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2acf0 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61 20  tines provide a 
2ad00 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d 69  means to determi
2ad10 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65 2c  ne the database,
2ad20 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20 74   table, and.** t
2ad30 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
2ad40 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20 6f   is the origin o
2ad50 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  f a particular r
2ad60 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e 0a  esult column in.
2ad70 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74  ** [SELECT] stat
2ad80 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6e  ement..** ^The n
2ad90 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61 62  ame of the datab
2ada0 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72 20  ase or table or 
2adb0 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72 65  column can be re
2adc0 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69 74  turned as.** eit
2add0 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20 55  her a UTF-8 or U
2ade0 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20 5e  TF-16 string.  ^
2adf0 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20 72  The _database_ r
2ae00 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a 2a  outines return.*
2ae10 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6e  * the database n
2ae20 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65 5f  ame, the _table_
2ae30 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
2ae40 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65 2c   the table name,
2ae50 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69 67   and.** the orig
2ae60 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  in_ routines ret
2ae70 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20 6e  urn the column n
2ae80 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ame..** ^The ret
2ae90 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 20  urned string is 
2aea0 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65 20  valid until the 
2aeb0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2aec0 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79 65  ent] is destroye
2aed0 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69  d.** using [sqli
2aee0 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20  te3_finalize()] 
2aef0 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61  or until the sta
2af00 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61  tement is automa
2af10 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65  tically.** repre
2af20 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69 72  pared by the fir
2af30 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  st call to [sqli
2af40 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20  te3_step()] for 
2af50 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e  a particular run
2af60 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65  .** or until the
2af70 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69 6f   same informatio
2af80 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a 2a  n is requested.*
2af90 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69 66  * again in a dif
2afa0 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67 2e  ferent encoding.
2afb0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65  .**.** ^The name
2afc0 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 74  s returned are t
2afd0 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d 61  he original un-a
2afe0 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66 20  liased names of 
2aff0 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 2c  the.** database,
2b000 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c 75   table, and colu
2b010 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  mn..**.** ^The f
2b020 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
2b030 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65   these interface
2b040 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65 64  s is a [prepared
2b050 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
2b060 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
2b070 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74   return informat
2b080 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e 74  ion about the Nt
2b090 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  h result column 
2b0a0 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 74  returned by.** t
2b0b0 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77 68  he statement, wh
2b0c0 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65 63  ere N is the sec
2b0d0 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72 67  ond function arg
2b0e0 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c  ument..** ^The l
2b0f0 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20  eft-most column 
2b100 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72 20  is column 0 for 
2b110 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
2b120 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e 74  **.** ^If the Nt
2b130 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e 65  h column returne
2b140 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d 65  d by the stateme
2b150 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73 73  nt is an express
2b160 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75 65  ion or.** subque
2b170 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  ry and is not a 
2b180 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74 68  column value, th
2b190 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  en all of these 
2b1a0 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e  functions return
2b1b0 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65 73  .** NULL.  ^Thes
2b1c0 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74 20  e routine might 
2b1d0 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c 4c  also return NULL
2b1e0 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c   if a memory all
2b1f0 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a 2a  ocation error.**
2b200 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65 72   occurs.  ^Other
2b210 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75 72  wise, they retur
2b220 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  n the name of th
2b230 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  e attached datab
2b240 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20 6f  ase, table,.** o
2b250 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71 75  r column that qu
2b260 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  ery result colum
2b270 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64 20  n was extracted 
2b280 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20  from..**.** ^As 
2b290 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20 53  with all other S
2b2a0 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f 73  QLite APIs, thos
2b2b0 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65 6e  e whose names en
2b2c0 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74 75  d with "16" retu
2b2d0 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e 63  rn.** UTF-16 enc
2b2e0 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e 64  oded strings and
2b2f0 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63 74   the other funct
2b300 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46 2d  ions return UTF-
2b310 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  8..**.** ^These 
2b320 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61 76  APIs are only av
2b330 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20 6c  ailable if the l
2b340 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70 69  ibrary was compi
2b350 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20  led with the.** 
2b360 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43  [SQLITE_ENABLE_C
2b370 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d 20  OLUMN_METADATA] 
2b380 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20 73  C-preprocessor s
2b390 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ymbol..**.** If 
2b3a0 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72 65  two or more thre
2b3b0 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72 20  ads call one or 
2b3c0 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72 6f  more of these ro
2b3d0 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20 74  utines against t
2b3e0 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70 61  he same.** prepa
2b3f0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  red statement an
2b400 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65 20  d column at the 
2b410 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74  same time then t
2b420 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a 2a  he results are.*
2b430 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a  * undefined..**.
2b440 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72  ** If two or mor
2b450 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20 6f  e threads call o
2b460 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b 73  ne or more.** [s
2b470 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 61  qlite3_column_da
2b480 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63 6f  tabase_name | co
2b490 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69 6e  lumn metadata in
2b4a0 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f 72  terfaces].** for
2b4b0 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70 61   the same [prepa
2b4c0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 61  red statement] a
2b4d0 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  nd result column
2b4e0 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65 20  .** at the same 
2b4f0 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72 65  time then the re
2b500 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2b510 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68  ned..*/.const ch
2b520 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2b530 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
2b540 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b550 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2b560 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b570 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36 28  database_name16(
2b580 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2b590 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  t);.const char *
2b5a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b5b0 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74 65  able_name(sqlite
2b5c0 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f  3_stmt*,int);.co
2b5d0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2b5e0 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f 6e  3_column_table_n
2b5f0 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73 74  ame16(sqlite3_st
2b600 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2b610 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
2b620 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65  lumn_origin_name
2b630 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
2b640 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  nt);.const void 
2b650 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2b660 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73 71  origin_name16(sq
2b670 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29  lite3_stmt*,int)
2b680 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2b690 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74 61  F: Declared Data
2b6a0 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79 20  type Of A Query 
2b6b0 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28 54  Result.**.** ^(T
2b6c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2b6d0 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  er is a [prepare
2b6e0 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
2b6f0 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d 65   If this stateme
2b700 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54 5d  nt is a [SELECT]
2b710 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74   statement and t
2b720 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f 66  he Nth column of
2b730 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64   the.** returned
2b740 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 74   result set of t
2b750 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73 20  hat [SELECT] is 
2b760 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 28  a table column (
2b770 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65 73  not an.** expres
2b780 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72 79  sion or subquery
2b790 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c 61  ) then the decla
2b7a0 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65 20  red type of the 
2b7b0 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20  table.** column 
2b7c0 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 20  is returned.)^  
2b7d0 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c 75  ^If the Nth colu
2b7e0 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  mn of the result
2b7f0 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65 78   set is an.** ex
2b800 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71  pression or subq
2b810 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55 4c  uery, then a NUL
2b820 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65 74  L pointer is ret
2b830 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 72  urned..** ^The r
2b840 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
2b850 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20 65  s always UTF-8 e
2b860 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ncoded..**.** ^(
2b870 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69 76  For example, giv
2b880 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2b890 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43 52  schema:.**.** CR
2b8a0 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63 31  EATE TABLE t1(c1
2b8b0 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a 2a   VARIANT);.**.**
2b8c0 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77 69   and the followi
2b8d0 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  ng statement to 
2b8e0 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a 0a  be compiled:.**.
2b8f0 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20 31  ** SELECT c1 + 1
2b900 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a 2a  , c1 FROM t1;.**
2b910 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65  .** this routine
2b920 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68   would return th
2b930 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41 4e  e string "VARIAN
2b940 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f 6e  T" for the secon
2b950 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c 75  d result.** colu
2b960 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20 61  mn (i==1), and a
2b970 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66 6f   NULL pointer fo
2b980 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73 75  r the first resu
2b990 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30 29  lt column (i==0)
2b9a0 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  .)^.**.** ^SQLit
2b9b0 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20 72  e uses dynamic r
2b9c0 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e 20  un-time typing. 
2b9d0 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75 73   ^So just becaus
2b9e0 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73  e a column.** is
2b9f0 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f 6e   declared to con
2ba00 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c 61  tain a particula
2ba10 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74 20  r type does not 
2ba20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a 2a  mean that the.**
2ba30 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e 20   data stored in 
2ba40 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20 6f  that column is o
2ba50 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20 74  f the declared t
2ba60 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73 0a  ype.  SQLite is.
2ba70 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70 65  ** strongly type
2ba80 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69 6e  d, but the typin
2ba90 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f 74  g is dynamic not
2baa0 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65 0a   static.  ^Type.
2bab0 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65 64  ** is associated
2bac0 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61 6c   with individual
2bad0 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69 74   values, not wit
2bae0 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72 73  h the containers
2baf0 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c 64  .** used to hold
2bb00 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a 2a   those values..*
2bb10 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71  /.const char *sq
2bb20 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65 63  lite3_column_dec
2bb30 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  ltype(sqlite3_st
2bb40 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20  mt*,int);.const 
2bb50 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f  void *sqlite3_co
2bb60 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36 28  lumn_decltype16(
2bb70 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
2bb80 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2bb90 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41 6e  REF: Evaluate An
2bba0 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a   SQL Statement.*
2bbb0 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70 72  *.** After a [pr
2bbc0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2bbd0 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70 61  ] has been prepa
2bbe0 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65 72  red using either
2bbf0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
2bc00 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b 73  pare_v2()] or [s
2bc10 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
2bc20 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
2bc30 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69   the legacy.** i
2bc40 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69 74  nterfaces [sqlit
2bc50 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72  e3_prepare()] or
2bc60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
2bc70 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75 6e  e16()], this fun
2bc80 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62 65  ction.** must be
2bc90 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20 6d   called one or m
2bca0 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76 61  ore times to eva
2bcb0 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65 6d  luate the statem
2bcc0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 64  ent..**.** The d
2bcd0 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62 65  etails of the be
2bce0 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73 71  havior of the sq
2bcf0 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 74  lite3_step() int
2bd00 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a 2a  erface depend.**
2bd10 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65 20   on whether the 
2bd20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70 72  statement was pr
2bd30 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68 65  epared using the
2bd40 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74 65   newer "v2" inte
2bd50 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  rface.** [sqlite
2bd60 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
2bd70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  and [sqlite3_pre
2bd80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72 20  pare16_v2()] or 
2bd90 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63 79  the older legacy
2bda0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b 73  .** interface [s
2bdb0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29  qlite3_prepare()
2bdc0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
2bdd0 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54 68  repare16()].  Th
2bde0 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a 20  e use of the.** 
2bdf0 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66 61  new "v2" interfa
2be00 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
2be10 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69 63  d for new applic
2be20 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20 6c  ations but the l
2be30 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61  egacy.** interfa
2be40 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75 65  ce will continue
2be50 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2be60 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65 20  ..**.** ^In the 
2be70 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65  legacy interface
2be80 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  , the return val
2be90 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68 65  ue will be eithe
2bea0 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c  r [SQLITE_BUSY],
2beb0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45  .** [SQLITE_DONE
2bec0 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c  ], [SQLITE_ROW],
2bed0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2c   [SQLITE_ERROR],
2bee0 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55   or [SQLITE_MISU
2bef0 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74 68  SE]..** ^With th
2bf00 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2bf10 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74 68  , any of the oth
2bf20 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65 73  er [result codes
2bf30 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
2bf40 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
2bf50 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e 65  might be returne
2bf60 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a 2a  d as well..**.**
2bf70 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20   ^[SQLITE_BUSY] 
2bf80 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 64  means that the d
2bf90 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20 77  atabase engine w
2bfa0 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63 71  as unable to acq
2bfb0 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74 61  uire the.** data
2bfc0 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e 65  base locks it ne
2bfd0 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a 6f  eds to do its jo
2bfe0 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61 74  b.  ^If the stat
2bff0 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d 4d  ement is a [COMM
2c000 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72 73  IT].** or occurs
2c010 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20 65   outside of an e
2c020 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74  xplicit transact
2c030 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63 61  ion, then you ca
2c040 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20 73  n retry the.** s
2c050 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74 68  tatement.  If th
2c060 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 6e  e statement is n
2c070 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61 6e  ot a [COMMIT] an
2c080 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20  d occurs within 
2c090 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20 74  an.** explicit t
2c0a0 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e 20  ransaction then 
2c0b0 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c 62  you should rollb
2c0c0 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63 74  ack the transact
2c0d0 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63 6f  ion before.** co
2c0e0 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  ntinuing..**.** 
2c0f0 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20 6d  ^[SQLITE_DONE] m
2c100 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73 74  eans that the st
2c110 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e 69  atement has fini
2c120 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a 2a  shed executing.*
2c130 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e 20  * successfully. 
2c140 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
2c150 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63 61  should not be ca
2c160 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74 68  lled again on th
2c170 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d 61  is virtual.** ma
2c180 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66 69  chine without fi
2c190 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  rst calling [sql
2c1a0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74 6f  ite3_reset()] to
2c1b0 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74 75   reset the virtu
2c1c0 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62 61  al.** machine ba
2c1d0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2c1e0 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e  l state..**.** ^
2c1f0 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  If the SQL state
2c200 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63 75  ment being execu
2c210 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79 20  ted returns any 
2c220 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c 49  data, then [SQLI
2c230 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72 65  TE_ROW].** is re
2c240 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d 65  turned each time
2c250 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64 61   a new row of da
2c260 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72 20  ta is ready for 
2c270 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74 68  processing by th
2c280 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68 65  e.** caller. The
2c290 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20 61   values may be a
2c2a0 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74 68  ccessed using th
2c2b0 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  e [column access
2c2c0 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20   functions]..** 
2c2d0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
2c2e0 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 74  s called again t
2c2f0 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20 6e  o retrieve the n
2c300 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61 2e  ext row of data.
2c310 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  .**.** ^[SQLITE_
2c320 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68 61  ERROR] means tha
2c330 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72 72  t a run-time err
2c340 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63 6f  or (such as a co
2c350 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f 6c  nstraint.** viol
2c360 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75 72  ation) has occur
2c370 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73 74  red.  sqlite3_st
2c380 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20  ep() should not 
2c390 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  be called again 
2c3a0 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d 6f  on.** the VM. Mo
2c3b0 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 6d  re information m
2c3c0 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20 63  ay be found by c
2c3d0 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  alling [sqlite3_
2c3e0 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e 57  errmsg()]..** ^W
2c3f0 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20 69  ith the legacy i
2c400 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72 65  nterface, a more
2c410 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
2c420 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70 6c  code (for exampl
2c430 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4e  e,.** [SQLITE_IN
2c440 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49 54  TERRUPT], [SQLIT
2c450 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c 49  E_SCHEMA], [SQLI
2c460 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e 64  TE_CORRUPT], and
2c470 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63 61   so forth).** ca
2c480 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62 79  n be obtained by
2c490 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
2c4a0 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74 68  3_reset()] on th
2c4b0 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
2c4c0 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e 20  tatement].  ^In 
2c4d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
2c4e0 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20  ce,.** the more 
2c4f0 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20 63  specific error c
2c500 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64 20  ode is returned 
2c510 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c 69  directly by sqli
2c520 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a 2a  te3_step()..**.*
2c530 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45  * [SQLITE_MISUSE
2c540 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
2c550 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 61   this routine wa
2c560 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72 6f  s called inappro
2c570 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65 72  priately..** Per
2c580 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c 6c  haps it was call
2c590 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65  ed on a [prepare
2c5a0 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61  d statement] tha
2c5b0 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64 79  t has.** already
2c5c0 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66   been [sqlite3_f
2c5d0 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c 69  inalize | finali
2c5e0 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20 74  zed] or on one t
2c5f0 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76 69  hat had.** previ
2c600 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20 5b  ously returned [
2c610 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f 72  SQLITE_ERROR] or
2c620 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
2c630 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a 20   Or it could.** 
2c640 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61 74  be the case that
2c650 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
2c660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
2c670 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20 74   being used by t
2c680 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74 68  wo or.** more th
2c690 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61 6d  reads at the sam
2c6a0 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d 65  e moment in time
2c6b0 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c 20  ..**.** For all 
2c6c0 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
2c6d0 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e 63  te up to and inc
2c6e0 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31 2c  luding 3.6.23.1,
2c6f0 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73   a call to.** [s
2c700 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
2c710 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66 74  was required aft
2c720 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  er sqlite3_step(
2c730 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74 68  ) returned anyth
2c740 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68 61  ing.** other tha
2c750 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 62  n [SQLITE_ROW] b
2c760 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65 71  efore any subseq
2c770 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 20  uent invocation 
2c780 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  of.** sqlite3_st
2c790 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20 74  ep().  Failure t
2c7a0 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  o reset the prep
2c7b0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 75  ared statement u
2c7c0 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74 65  sing .** [sqlite
2c7d0 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c 64  3_reset()] would
2c7e0 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b 53   result in an [S
2c7f0 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72 65  QLITE_MISUSE] re
2c800 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71 6c  turn from.** sql
2c810 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42 75  ite3_step().  Bu
2c820 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e 20  t after version 
2c830 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74 65  3.6.23.1, sqlite
2c840 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a 2a  3_step() began.*
2c850 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  * calling [sqlit
2c860 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74 6f  e3_reset()] auto
2c870 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68 69  matically in thi
2c880 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20 72  s circumstance r
2c890 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72 65  ather.** than re
2c8a0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
2c8b0 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20 69  MISUSE].  This i
2c8c0 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65 64  s not considered
2c8d0 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79   a compatibility
2c8e0 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75 73  .** break becaus
2c8f0 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69 6f  e any applicatio
2c900 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63 65  n that ever rece
2c910 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f 4d  ives an SQLITE_M
2c920 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20 69  ISUSE error.** i
2c930 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66 69  s broken by defi
2c940 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53 51  nition.  The [SQ
2c950 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52 45  LITE_OMIT_AUTORE
2c960 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  SET] compile-tim
2c970 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e 20  e option.** can 
2c980 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74 6f  be used to resto
2c990 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62 65  re the legacy be
2c9a0 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c 62  havior..**.** <b
2c9b0 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63 65  >Goofy Interface
2c9c0 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20 74   Alert:</b> In t
2c9d0 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
2c9e0 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65 33  ace, the sqlite3
2c9f0 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20 61  _step().** API a
2ca00 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61 20  lways returns a 
2ca10 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63 6f  generic error co
2ca20 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  de, [SQLITE_ERRO
2ca30 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e  R], following an
2ca40 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65 72  y.** error other
2ca50 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42 55   than [SQLITE_BU
2ca60 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  SY] and [SQLITE_
2ca70 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d 75  MISUSE].  You mu
2ca80 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c 69  st call.** [sqli
2ca90 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20  te3_reset()] or 
2caa0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2cab0 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74 6f  e()] in order to
2cac0 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68 65   find one of the
2cad0 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65 72  .** specific [er
2cae0 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74 20  ror codes] that 
2caf0 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65 73  better describes
2cb00 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20 57   the error..** W
2cb10 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68 69  e admit that thi
2cb20 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65 73  s is a goofy des
2cb30 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c 65  ign.  The proble
2cb40 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65 64  m has been fixed
2cb50 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76 32  .** with the "v2
2cb60 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49 66  " interface.  If
2cb70 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c 6c   you prepare all
2cb80 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74 61   of your SQL sta
2cb90 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e 67  tements.** using
2cba0 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33   either [sqlite3
2cbb0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
2cbc0 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
2cbd0 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74 65  re16_v2()] inste
2cbe0 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65 67  ad.** of the leg
2cbf0 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  acy [sqlite3_pre
2cc00 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c  pare()] and [sql
2cc10 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29  ite3_prepare16()
2cc20 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a 2a  ] interfaces,.**
2cc30 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20 73   then the more s
2cc40 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20 63  pecific [error c
2cc50 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72 6e  odes] are return
2cc60 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20 62  ed directly.** b
2cc70 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  y sqlite3_step()
2cc80 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74 68  .  The use of th
2cc90 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63 65  e "v2" interface
2cca0 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e   is recommended.
2ccb0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2ccc0 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74 6d  step(sqlite3_stm
2ccd0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
2cce0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66 20  3REF: Number of 
2ccf0 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65 73  columns in a res
2cd00 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e 54  ult set.**.** ^T
2cd10 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
2cd20 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66 61  count(P) interfa
2cd30 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  ce returns the n
2cd40 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73  umber of columns
2cd50 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72 65   in the.** curre
2cd60 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72 65  nt row of the re
2cd70 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72 65  sult set of [pre
2cd80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2cd90 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70 61   P..** ^If prepa
2cda0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50 20  red statement P 
2cdb0 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72 65  does not have re
2cdc0 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20 72  sults ready to r
2cdd0 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63 61  eturn.** (via ca
2cde0 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  lls to the [sqli
2cdf0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20 7c  te3_column_int |
2ce00 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2ce10 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65 72  *()] of.** inter
2ce20 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c 69  faces) then sqli
2ce30 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 50  te3_data_count(P
2ce40 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a 20  ) returns 0..** 
2ce50 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2ce60 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69  a_count(P) routi
2ce70 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73 20  ne also returns 
2ce80 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c 4c  0 if P is a NULL
2ce90 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54 68   pointer..** ^Th
2cea0 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  e sqlite3_data_c
2ceb0 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65 20  ount(P) routine 
2cec0 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68 65  returns 0 if the
2ced0 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
2cee0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74  o.** [sqlite3_st
2cef0 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64 20  ep](P) returned 
2cf00 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20 20  [SQLITE_DONE].  
2cf10 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
2cf20 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77 69  a_count(P).** wi
2cf30 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a 65  ll return non-ze
2cf40 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20 63  ro if previous c
2cf50 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2cf60 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65  step](P) returne
2cf70 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f 57  d.** [SQLITE_ROW
2cf80 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68 65  ], except in the
2cf90 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50 52   case of the [PR
2cfa0 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61 6c  AGMA incremental
2cfb0 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65 72  _vacuum].** wher
2cfc0 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74 75  e it always retu
2cfd0 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20 65  rns zero since e
2cfe0 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61 74  ach step of that
2cff0 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20 70   multi-step.** p
2d000 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30 20  ragma returns 0 
2d010 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61 2e  columns of data.
2d020 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
2d030 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2d040 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
2d050 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f   sqlite3_data_co
2d060 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  unt(sqlite3_stmt
2d070 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
2d080 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64 61   CAPI3REF: Funda
2d090 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65 73  mental Datatypes
2d0a0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53 51  .** KEYWORDS: SQ
2d0b0 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a 20  LITE_TEXT.**.** 
2d0c0 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69 6e  ^(Every value in
2d0d0 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65 20   SQLite has one 
2d0e0 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65 6e  of five fundamen
2d0f0 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a 2a  tal datatypes:.*
2d100 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
2d110 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20  > 64-bit signed 
2d120 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e 20  integer.** <li> 
2d130 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f 61  64-bit IEEE floa
2d140 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65  ting point numbe
2d150 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e 67  r.** <li> string
2d160 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a 2a  .** <li> BLOB.**
2d170 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f   <li> NULL.** </
2d180 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ul>)^.**.** Thes
2d190 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20  e constants are 
2d1a0 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20 6f  codes for each o
2d1b0 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a 2a  f those types..*
2d1c0 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 74  *.** Note that t
2d1d0 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20 63  he SQLITE_TEXT c
2d1e0 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73 6f  onstant was also
2d1f0 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65 20   used in SQLite 
2d200 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f 72  version 2.** for
2d210 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64 69   a completely di
2d220 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67 2e  fferent meaning.
2d230 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74 20    Software that 
2d240 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62 6f  links against bo
2d250 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65 72  th.** SQLite ver
2d260 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69 74  sion 2 and SQLit
2d270 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f 75  e version 3 shou
2d280 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f 54  ld use SQLITE3_T
2d290 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c 49  EXT, not.** SQLI
2d2a0 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65 66  TE_TEXT..*/.#def
2d2b0 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 47  ine SQLITE_INTEG
2d2c0 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51  ER  1.#define SQ
2d2d0 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32 0a  LITE_FLOAT    2.
2d2e0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42  #define SQLITE_B
2d2f0 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69 6e  LOB     4.#defin
2d300 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20 20  e SQLITE_NULL   
2d310 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49 54    5.#ifdef SQLIT
2d320 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20 53  E_TEXT.# undef S
2d330 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73 65  QLITE_TEXT.#else
2d340 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54 45  .# define SQLITE
2d350 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e 64  _TEXT     3.#end
2d360 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  if.#define SQLIT
2d370 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a 2f  E3_TEXT     3../
2d380 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
2d390 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72 6f  esult Values Fro
2d3a0 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45 59  m A Query.** KEY
2d3b0 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20 61  WORDS: {column a
2d3c0 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 7d  ccess functions}
2d3d0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
2d3e0 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20 22  tines form the "
2d3f0 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74 65  result set" inte
2d400 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  rface..**.** ^Th
2d410 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 74  ese routines ret
2d420 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  urn information 
2d430 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20 63  about a single c
2d440 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75 72  olumn of the cur
2d450 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20 72  rent.** result r
2d460 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20 20  ow of a query.  
2d470 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20 74  ^In every case t
2d480 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
2d490 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a 2a  t is a pointer.*
2d4a0 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61 72  * to the [prepar
2d4b0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
2d4c0 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61 6c  at is being eval
2d4d0 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c 69  uated (the [sqli
2d4e0 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74 68  te3_stmt*].** th
2d4f0 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64 20  at was returned 
2d500 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70 72  from [sqlite3_pr
2d510 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 6f  epare_v2()] or o
2d520 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61 6e  ne of its varian
2d530 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20 73  ts).** and the s
2d540 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 69  econd argument i
2d550 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74  s the index of t
2d560 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77 68  he column for wh
2d570 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a  ich information.
2d580 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74  ** should be ret
2d590 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66 74  urned. ^The left
2d5a0 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20 74  most column of t
2d5b0 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68 61  he result set ha
2d5c0 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a 2a  s the index 0..*
2d5d0 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f 66  * ^The number of
2d5e0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20   columns in the 
2d5f0 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64 65  result can be de
2d600 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a 2a  termined using.*
2d610 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  * [sqlite3_colum
2d620 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a  n_count()]..**.*
2d630 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74 61  * If the SQL sta
2d640 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
2d650 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74 20  currently point 
2d660 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c 20  to a valid row, 
2d670 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f 6c  or if the.** col
2d680 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75 74  umn index is out
2d690 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20 72   of range, the r
2d6a0 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69 6e  esult is undefin
2d6b0 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  ed..** These rou
2d6c0 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20 62  tines may only b
2d6d0 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74 68  e called when th
2d6e0 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63 61  e most recent ca
2d6f0 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
2d700 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72 65  3_step()] has re
2d710 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f 52  turned [SQLITE_R
2d720 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72 0a  OW] and neither.
2d730 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  ** [sqlite3_rese
2d740 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74 65  t()] nor [sqlite
2d750 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68 61  3_finalize()] ha
2d760 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 73  ve been called s
2d770 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a 20  ubsequently..** 
2d780 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  If any of these 
2d790 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
2d7a0 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74  led after [sqlit
2d7b0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a  e3_reset()] or.*
2d7c0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  * [sqlite3_final
2d7d0 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20  ize()] or after 
2d7e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2d7f0 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a 2a   has returned.**
2d800 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72   something other
2d810 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f   than [SQLITE_RO
2d820 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73 20  W], the results 
2d830 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
2d840 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73 74  * If [sqlite3_st
2d850 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ep()] or [sqlite
2d860 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73  3_reset()] or [s
2d870 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2d880 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65 64  )].** are called
2d890 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65 6e   from a differen
2d8a0 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20 61  t thread while a
2d8b0 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74  ny of these rout
2d8c0 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e 64  ines.** are pend
2d8d0 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72 65  ing, then the re
2d8e0 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
2d8f0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ned..**.** ^The 
2d900 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2d910 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72 65  ype() routine re
2d920 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53 51  turns the.** [SQ
2d930 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20 64  LITE_INTEGER | d
2d940 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66 6f  atatype code] fo
2d950 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64 61  r the initial da
2d960 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74 68  ta type.** of th
2d970 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 2e  e result column.
2d980 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64 20    ^The returned 
2d990 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66 20  value is one of 
2d9a0 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 5d  [SQLITE_INTEGER]
2d9b0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c 4f  ,.** [SQLITE_FLO
2d9c0 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45 58  AT], [SQLITE_TEX
2d9d0 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f 42  T], [SQLITE_BLOB
2d9e0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 55  ], or [SQLITE_NU
2d9f0 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65 0a  LL].  The value.
2da00 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
2da10 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
2da20 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65 61  pe() is only mea
2da30 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74 79  ningful if no ty
2da40 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f 6e  pe.** conversion
2da50 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64 20  s have occurred 
2da60 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65 6c  as described bel
2da70 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79 70  ow.  After a typ
2da80 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a 2a  e conversion,.**
2da90 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
2daa0 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63  ned by sqlite3_c
2dab0 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73 20  olumn_type() is 
2dac0 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74 75  undefined.  Futu
2dad0 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20 6f  re.** versions o
2dae0 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68 61  f SQLite may cha
2daf0 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f 72  nge the behavior
2db00 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   of sqlite3_colu
2db10 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f 6c  mn_type().** fol
2db20 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63 6f  lowing a type co
2db30 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  nversion..**.** 
2db40 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69  ^If the result i
2db50 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d  s a BLOB or UTF-
2db60 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  8 string then th
2db70 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
2db80 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75 74  _bytes().** rout
2db90 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
2dba0 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
2dbb0 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72 20  in that BLOB or 
2dbc0 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74  string..** ^If t
2dbd0 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 55  he result is a U
2dbe0 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74 68  TF-16 string, th
2dbf0 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2dc00 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65 72  n_bytes() conver
2dc10 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  ts.** the string
2dc20 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74 68   to UTF-8 and th
2dc30 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e  en returns the n
2dc40 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e 0a  umber of bytes..
2dc50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2dc60 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20 76  t is a numeric v
2dc70 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74 65  alue then sqlite
2dc80 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2dc90 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74 65   uses.** [sqlite
2dca0 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74 6f  3_snprintf()] to
2dcb0 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76 61   convert that va
2dcc0 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20 73  lue to a UTF-8 s
2dcd0 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72 6e  tring and return
2dce0 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
2dcf0 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74  of bytes in that
2dd00 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2dd10 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e 55  the result is NU
2dd20 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  LL, then sqlite3
2dd30 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20  _column_bytes() 
2dd40 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a  returns zero..**
2dd50 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2dd60 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72 20  lt is a BLOB or 
2dd70 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74 68  UTF-16 string th
2dd80 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  en the sqlite3_c
2dd90 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 0a  olumn_bytes16().
2dda0 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
2ddb0 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ns the number of
2ddc0 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 42   bytes in that B
2ddd0 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a 2a  LOB or string..*
2dde0 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
2ddf0 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69   is a UTF-8 stri
2de00 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33  ng, then sqlite3
2de10 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2de20 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74 68  ) converts.** th
2de30 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46 2d  e string to UTF-
2de40 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74 75  16 and then retu
2de50 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2de60 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66 20  f bytes..** ^If 
2de70 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2de80 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74 68  numeric value th
2de90 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
2dea0 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65 73  n_bytes16() uses
2deb0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
2dec0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
2ded0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
2dee0 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  o a UTF-16 strin
2def0 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a  g and returns.**
2df00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
2df10 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72  ytes in that str
2df20 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ing..** ^If the 
2df30 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20  result is NULL, 
2df40 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
2df50 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72 65  umn_bytes16() re
2df60 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a  turns zero..**.*
2df70 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72 65  * ^The values re
2df80 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2df90 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2dfa0 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c 69  )] and .** [sqli
2dfb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2dfc0 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e 63  16()] do not inc
2dfd0 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74 65  lude the zero te
2dfe0 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68 65  rminators at the
2dff0 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20 73   end.** of the s
2e000 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c 61  tring.  ^For cla
2e010 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65 73  rity: the values
2e020 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2e030 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2e040 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73 71  bytes()] and [sq
2e050 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
2e060 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65 20  es16()] are the 
2e070 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79 74  number of.** byt
2e080 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67  es in the string
2e090 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65 72  , not the number
2e0a0 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e 0a   of characters..
2e0b0 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20 72  **.** ^Strings r
2e0c0 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74  eturned by sqlit
2e0d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2e0e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2e0f0 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  umn_text16(),.**
2e100 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72 69   even empty stri
2e110 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73 20  ngs, are always 
2e120 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e  zero-terminated.
2e130 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a 2a    ^The return.**
2e140 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
2e150 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28  te3_column_blob(
2e160 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65 6e  ) for a zero-len
2e170 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e 55  gth BLOB is a NU
2e180 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
2e190 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72 65  * ^The object re
2e1a0 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74  turned by [sqlit
2e1b0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
2e1c0 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e 70  )] is an.** [unp
2e1d0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2e1e0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e 20  _value] object. 
2e1f0 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   An unprotected 
2e200 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
2e210 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79  ject.** may only
2e220 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b 73   be used with [s
2e230 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75  qlite3_bind_valu
2e240 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
2e250 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2e260 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75 6e  ]..** If the [un
2e270 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2e280 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
2e290 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20 5b  returned by.** [
2e2a0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76  sqlite3_column_v
2e2b0 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64 20  alue()] is used 
2e2c0 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61 79  in any other way
2e2d0 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c 6c  , including call
2e2e0 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65 73  s.** to routines
2e2f0 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 76   like [sqlite3_v
2e300 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73 71  alue_int()], [sq
2e310 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2e320 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69  ()],.** or [sqli
2e330 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2e340 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  )], then the beh
2e350 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e  avior is undefin
2e360 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ed..**.** These 
2e370 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70 74  routines attempt
2e380 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65 20   to convert the 
2e390 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70 72  value where appr
2e3a0 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a 2a  opriate.  ^For.*
2e3b0 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74 68  * example, if th
2e3c0 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72 65  e internal repre
2e3d0 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c 4f  sentation is FLO
2e3e0 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72 65  AT and a text re
2e3f0 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75 65  sult.** is reque
2e400 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f 73  sted, [sqlite3_s
2e410 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75 73  nprintf()] is us
2e420 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74 6f  ed internally to
2e430 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a 20   perform the.** 
2e440 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f 6d  conversion autom
2e450 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68 65  atically.  ^(The
2e460 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c 65   following table
2e470 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f 6e   details the con
2e480 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61 74  versions.** that
2e490 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a 2a   are applied:.**
2e4a0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
2e4b0 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64 65  .** <table borde
2e4c0 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  r="1">.** <tr><t
2e4d0 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e 54  h> Internal<br>T
2e4e0 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73 74  ype <th> Request
2e4f0 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20  ed<br>Type <th> 
2e500 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a 2a   Conversion.**.*
2e510 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
2e520 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2e530 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
2e540 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  s 0.** <tr><td> 
2e550 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20 46   NULL    <td>  F
2e560 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65 73  LOAT    <td> Res
2e570 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c 74  ult is 0.0.** <t
2e580 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20  r><td>  NULL    
2e590 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
2e5a0 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 61 20  td> Result is a 
2e5b0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20  NULL pointer.** 
2e5c0 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20  <tr><td>  NULL  
2e5d0 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20    <td>   BLOB   
2e5e0 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20   <td> Result is 
2e5f0 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a  a NULL pointer.*
2e600 2a 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47  * <tr><td> INTEG
2e610 45 52 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20  ER  <td>  FLOAT 
2e620 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2e630 66 72 6f 6d 20 69 6e 74 65 67 65 72 20 74 6f 20  from integer to 
2e640 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  float.** <tr><td
2e650 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
2e660 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 41    TEXT    <td> A
2e670 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67 20 6f  SCII rendering o
2e680 66 20 74 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a  f the integer.**
2e690 20 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45   <tr><td> INTEGE
2e6a0 52 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20  R  <td>   BLOB  
2e6b0 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73 20 49    <td> Same as I
2e6c0 4e 54 45 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20  NTEGER->TEXT.** 
2e6d0 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20  <tr><td>  FLOAT 
2e6e0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
2e6f0 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20   <td> [CAST] to 
2e700 49 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c  INTEGER.** <tr><
2e710 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64  td>  FLOAT   <td
2e720 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e  >   TEXT    <td>
2e730 20 41 53 43 49 49 20 72 65 6e 64 65 72 69 6e 67   ASCII rendering
2e740 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a 2a 2a   of the float.**
2e750 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54   <tr><td>  FLOAT
2e760 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20     <td>   BLOB  
2e770 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f    <td> [CAST] to
2e780 20 42 4c 4f 42 0a 2a 2a 20 3c 74 72 3e 3c 74 64   BLOB.** <tr><td
2e790 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
2e7a0 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e 20 5b  INTEGER   <td> [
2e7b0 43 41 53 54 5d 20 74 6f 20 49 4e 54 45 47 45 52  CAST] to INTEGER
2e7c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
2e7d0 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
2e7e0 54 20 20 20 20 3c 74 64 3e 20 5b 43 41 53 54 5d  T    <td> [CAST]
2e7f0 20 74 6f 20 52 45 41 4c 0a 2a 2a 20 3c 74 72 3e   to REAL.** <tr>
2e800 3c 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74  <td>  TEXT    <t
2e810 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  d>   BLOB    <td
2e820 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c  > No change.** <
2e830 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20  tr><td>  BLOB   
2e840 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20   <td> INTEGER   
2e850 3c 74 64 3e 20 5b 43 41 53 54 5d 20 74 6f 20 49  <td> [CAST] to I
2e860 4e 54 45 47 45 52 0a 2a 2a 20 3c 74 72 3e 3c 74  NTEGER.** <tr><t
2e870 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e  d>  BLOB    <td>
2e880 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20    FLOAT    <td> 
2e890 5b 43 41 53 54 5d 20 74 6f 20 52 45 41 4c 0a 2a  [CAST] to REAL.*
2e8a0 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2e8b0 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20      <td>   TEXT 
2e8c0 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20 7a 65     <td> Add a ze
2e8d0 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20 69 66  ro terminator if
2e8e0 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74 61 62   needed.** </tab
2e8f0 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75  le>.** </blockqu
2e900 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ote>)^.**.** The
2e910 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d 61 6b   table above mak
2e920 65 73 20 72 65 66 65 72 65 6e 63 65 20 74 6f 20  es reference to 
2e930 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62 72 61  standard C libra
2e940 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61 74 6f  ry functions ato
2e950 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f 66 28  i().** and atof(
2e960 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65 73 20  ).  SQLite does 
2e970 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65 20 74  not really use t
2e980 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2e 20  hese functions. 
2e990 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a 20 6f   It has its.** o
2e9a0 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20 69 6e  wn equivalent in
2e9b0 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65 73 2e  ternal routines.
2e9c0 20 20 54 68 65 20 61 74 6f 69 28 29 20 61 6e 64    The atoi() and
2e9d0 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20 61 72   atof() names ar
2e9e0 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74 68 65  e.** used in the
2e9f0 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65 76 69   table for brevi
2ea00 74 79 20 61 6e 64 20 62 65 63 61 75 73 65 20 74  ty and because t
2ea10 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69 61 72  hey are familiar
2ea20 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20 70 72   to most.** C pr
2ea30 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a  ogrammers..**.**
2ea40 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65 6e 20   Note that when 
2ea50 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 73  type conversions
2ea60 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65 72 73   occur, pointers
2ea70 20 72 65 74 75 72 6e 65 64 20 62 79 20 70 72 69   returned by pri
2ea80 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  or.** calls to s
2ea90 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c  qlite3_column_bl
2eaa0 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 63 6f  ob(), sqlite3_co
2eab0 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61 6e 64  lumn_text(), and
2eac0 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  /or.** sqlite3_c
2ead0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 6d  olumn_text16() m
2eae0 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65  ay be invalidate
2eaf0 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e 76 65  d..** Type conve
2eb00 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69 6e 74  rsions and point
2eb10 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f 6e 73  er invalidations
2eb20 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a 20   might occur.** 
2eb30 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  in the following
2eb40 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75   cases:.**.** <u
2eb50 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  l>.** <li> The i
2eb60 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2eb70 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73 71 6c  s a BLOB and sql
2eb80 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2eb90 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71  () or.**      sq
2eba0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2ebb0 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  t16() is called.
2ebc0 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61    A zero-termina
2ebd0 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20 20 20  tor might.**    
2ebe0 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61 64 64    need to be add
2ebf0 65 64 20 74 6f 20 74 68 65 20 73 74 72 69 6e 67  ed to the string
2ec00 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54  .</li>.** <li> T
2ec10 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65  he initial conte
2ec20 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65 78 74  nt is UTF-8 text
2ec30 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c   and sqlite3_col
2ec40 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 6f 72  umn_bytes16() or
2ec50 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
2ec60 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2ec70 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54 68 65   is called.  The
2ec80 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20 62 65   content must be
2ec90 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20 20 20   converted.**   
2eca0 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c     to UTF-16.</l
2ecb0 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
2ecc0 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
2ecd0 73 20 55 54 46 2d 31 36 20 74 65 78 74 20 61 6e  s UTF-16 text an
2ece0 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
2ecf0 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a 20 20  _bytes() or.**  
2ed00 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
2ed10 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63 61 6c  mn_text() is cal
2ed20 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74 65 6e  led.  The conten
2ed30 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72  t must be conver
2ed40 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f 20 55  ted.**      to U
2ed50 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f  TF-8.</li>.** </
2ed60 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65  ul>.**.** ^Conve
2ed70 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e 20 55  rsions between U
2ed80 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54 46 2d  TF-16be and UTF-
2ed90 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79 73 20  16le are always 
2eda0 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 61 6e  done in place an
2edb0 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61  d do.** not inva
2edc0 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72 20 70  lidate a prior p
2edd0 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68 20 6f  ointer, though o
2ede0 66 20 63 6f 75 72 73 65 20 74 68 65 20 63 6f 6e  f course the con
2edf0 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75 66 66  tent of the buff
2ee00 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 70  er.** that the p
2ee10 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72 65 66  rior pointer ref
2ee20 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68 61 76  erences will hav
2ee30 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65 64 2e  e been modified.
2ee40 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a 2a 2a    Other kinds.**
2ee50 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61   of conversion a
2ee60 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65  re done in place
2ee70 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f 73 73   when it is poss
2ee80 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65 74 69  ible, but someti
2ee90 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72 65 20  mes they.** are 
2eea0 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61 6e 64  not possible and
2eeb0 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65 73 20   in those cases 
2eec0 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73 20 61  prior pointers a
2eed0 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a  re invalidated..
2eee0 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65 73 74  **.** The safest
2eef0 20 61 6e 64 20 65 61 73 69 65 73 74 20 74 6f 20   and easiest to 
2ef00 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63 79 20  remember policy 
2ef10 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74 68 65  is to invoke the
2ef20 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a 20 69  se routines.** i
2ef30 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c  n one of the fol
2ef40 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a  lowing ways:.**.
2ef50 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e  ** <ul>.**  <li>
2ef60 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2ef70 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  ext() followed b
2ef80 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2ef90 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a  _bytes()</li>.**
2efa0 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63 6f    <li>sqlite3_co
2efb0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c  lumn_blob() foll
2efc0 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  owed by sqlite3_
2efd0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 3c 2f  column_bytes()</
2efe0 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  li>.**  <li>sqli
2eff0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2f000 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20  6() followed by 
2f010 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
2f020 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a  ytes16()</li>.**
2f030 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
2f040 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79 6f 75  other words, you
2f050 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73 71 6c   should call sql
2f060 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2f070 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  (),.** sqlite3_c
2f080 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72  olumn_blob(), or
2f090 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2f0a0 74 65 78 74 31 36 28 29 20 66 69 72 73 74 20 74  text16() first t
2f0b0 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65 73 75  o force the resu
2f0c0 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65 20 64  lt.** into the d
2f0d0 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c 20 74  esired format, t
2f0e0 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c 69 74  hen invoke sqlit
2f0f0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2f100 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
2f110 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2f120 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73 69 7a   to find the siz
2f130 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 2e  e of the result.
2f140 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c    Do not mix cal
2f150 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33  ls.** to sqlite3
2f160 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
2f170 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  r sqlite3_column
2f180 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63 61 6c  _blob() with cal
2f190 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33  ls to.** sqlite3
2f1a0 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2f1b0 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20 6d 69  ), and do not mi
2f1c0 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  x calls to sqlit
2f1d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2f1e0 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c 6c 73  ().** with calls
2f1f0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2f200 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a  mn_bytes()..**.*
2f210 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72 73 20  * ^The pointers 
2f220 72 65 74 75 72 6e 65 64 20 61 72 65 20 76 61 6c  returned are val
2f230 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70 65 20  id until a type 
2f240 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63 75 72  conversion occur
2f250 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69 62 65  s as.** describe
2f260 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e 74 69  d above, or unti
2f270 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  l [sqlite3_step(
2f280 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  )] or [sqlite3_r
2f290 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  eset()] or.** [s
2f2a0 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f2b0 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 5e  )] is called.  ^
2f2c0 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61 63 65  The memory space
2f2d0 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20 73 74   used to hold st
2f2e0 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f  rings.** and BLO
2f2f0 42 73 20 69 73 20 66 72 65 65 64 20 61 75 74 6f  Bs is freed auto
2f300 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f 20 3c  matically.  Do <
2f310 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73 20 74  b>not</b> pass t
2f320 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
2f330 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71  rned.** from [sq
2f340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
2f350 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  b()], [sqlite3_c
2f360 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65  olumn_text()], e
2f370 74 63 2e 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c  tc. into.** [sql
2f380 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a  ite3_free()]..**
2f390 0a 2a 2a 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72  .** ^(If a memor
2f3a0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72  y allocation err
2f3b0 6f 72 20 6f 63 63 75 72 73 20 64 75 72 69 6e 67  or occurs during
2f3c0 20 74 68 65 20 65 76 61 6c 75 61 74 69 6f 6e 20   the evaluation 
2f3d0 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65  of any.** of the
2f3e0 73 65 20 72 6f 75 74 69 6e 65 73 2c 20 61 20 64  se routines, a d
2f3f0 65 66 61 75 6c 74 20 76 61 6c 75 65 20 69 73 20  efault value is 
2f400 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20 64  returned.  The d
2f410 65 66 61 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20  efault value.** 
2f420 69 73 20 65 69 74 68 65 72 20 74 68 65 20 69 6e  is either the in
2f430 74 65 67 65 72 20 30 2c 20 74 68 65 20 66 6c 6f  teger 0, the flo
2f440 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
2f450 65 72 20 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c  er 0.0, or a NUL
2f460 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53  L.** pointer.  S
2f470 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2f480 74 6f 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 63  to [sqlite3_errc
2f490 6f 64 65 28 29 5d 20 77 69 6c 6c 20 72 65 74 75  ode()] will retu
2f4a0 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  rn.** [SQLITE_NO
2f4b0 4d 45 4d 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74  MEM].)^.*/.const
2f4c0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2f4d0 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74  olumn_blob(sqlit
2f4e0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f4f0 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2f500 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71  _column_bytes(sq
2f510 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2f520 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
2f530 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2f540 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
2f550 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75  , int iCol);.dou
2f560 62 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ble sqlite3_colu
2f570 6d 6e 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  mn_double(sqlite
2f580 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
2f590 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  l);.int sqlite3_
2f5a0 63 6f 6c 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74  column_int(sqlit
2f5b0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f5c0 6f 6c 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ol);.sqlite3_int
2f5d0 36 34 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  64 sqlite3_colum
2f5e0 6e 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  n_int64(sqlite3_
2f5f0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2f600 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64  ;.const unsigned
2f610 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
2f620 6f 6c 75 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74  olumn_text(sqlit
2f630 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2f640 6f 6c 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20  ol);.const void 
2f650 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
2f660 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f 73  text16(sqlite3_s
2f670 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f680 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2f690 75 6d 6e 5f 74 79 70 65 28 73 71 6c 69 74 65 33  umn_type(sqlite3
2f6a0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2f6b0 29 3b 0a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  );.sqlite3_value
2f6c0 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
2f6d0 5f 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73  _value(sqlite3_s
2f6e0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2f6f0 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
2f700 3a 20 44 65 73 74 72 6f 79 20 41 20 50 72 65 70  : Destroy A Prep
2f710 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20 4f  ared Statement O
2f720 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  bject.**.** ^The
2f730 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2f740 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
2f750 63 61 6c 6c 65 64 20 74 6f 20 64 65 6c 65 74 65  called to delete
2f760 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2f770 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20  tement]..** ^If 
2f780 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
2f790 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68  evaluation of th
2f7a0 65 20 73 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f  e statement enco
2f7b0 75 6e 74 65 72 65 64 20 6e 6f 20 65 72 72 6f 72  untered no error
2f7c0 73 0a 2a 2a 20 6f 72 20 69 66 20 74 68 65 20 73  s.** or if the s
2f7d0 74 61 74 65 6d 65 6e 74 20 69 73 20 6e 65 76 65  tatement is neve
2f7e0 72 20 62 65 65 6e 20 65 76 61 6c 75 61 74 65 64  r been evaluated
2f7f0 2c 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 66  , then sqlite3_f
2f800 69 6e 61 6c 69 7a 65 28 29 20 72 65 74 75 72 6e  inalize() return
2f810 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20  s.** SQLITE_OK. 
2f820 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65   ^If the most re
2f830 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20  cent evaluation 
2f840 6f 66 20 73 74 61 74 65 6d 65 6e 74 20 53 20 66  of statement S f
2f850 61 69 6c 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73  ailed, then.** s
2f860 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
2f870 53 29 20 72 65 74 75 72 6e 73 20 74 68 65 20 61  S) returns the a
2f880 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
2f890 72 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65  r code] or.** [e
2f8a0 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
2f8b0 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  de]..**.** ^The 
2f8c0 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2f8d0 28 53 29 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  (S) routine can 
2f8e0 62 65 20 63 61 6c 6c 65 64 20 61 74 20 61 6e 79  be called at any
2f8f0 20 70 6f 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a   point during.**
2f900 20 74 68 65 20 6c 69 66 65 20 63 79 63 6c 65 20   the life cycle 
2f910 6f 66 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  of [prepared sta
2f920 74 65 6d 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65  tement] S:.** be
2f930 66 6f 72 65 20 73 74 61 74 65 6d 65 6e 74 20 53  fore statement S
2f940 20 69 73 20 65 76 65 72 20 65 76 61 6c 75 61 74   is ever evaluat
2f950 65 64 2c 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65  ed, after.** one
2f960 20 6f 72 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74   or more calls t
2f970 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
2f980 28 29 5d 2c 20 6f 72 20 61 66 74 65 72 20 61 6e  ()], or after an
2f990 79 20 63 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71  y call.** to [sq
2f9a0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 72 65  lite3_step()] re
2f9b0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
2f9c0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 73  her or not the s
2f9d0 74 61 74 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20  tatement has.** 
2f9e0 63 6f 6d 70 6c 65 74 65 64 20 65 78 65 63 75 74  completed execut
2f9f0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f  ion..**.** ^Invo
2fa00 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 69 6e  king sqlite3_fin
2fa10 61 6c 69 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c  alize() on a NUL
2fa20 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 61 20 68  L pointer is a h
2fa30 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a  armless no-op..*
2fa40 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
2fa50 74 69 6f 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69  tion must finali
2fa60 7a 65 20 65 76 65 72 79 20 5b 70 72 65 70 61 72  ze every [prepar
2fa70 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e  ed statement] in
2fa80 20 6f 72 64 65 72 20 74 6f 20 61 76 6f 69 64 0a   order to avoid.
2fa90 2a 2a 20 72 65 73 6f 75 72 63 65 20 6c 65 61 6b  ** resource leak
2faa0 73 2e 20 20 49 74 20 69 73 20 61 20 67 72 69 65  s.  It is a grie
2fab0 76 6f 75 73 20 65 72 72 6f 72 20 66 6f 72 20 74  vous error for t
2fac0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  he application t
2fad0 6f 20 74 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20  o try to use.** 
2fae0 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
2faf0 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68 61  ment after it ha
2fb00 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
2fb10 2e 20 20 41 6e 79 20 75 73 65 20 6f 66 20 61 20  .  Any use of a 
2fb20 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
2fb30 65 6d 65 6e 74 20 61 66 74 65 72 20 69 74 20 68  ement after it h
2fb40 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65  as been finalize
2fb50 64 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e 20  d can result in 
2fb60 75 6e 64 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a  undefined and.**
2fb70 20 75 6e 64 65 73 69 72 61 62 6c 65 20 62 65 68   undesirable beh
2fb80 61 76 69 6f 72 20 73 75 63 68 20 61 73 20 73 65  avior such as se
2fb90 67 66 61 75 6c 74 73 20 61 6e 64 20 68 65 61 70  gfaults and heap
2fba0 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a   corruption..*/.
2fbb0 69 6e 74 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  int sqlite3_fina
2fbc0 6c 69 7a 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  lize(sqlite3_stm
2fbd0 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
2fbe0 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 65  * CAPI3REF: Rese
2fbf0 74 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61  t A Prepared Sta
2fc00 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a  tement Object.**
2fc10 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
2fc20 72 65 73 65 74 28 29 20 66 75 6e 63 74 69 6f 6e  reset() function
2fc30 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20 72 65   is called to re
2fc40 73 65 74 20 61 20 5b 70 72 65 70 61 72 65 64 20  set a [prepared 
2fc50 73 74 61 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62  statement].** ob
2fc60 6a 65 63 74 20 62 61 63 6b 20 74 6f 20 69 74 73  ject back to its
2fc70 20 69 6e 69 74 69 61 6c 20 73 74 61 74 65 2c 20   initial state, 
2fc80 72 65 61 64 79 20 74 6f 20 62 65 20 72 65 2d 65  ready to be re-e
2fc90 78 65 63 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79  xecuted..** ^Any
2fca0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 76   SQL statement v
2fcb0 61 72 69 61 62 6c 65 73 20 74 68 61 74 20 68 61  ariables that ha
2fcc0 64 20 76 61 6c 75 65 73 20 62 6f 75 6e 64 20 74  d values bound t
2fcd0 6f 20 74 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20  o them using.** 
2fce0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e  the [sqlite3_bin
2fcf0 64 5f 62 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33  d_blob | sqlite3
2fd00 5f 62 69 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72  _bind_*() API] r
2fd10 65 74 61 69 6e 20 74 68 65 69 72 20 76 61 6c 75  etain their valu
2fd20 65 73 2e 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69  es..** Use [sqli
2fd30 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e  te3_clear_bindin
2fd40 67 73 28 29 5d 20 74 6f 20 72 65 73 65 74 20 74  gs()] to reset t
2fd50 68 65 20 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a  he bindings..**.
2fd60 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
2fd70 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74 65 72  _reset(S)] inter
2fd80 66 61 63 65 20 72 65 73 65 74 73 20 74 68 65 20  face resets the 
2fd90 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2fda0 65 6e 74 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74  ent] S.** back t
2fdb0 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20  o the beginning 
2fdc0 6f 66 20 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a  of its program..
2fdd0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f  **.** ^If the mo
2fde0 73 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74  st recent call t
2fdf0 6f 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  o [sqlite3_step(
2fe00 53 29 5d 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b  S)] for the.** [
2fe10 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2fe20 6e 74 5d 20 53 20 72 65 74 75 72 6e 65 64 20 5b  nt] S returned [
2fe30 53 51 4c 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b  SQLITE_ROW] or [
2fe40 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a  SQLITE_DONE],.**
2fe50 20 6f 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f   or if [sqlite3_
2fe60 73 74 65 70 28 53 29 5d 20 68 61 73 20 6e 65 76  step(S)] has nev
2fe70 65 72 20 62 65 66 6f 72 65 20 62 65 65 6e 20 63  er before been c
2fe80 61 6c 6c 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74  alled on S,.** t
2fe90 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  hen [sqlite3_res
2fea0 65 74 28 53 29 5d 20 72 65 74 75 72 6e 73 20 5b  et(S)] returns [
2feb0 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a  SQLITE_OK]..**.*
2fec0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2fed0 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73  ecent call to [s
2fee0 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20  qlite3_step(S)] 
2fef0 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70  for the.** [prep
2ff00 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
2ff10 53 20 69 6e 64 69 63 61 74 65 64 20 61 6e 20 65  S indicated an e
2ff20 72 72 6f 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73  rror, then.** [s
2ff30 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2ff40 20 72 65 74 75 72 6e 73 20 61 6e 20 61 70 70 72   returns an appr
2ff50 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2ff60 6f 64 65 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ode]..**.** ^The
2ff70 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2ff80 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 64 6f  S)] interface do
2ff90 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
2ffa0 65 20 76 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61  e values.** of a
2ffb0 6e 79 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ny [sqlite3_bind
2ffc0 5f 62 6c 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20  _blob|bindings] 
2ffd0 6f 6e 20 74 68 65 20 5b 70 72 65 70 61 72 65 64  on the [prepared
2ffe0 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a   statement] S..*
2fff0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65  /.int sqlite3_re
30000 73 65 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  set(sqlite3_stmt
30010 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a   *pStmt);../*.**
30020 20 43 41 50 49 33 52 45 46 3a 20 43 72 65 61 74   CAPI3REF: Creat
30030 65 20 4f 72 20 52 65 64 65 66 69 6e 65 20 53 51  e Or Redefine SQ
30040 4c 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b  L Functions.** K
30050 45 59 57 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69  EYWORDS: {functi
30060 6f 6e 20 63 72 65 61 74 69 6f 6e 20 72 6f 75 74  on creation rout
30070 69 6e 65 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  ines}.** KEYWORD
30080 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
30090 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
300a0 74 69 6f 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44  tion}.** KEYWORD
300b0 53 3a 20 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d  S: {application-
300c0 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63  defined SQL func
300d0 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68  tions}.**.** ^Th
300e0 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 28 63  ese functions (c
300f0 6f 6c 6c 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77  ollectively know
30100 6e 20 61 73 20 22 66 75 6e 63 74 69 6f 6e 20 63  n as "function c
30110 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  reation routines
30120 22 29 0a 2a 2a 20 61 72 65 20 75 73 65 64 20 74  ").** are used t
30130 6f 20 61 64 64 20 53 51 4c 20 66 75 6e 63 74 69  o add SQL functi
30140 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
30150 73 20 6f 72 20 74 6f 20 72 65 64 65 66 69 6e 65  s or to redefine
30160 20 74 68 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a   the behavior.**
30170 20 6f 66 20 65 78 69 73 74 69 6e 67 20 53 51 4c   of existing SQL
30180 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67   functions or ag
30190 67 72 65 67 61 74 65 73 2e 20 20 54 68 65 20 6f  gregates.  The o
301a0 6e 6c 79 20 64 69 66 66 65 72 65 6e 63 65 73 20  nly differences 
301b0 62 65 74 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65  between.** these
301c0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 74 68   routines are th
301d0 65 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 20  e text encoding 
301e0 65 78 70 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20  expected for.** 
301f0 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
30200 65 74 65 72 20 28 74 68 65 20 6e 61 6d 65 20 6f  eter (the name o
30210 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 62  f the function b
30220 65 69 6e 67 20 63 72 65 61 74 65 64 29 0a 2a 2a  eing created).**
30230 20 61 6e 64 20 74 68 65 20 70 72 65 73 65 6e 63   and the presenc
30240 65 20 6f 72 20 61 62 73 65 6e 63 65 20 6f 66 20  e or absence of 
30250 61 20 64 65 73 74 72 75 63 74 6f 72 20 63 61 6c  a destructor cal
30260 6c 62 61 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65  lback for.** the
30270 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74   application dat
30280 61 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  a pointer..**.**
30290 20 5e 54 68 65 20 66 69 72 73 74 20 70 61 72 61   ^The first para
302a0 6d 65 74 65 72 20 69 73 20 74 68 65 20 5b 64 61  meter is the [da
302b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
302c0 6e 5d 20 74 6f 20 77 68 69 63 68 20 74 68 65 20  n] to which the 
302d0 53 51 4c 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  SQL.** function 
302e0 69 73 20 74 6f 20 62 65 20 61 64 64 65 64 2e 20  is to be added. 
302f0 20 5e 49 66 20 61 6e 20 61 70 70 6c 69 63 61 74   ^If an applicat
30300 69 6f 6e 20 75 73 65 73 20 6d 6f 72 65 20 74 68  ion uses more th
30310 61 6e 20 6f 6e 65 20 64 61 74 61 62 61 73 65 0a  an one database.
30320 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  ** connection th
30330 65 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  en application-d
30340 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
30350 69 6f 6e 73 20 6d 75 73 74 20 62 65 20 61 64 64  ions must be add
30360 65 64 0a 2a 2a 20 74 6f 20 65 61 63 68 20 64 61  ed.** to each da
30370 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30380 6e 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  n separately..**
30390 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  .** ^The second 
303a0 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
303b0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 53 51 4c   name of the SQL
303c0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
303d0 63 72 65 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65  created or.** re
303e0 64 65 66 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c  defined.  ^The l
303f0 65 6e 67 74 68 20 6f 66 20 74 68 65 20 6e 61 6d  ength of the nam
30400 65 20 69 73 20 6c 69 6d 69 74 65 64 20 74 6f 20  e is limited to 
30410 32 35 35 20 62 79 74 65 73 20 69 6e 20 61 20 55  255 bytes in a U
30420 54 46 2d 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e  TF-8.** represen
30430 74 61 74 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76  tation, exclusiv
30440 65 20 6f 66 20 74 68 65 20 7a 65 72 6f 2d 74 65  e of the zero-te
30450 72 6d 69 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65  rminator.  ^Note
30460 20 74 68 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a   that the name.*
30470 2a 20 6c 65 6e 67 74 68 20 6c 69 6d 69 74 20 69  * length limit i
30480 73 20 69 6e 20 55 54 46 2d 38 20 62 79 74 65 73  s in UTF-8 bytes
30490 2c 20 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73  , not characters
304a0 20 6e 6f 72 20 55 54 46 2d 31 36 20 62 79 74 65   nor UTF-16 byte
304b0 73 2e 20 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74  s.  .** ^Any att
304c0 65 6d 70 74 20 74 6f 20 63 72 65 61 74 65 20 61  empt to create a
304d0 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 61   function with a
304e0 20 6c 6f 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20   longer name.** 
304f0 77 69 6c 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b  will result in [
30500 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 62  SQLITE_MISUSE] b
30510 65 69 6e 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a  eing returned..*
30520 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72 64 20  *.** ^The third 
30530 70 61 72 61 6d 65 74 65 72 20 28 6e 41 72 67 29  parameter (nArg)
30540 0a 2a 2a 20 69 73 20 74 68 65 20 6e 75 6d 62 65  .** is the numbe
30550 72 20 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 74  r of arguments t
30560 68 61 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hat the SQL func
30570 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
30580 67 61 74 65 20 74 61 6b 65 73 2e 20 5e 49 66 20  gate takes. ^If 
30590 74 68 69 73 20 70 61 72 61 6d 65 74 65 72 20 69  this parameter i
305a0 73 20 2d 31 2c 20 74 68 65 6e 20 74 68 65 20 53  s -1, then the S
305b0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
305c0 2a 20 61 67 67 72 65 67 61 74 65 20 6d 61 79 20  * aggregate may 
305d0 74 61 6b 65 20 61 6e 79 20 6e 75 6d 62 65 72 20  take any number 
305e0 6f 66 20 61 72 67 75 6d 65 6e 74 73 20 62 65 74  of arguments bet
305f0 77 65 65 6e 20 30 20 61 6e 64 20 74 68 65 20 6c  ween 0 and the l
30600 69 6d 69 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b  imit.** set by [
30610 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b  sqlite3_limit]([
30620 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e  SQLITE_LIMIT_FUN
30630 43 54 49 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66  CTION_ARG]).  If
30640 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70 61   the third.** pa
30650 72 61 6d 65 74 65 72 20 69 73 20 6c 65 73 73 20  rameter is less 
30660 74 68 61 6e 20 2d 31 20 6f 72 20 67 72 65 61 74  than -1 or great
30670 65 72 20 74 68 61 6e 20 31 32 37 20 74 68 65 6e  er than 127 then
30680 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
30690 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
306a0 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68  *.** ^The fourth
306b0 20 70 61 72 61 6d 65 74 65 72 2c 20 65 54 65 78   parameter, eTex
306c0 74 52 65 70 2c 20 73 70 65 63 69 66 69 65 73 20  tRep, specifies 
306d0 77 68 61 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  what.** [SQLITE_
306e0 55 54 46 38 20 7c 20 74 65 78 74 20 65 6e 63 6f  UTF8 | text enco
306f0 64 69 6e 67 5d 20 74 68 69 73 20 53 51 4c 20 66  ding] this SQL f
30700 75 6e 63 74 69 6f 6e 20 70 72 65 66 65 72 73 20  unction prefers 
30710 66 6f 72 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d  for.** its param
30720 65 74 65 72 73 2e 20 20 54 68 65 20 61 70 70 6c  eters.  The appl
30730 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 73  ication should s
30740 65 74 20 74 68 69 73 20 70 61 72 61 6d 65 74 65  et this paramete
30750 72 20 74 6f 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  r to.** [SQLITE_
30760 55 54 46 31 36 4c 45 5d 20 69 66 20 74 68 65 20  UTF16LE] if the 
30770 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
30780 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73 20  ntation invokes 
30790 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
307a0 75 65 5f 74 65 78 74 31 36 6c 65 28 29 5d 20 6f  ue_text16le()] o
307b0 6e 20 61 6e 20 69 6e 70 75 74 2c 20 6f 72 20 5b  n an input, or [
307c0 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 20  SQLITE_UTF16BE] 
307d0 69 66 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  if the.** implem
307e0 65 6e 74 61 74 69 6f 6e 20 69 6e 76 6f 6b 65 73  entation invokes
307f0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30800 74 65 78 74 31 36 62 65 28 29 5d 20 6f 6e 20 61  text16be()] on a
30810 6e 20 69 6e 70 75 74 2c 20 6f 72 0a 2a 2a 20 5b  n input, or.** [
30820 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 69 66  SQLITE_UTF16] if
30830 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
30840 74 65 78 74 31 36 28 29 5d 20 69 73 20 75 73 65  text16()] is use
30850 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 54  d, or [SQLITE_UT
30860 46 38 5d 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  F8].** otherwise
30870 2e 20 20 5e 54 68 65 20 73 61 6d 65 20 53 51 4c  .  ^The same SQL
30880 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65   function may be
30890 20 72 65 67 69 73 74 65 72 65 64 20 6d 75 6c 74   registered mult
308a0 69 70 6c 65 20 74 69 6d 65 73 20 75 73 69 6e 67  iple times using
308b0 0a 2a 2a 20 64 69 66 66 65 72 65 6e 74 20 70 72  .** different pr
308c0 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
308d0 6f 64 69 6e 67 73 2c 20 77 69 74 68 20 64 69 66  odings, with dif
308e0 66 65 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  ferent implement
308f0 61 74 69 6f 6e 73 20 66 6f 72 0a 2a 2a 20 65 61  ations for.** ea
30900 63 68 20 65 6e 63 6f 64 69 6e 67 2e 0a 2a 2a 20  ch encoding..** 
30910 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
30920 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
30930 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
30940 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
30950 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
30960 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
30970 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
30980 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
30990 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
309a0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 6f 75  ..**.** ^The fou
309b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 6d 61  rth parameter ma
309c0 79 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 62 65 20  y optionally be 
309d0 4f 52 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54  ORed with [SQLIT
309e0 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43 5d  E_DETERMINISTIC]
309f0 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 74 68  .** to signal th
30a00 61 74 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  at the function 
30a10 77 69 6c 6c 20 61 6c 77 61 79 73 20 72 65 74 75  will always retu
30a20 72 6e 20 74 68 65 20 73 61 6d 65 20 72 65 73 75  rn the same resu
30a30 6c 74 20 67 69 76 65 6e 0a 2a 2a 20 74 68 65 20  lt given.** the 
30a40 73 61 6d 65 20 69 6e 70 75 74 73 20 77 69 74 68  same inputs with
30a50 69 6e 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  in a single SQL 
30a60 73 74 61 74 65 6d 65 6e 74 2e 20 20 4d 6f 73 74  statement.  Most
30a70 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
30a80 72 65 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 69 73  re.** determinis
30a90 74 69 63 2e 20 20 54 68 65 20 62 75 69 6c 74 2d  tic.  The built-
30aa0 69 6e 20 5b 72 61 6e 64 6f 6d 28 29 5d 20 53 51  in [random()] SQ
30ab0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 6e  L function is an
30ac0 20 65 78 61 6d 70 6c 65 20 6f 66 20 61 0a 2a 2a   example of a.**
30ad0 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 69   function that i
30ae0 73 20 6e 6f 74 20 64 65 74 65 72 6d 69 6e 69 73  s not determinis
30af0 74 69 63 2e 20 20 54 68 65 20 53 51 4c 69 74 65  tic.  The SQLite
30b00 20 71 75 65 72 79 20 70 6c 61 6e 6e 65 72 20 69   query planner i
30b10 73 20 61 62 6c 65 20 74 6f 0a 2a 2a 20 70 65 72  s able to.** per
30b20 66 6f 72 6d 20 61 64 64 69 74 69 6f 6e 61 6c 20  form additional 
30b30 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 73 20 6f 6e  optimizations on
30b40 20 64 65 74 65 72 6d 69 6e 69 73 74 69 63 20 66   deterministic f
30b50 75 6e 63 74 69 6f 6e 73 2c 20 73 6f 20 75 73 65  unctions, so use
30b60 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 53 51 4c 49  .** of the [SQLI
30b70 54 45 5f 44 45 54 45 52 4d 49 4e 49 53 54 49 43  TE_DETERMINISTIC
30b80 5d 20 66 6c 61 67 20 69 73 20 72 65 63 6f 6d 6d  ] flag is recomm
30b90 65 6e 64 65 64 20 77 68 65 72 65 20 70 6f 73 73  ended where poss
30ba0 69 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ible..**.** ^(Th
30bb0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
30bc0 72 20 69 73 20 61 6e 20 61 72 62 69 74 72 61 72  r is an arbitrar
30bd0 79 20 70 6f 69 6e 74 65 72 2e 20 20 54 68 65 20  y pointer.  The 
30be0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30bf0 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  f the.** functio
30c00 6e 20 63 61 6e 20 67 61 69 6e 20 61 63 63 65 73  n can gain acces
30c10 73 20 74 6f 20 74 68 69 73 20 70 6f 69 6e 74 65  s to this pointe
30c20 72 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  r using [sqlite3
30c30 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2e 29 5e  _user_data()].)^
30c40 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 69 78 74  .**.** ^The sixt
30c50 68 2c 20 73 65 76 65 6e 74 68 20 61 6e 64 20 65  h, seventh and e
30c60 69 67 68 74 68 20 70 61 72 61 6d 65 74 65 72 73  ighth parameters
30c70 2c 20 78 46 75 6e 63 2c 20 78 53 74 65 70 20 61  , xFunc, xStep a
30c80 6e 64 20 78 46 69 6e 61 6c 2c 20 61 72 65 0a 2a  nd xFinal, are.*
30c90 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 43 2d  * pointers to C-
30ca0 6c 61 6e 67 75 61 67 65 20 66 75 6e 63 74 69 6f  language functio
30cb0 6e 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ns that implemen
30cc0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
30cd0 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61  on or.** aggrega
30ce0 74 65 2e 20 5e 41 20 73 63 61 6c 61 72 20 53 51  te. ^A scalar SQ
30cf0 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  L function requi
30d00 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e 74  res an implement
30d10 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 46 75  ation of the xFu
30d20 6e 63 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 6f  nc.** callback o
30d30 6e 6c 79 3b 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  nly; NULL pointe
30d40 72 73 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  rs must be passe
30d50 64 20 61 73 20 74 68 65 20 78 53 74 65 70 20 61  d as the xStep a
30d60 6e 64 20 78 46 69 6e 61 6c 0a 2a 2a 20 70 61 72  nd xFinal.** par
30d70 61 6d 65 74 65 72 73 2e 20 5e 41 6e 20 61 67 67  ameters. ^An agg
30d80 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74  regate SQL funct
30d90 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
30da0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
30db0 66 20 78 53 74 65 70 0a 2a 2a 20 61 6e 64 20 78  f xStep.** and x
30dc0 46 69 6e 61 6c 20 61 6e 64 20 4e 55 4c 4c 20 70  Final and NULL p
30dd0 6f 69 6e 74 65 72 20 6d 75 73 74 20 62 65 20 70  ointer must be p
30de0 61 73 73 65 64 20 66 6f 72 20 78 46 75 6e 63 2e  assed for xFunc.
30df0 20 5e 54 6f 20 64 65 6c 65 74 65 20 61 6e 20 65   ^To delete an e
30e00 78 69 73 74 69 6e 67 0a 2a 2a 20 53 51 4c 20 66  xisting.** SQL f
30e10 75 6e 63 74 69 6f 6e 20 6f 72 20 61 67 67 72 65  unction or aggre
30e20 67 61 74 65 2c 20 70 61 73 73 20 4e 55 4c 4c 20  gate, pass NULL 
30e30 70 6f 69 6e 74 65 72 73 20 66 6f 72 20 61 6c 6c  pointers for all
30e40 20 74 68 72 65 65 20 66 75 6e 63 74 69 6f 6e 0a   three function.
30e50 2a 2a 20 63 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a  ** callbacks..**
30e60 0a 2a 2a 20 5e 28 49 66 20 74 68 65 20 6e 69 6e  .** ^(If the nin
30e70 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
30e80 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
30e90 75 6e 63 74 69 6f 6e 5f 76 32 28 29 20 69 73 20  unction_v2() is 
30ea0 6e 6f 74 20 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65  not NULL,.** the
30eb0 6e 20 69 74 20 69 73 20 64 65 73 74 72 75 63 74  n it is destruct
30ec0 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c 69  or for the appli
30ed0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
30ee0 74 65 72 2e 20 0a 2a 2a 20 54 68 65 20 64 65 73  ter. .** The des
30ef0 74 72 75 63 74 6f 72 20 69 73 20 69 6e 76 6f 6b  tructor is invok
30f00 65 64 20 77 68 65 6e 20 74 68 65 20 66 75 6e 63  ed when the func
30f10 74 69 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2c  tion is deleted,
30f20 20 65 69 74 68 65 72 20 62 79 20 62 65 69 6e 67   either by being
30f30 0a 2a 2a 20 6f 76 65 72 6c 6f 61 64 65 64 20 6f  .** overloaded o
30f40 72 20 77 68 65 6e 20 74 68 65 20 64 61 74 61 62  r when the datab
30f50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63  ase connection c
30f60 6c 6f 73 65 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65  loses.)^.** ^The
30f70 20 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 61   destructor is a
30f80 6c 73 6f 20 69 6e 76 6f 6b 65 64 20 69 66 20 74  lso invoked if t
30f90 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  he call to.** sq
30fa0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
30fb0 63 74 69 6f 6e 5f 76 32 28 29 20 66 61 69 6c 73  ction_v2() fails
30fc0 2e 0a 2a 2a 20 5e 57 68 65 6e 20 74 68 65 20 64  ..** ^When the d
30fd0 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
30fe0 63 6b 20 6f 66 20 74 68 65 20 74 65 6e 74 68 20  ck of the tenth 
30ff0 70 61 72 61 6d 65 74 65 72 20 69 73 20 69 6e 76  parameter is inv
31000 6f 6b 65 64 2c 20 69 74 0a 2a 2a 20 69 73 20 70  oked, it.** is p
31010 61 73 73 65 64 20 61 20 73 69 6e 67 6c 65 20 61  assed a single a
31020 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
31030 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 61   a copy of the a
31040 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
31050 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63  .** pointer whic
31060 68 20 77 61 73 20 74 68 65 20 66 69 66 74 68 20  h was the fifth 
31070 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
31080 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
31090 74 69 6f 6e 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a  tion_v2()..**.**
310a0 20 5e 49 74 20 69 73 20 70 65 72 6d 69 74 74 65   ^It is permitte
310b0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 6d 75  d to register mu
310c0 6c 74 69 70 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  ltiple implement
310d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
310e0 6d 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  me.** functions 
310f0 77 69 74 68 20 74 68 65 20 73 61 6d 65 20 6e 61  with the same na
31100 6d 65 20 62 75 74 20 77 69 74 68 20 65 69 74 68  me but with eith
31110 65 72 20 64 69 66 66 65 72 69 6e 67 20 6e 75 6d  er differing num
31120 62 65 72 73 20 6f 66 0a 2a 2a 20 61 72 67 75 6d  bers of.** argum
31130 65 6e 74 73 20 6f 72 20 64 69 66 66 65 72 69 6e  ents or differin
31140 67 20 70 72 65 66 65 72 72 65 64 20 74 65 78 74  g preferred text
31150 20 65 6e 63 6f 64 69 6e 67 73 2e 20 20 5e 53 51   encodings.  ^SQ
31160 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a  Lite will use.**
31170 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
31180 69 6f 6e 20 74 68 61 74 20 6d 6f 73 74 20 63 6c  ion that most cl
31190 6f 73 65 6c 79 20 6d 61 74 63 68 65 73 20 74 68  osely matches th
311a0 65 20 77 61 79 20 69 6e 20 77 68 69 63 68 20 74  e way in which t
311b0 68 65 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69  he.** SQL functi
311c0 6f 6e 20 69 73 20 75 73 65 64 2e 20 20 5e 41 20  on is used.  ^A 
311d0 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
311e0 6e 74 61 74 69 6f 6e 20 77 69 74 68 20 61 20 6e  ntation with a n
311f0 6f 6e 2d 6e 65 67 61 74 69 76 65 0a 2a 2a 20 6e  on-negative.** n
31200 41 72 67 20 70 61 72 61 6d 65 74 65 72 20 69 73  Arg parameter is
31210 20 61 20 62 65 74 74 65 72 20 6d 61 74 63 68 20   a better match 
31220 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20  than a function 
31230 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77  implementation w
31240 69 74 68 0a 2a 2a 20 61 20 6e 65 67 61 74 69 76  ith.** a negativ
31250 65 20 6e 41 72 67 2e 20 20 5e 41 20 66 75 6e 63  e nArg.  ^A func
31260 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 70  tion where the p
31270 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31280 63 6f 64 69 6e 67 0a 2a 2a 20 6d 61 74 63 68 65  coding.** matche
31290 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  s the database e
312a0 6e 63 6f 64 69 6e 67 20 69 73 20 61 20 62 65 74  ncoding is a bet
312b0 74 65 72 0a 2a 2a 20 6d 61 74 63 68 20 74 68 61  ter.** match tha
312c0 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
312d0 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
312e0 69 73 20 64 69 66 66 65 72 65 6e 74 2e 20 20 0a  is different.  .
312f0 2a 2a 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77  ** ^A function w
31300 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e  here the encodin
31310 67 20 64 69 66 66 65 72 65 6e 63 65 20 69 73 20  g difference is 
31320 62 65 74 77 65 65 6e 20 55 54 46 31 36 6c 65 20  between UTF16le 
31330 61 6e 64 20 55 54 46 31 36 62 65 0a 2a 2a 20 69  and UTF16be.** i
31340 73 20 61 20 63 6c 6f 73 65 72 20 6d 61 74 63 68  s a closer match
31350 20 74 68 61 6e 20 61 20 66 75 6e 63 74 69 6f 6e   than a function
31360 20 77 68 65 72 65 20 74 68 65 20 65 6e 63 6f 64   where the encod
31370 69 6e 67 20 64 69 66 66 65 72 65 6e 63 65 20 69  ing difference i
31380 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20 55 54 46  s.** between UTF
31390 38 20 61 6e 64 20 55 54 46 31 36 2e 0a 2a 2a 0a  8 and UTF16..**.
313a0 2a 2a 20 5e 42 75 69 6c 74 2d 69 6e 20 66 75 6e  ** ^Built-in fun
313b0 63 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 6f 76  ctions may be ov
313c0 65 72 6c 6f 61 64 65 64 20 62 79 20 6e 65 77 20  erloaded by new 
313d0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
313e0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a  ned functions..*
313f0 2a 0a 2a 2a 20 5e 41 6e 20 61 70 70 6c 69 63 61  *.** ^An applica
31400 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31410 63 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74  ction is permitt
31420 65 64 20 74 6f 20 63 61 6c 6c 20 6f 74 68 65 72  ed to call other
31430 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72  .** SQLite inter
31440 66 61 63 65 73 2e 20 20 48 6f 77 65 76 65 72 2c  faces.  However,
31450 20 73 75 63 68 20 63 61 6c 6c 73 20 6d 75 73 74   such calls must
31460 20 6e 6f 74 0a 2a 2a 20 63 6c 6f 73 65 20 74 68   not.** close th
31470 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
31480 63 74 69 6f 6e 20 6e 6f 72 20 66 69 6e 61 6c 69  ction nor finali
31490 7a 65 20 6f 72 20 72 65 73 65 74 20 74 68 65 20  ze or reset the 
314a0 70 72 65 70 61 72 65 64 0a 2a 2a 20 73 74 61 74  prepared.** stat
314b0 65 6d 65 6e 74 20 69 6e 20 77 68 69 63 68 20 74  ement in which t
314c0 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  he function is r
314d0 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73  unning..*/.int s
314e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
314f0 6e 63 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  nction(.  sqlite
31500 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63  3 *db,.  const c
31510 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61  har *zFunctionNa
31520 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a  me,.  int nArg,.
31530 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a    int eTextRep,.
31540 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20    void *pApp,.  
31550 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71  void (*xFunc)(sq
31560 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
31570 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
31580 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53  **),.  void (*xS
31590 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  tep)(sqlite3_con
315a0 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65  text*,int,sqlite
315b0 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f  3_value**),.  vo
315c0 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c  id (*xFinal)(sql
315d0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a 29  ite3_context*).)
315e0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72  ;.int sqlite3_cr
315f0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28  eate_function16(
31600 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
31610 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 46    const void *zF
31620 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
31630 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
31640 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
31650 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
31660 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
31670 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
31680 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
31690 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
316a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
316b0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
316c0 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
316d0 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
316e0 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
316f0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
31700 6e 63 74 69 6f 6e 5f 76 32 28 0a 20 20 73 71 6c  nction_v2(.  sql
31710 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73  ite3 *db,.  cons
31720 74 20 63 68 61 72 20 2a 7a 46 75 6e 63 74 69 6f  t char *zFunctio
31730 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72  nName,.  int nAr
31740 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65  g,.  int eTextRe
31750 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c  p,.  void *pApp,
31760 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29  .  void (*xFunc)
31770 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
31780 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
31790 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
317a0 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f  *xStep)(sqlite3_
317b0 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
317c0 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
317d0 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28   void (*xFinal)(
317e0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
317f0 29 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74  ),.  void(*xDest
31800 72 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a  roy)(void*).);..
31810 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
31820 54 65 78 74 20 45 6e 63 6f 64 69 6e 67 73 0a 2a  Text Encodings.*
31830 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
31840 61 6e 74 20 64 65 66 69 6e 65 20 69 6e 74 65 67  ant define integ
31850 65 72 20 63 6f 64 65 73 20 74 68 61 74 20 72 65  er codes that re
31860 70 72 65 73 65 6e 74 20 74 68 65 20 76 61 72 69  present the vari
31870 6f 75 73 0a 2a 2a 20 74 65 78 74 20 65 6e 63 6f  ous.** text enco
31880 64 69 6e 67 73 20 73 75 70 70 6f 72 74 65 64 20  dings supported 
31890 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64  by SQLite..*/.#d
318a0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
318b0 38 20 20 20 20 20 20 20 20 20 20 20 31 0a 23 64  8           1.#d
318c0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
318d0 31 36 4c 45 20 20 20 20 20 20 20 20 32 0a 23 64  16LE        2.#d
318e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
318f0 31 36 42 45 20 20 20 20 20 20 20 20 33 0a 23 64  16BE        3.#d
31900 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46  efine SQLITE_UTF
31910 31 36 20 20 20 20 20 20 20 20 20 20 34 20 20 20  16          4   
31920 20 2f 2a 20 55 73 65 20 6e 61 74 69 76 65 20 62   /* Use native b
31930 79 74 65 20 6f 72 64 65 72 20 2a 2f 0a 23 64 65  yte order */.#de
31940 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 59 20  fine SQLITE_ANY 
31950 20 20 20 20 20 20 20 20 20 20 20 35 20 20 20 20             5    
31960 2f 2a 20 44 65 70 72 65 63 61 74 65 64 20 2a 2f  /* Deprecated */
31970 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
31980 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38  UTF16_ALIGNED  8
31990 20 20 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63      /* sqlite3_c
319a0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20  reate_collation 
319b0 6f 6e 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43  only */../*.** C
319c0 41 50 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f  API3REF: Functio
319d0 6e 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 54 68  n Flags.**.** Th
319e0 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 6d 61  ese constants ma
319f0 79 20 62 65 20 4f 52 65 64 20 74 6f 67 65 74 68  y be ORed togeth
31a00 65 72 20 77 69 74 68 20 74 68 65 20 0a 2a 2a 20  er with the .** 
31a10 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20 70  [SQLITE_UTF8 | p
31a20 72 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e  referred text en
31a30 63 6f 64 69 6e 67 5d 20 61 73 20 74 68 65 20 66  coding] as the f
31a40 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a  ourth argument.*
31a50 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72  * to [sqlite3_cr
31a60 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d  eate_function()]
31a70 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  , [sqlite3_creat
31a80 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 2c  e_function16()],
31a90 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
31aa0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
31ab0 76 32 28 29 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e  v2()]..*/.#defin
31ac0 65 20 53 51 4c 49 54 45 5f 44 45 54 45 52 4d 49  e SQLITE_DETERMI
31ad0 4e 49 53 54 49 43 20 20 20 20 30 78 38 30 30 0a  NISTIC    0x800.
31ae0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
31af0 20 44 65 70 72 65 63 61 74 65 64 20 46 75 6e 63   Deprecated Func
31b00 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45 43 41  tions.** DEPRECA
31b10 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  TED.**.** These 
31b20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20 5b 64  functions are [d
31b30 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49 6e 20  eprecated].  In 
31b40 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74 61 69  order to maintai
31b50 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  n.** backwards c
31b60 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77 69 74  ompatibility wit
31b70 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20 74 68  h older code, th
31b80 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 63 6f  ese functions co
31b90 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20 62 65  ntinue .** to be
31ba0 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48 6f 77   supported.  How
31bb0 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c 69 63  ever, new applic
31bc0 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 61 76  ations should av
31bd0 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65 20 6f  oid.** the use o
31be0 66 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  f these function
31bf0 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e 63 6f  s.  To help enco
31c00 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74 6f 20  urage people to 
31c10 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67 20 74  avoid.** using t
31c20 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 2c 20  hese functions, 
31c30 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69 6e 67  we are not going
31c40 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77 68 61   to tell you wha
31c50 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a 23 69  t they do..*/.#i
31c60 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d 49  fndef SQLITE_OMI
31c70 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53 51 4c  T_DEPRECATED.SQL
31c80 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69  ITE_DEPRECATED i
31c90 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  nt sqlite3_aggre
31ca0 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c 69 74  gate_count(sqlit
31cb0 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 53 51  e3_context*);.SQ
31cc0 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
31cd0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 70 69  int sqlite3_expi
31ce0 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  red(sqlite3_stmt
31cf0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
31d00 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
31d10 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e 64 69  3_transfer_bindi
31d20 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
31d30 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  *, sqlite3_stmt*
31d40 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  );.SQLITE_DEPREC
31d50 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
31d60 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65 72 28  _global_recover(
31d70 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f 44 45  void);.SQLITE_DE
31d80 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
31d90 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63 6c 65  lite3_thread_cle
31da0 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51 4c 49  anup(void);.SQLI
31db0 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e  TE_DEPRECATED in
31dc0 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  t sqlite3_memory
31dd0 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29 28 76  _alarm(void(*)(v
31de0 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
31df0 36 34 2c 69 6e 74 29 2c 0a 20 20 20 20 20 20 20  64,int),.       
31e00 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 76                 v
31e10 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74  oid*,sqlite3_int
31e20 36 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a  64);.#endif../*.
31e30 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74  ** CAPI3REF: Obt
31e40 61 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74  aining SQL Funct
31e50 69 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61  ion Parameter Va
31e60 6c 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43  lues.**.** The C
31e70 2d 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d  -language implem
31e80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20  entation of SQL 
31e90 66 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67  functions and ag
31ea0 67 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a  gregates uses.**
31eb0 20 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74   this set of int
31ec0 65 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20  erface routines 
31ed0 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61  to access the pa
31ee0 72 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f  rameter values o
31ef0 6e 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f  n.** the functio
31f00 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a  n or aggregate..
31f10 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20  **.** The xFunc 
31f20 28 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63  (for scalar func
31f30 74 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20  tions) or xStep 
31f40 28 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29  (for aggregates)
31f50 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74   parameters.** t
31f60 6f 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  o [sqlite3_creat
31f70 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e  e_function()] an
31f80 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
31f90 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a  e_function16()].
31fa0 2a 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61  ** define callba
31fb0 63 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65  cks that impleme
31fc0 6e 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  nt the SQL funct
31fd0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
31fe0 74 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20  tes..** The 3rd 
31ff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
32000 73 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20  se callbacks is 
32010 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e  an array of poin
32020 74 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74  ters to.** [prot
32030 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61  ected sqlite3_va
32040 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54  lue] objects.  T
32050 68 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c  here is one [sql
32060 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32070 63 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70  ct for.** each p
32080 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
32090 53 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54  SQL function.  T
320a0 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72  hese routines ar
320b0 65 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74  e used to.** ext
320c0 72 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d  ract values from
320d0 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61   the [sqlite3_va
320e0 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a  lue] objects..**
320f0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
32100 65 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74  es work only wit
32110 68 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  h [protected sql
32120 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
32130 63 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65  cts..** Any atte
32140 6d 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65  mpt to use these
32150 20 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20   routines on an 
32160 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c  [unprotected sql
32170 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f  ite3_value].** o
32180 62 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e  bject results in
32190 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76   undefined behav
321a0 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  ior..**.** ^Thes
321b0 65 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20  e routines work 
321c0 6a 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f  just like the co
321d0 72 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c  rresponding [col
321e0 75 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74  umn access funct
321f0 69 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20  ions].** except 
32200 74 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74  that  these rout
32210 69 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67  ines take a sing
32220 6c 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71  le [protected sq
32230 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
32240 65 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69  ect.** pointer i
32250 6e 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c  nstead of a [sql
32260 69 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e  ite3_stmt*] poin
32270 74 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67  ter and an integ
32280 65 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72  er column number
32290 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
322a0 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
322b0 36 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78  6() interface ex
322c0 74 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20  tracts a UTF-16 
322d0 73 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65  string.** in the
322e0 20 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64   native byte-ord
322f0 65 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d  er of the host m
32300 61 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a  achine.  ^The.**
32310 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74   sqlite3_value_t
32320 65 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71  ext16be() and sq
32330 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32340 31 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65  16le() interface
32350 73 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46  s.** extract UTF
32360 2d 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62  -16 strings as b
32370 69 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69  ig-endian and li
32380 74 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70  ttle-endian resp
32390 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ectively..**.** 
323a0 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61  ^(The sqlite3_va
323b0 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65  lue_numeric_type
323c0 28 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74  () interface att
323d0 65 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a  empts to apply.*
323e0 2a 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69  * numeric affini
323f0 74 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e  ty to the value.
32400 20 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61    This means tha
32410 74 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a  t an attempt is.
32420 2a 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65  ** made to conve
32430 72 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20  rt the value to 
32440 61 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c  an integer or fl
32450 6f 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49  oating point.  I
32460 66 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76  f.** such a conv
32470 65 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62  ersion is possib
32480 6c 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20  le without loss 
32490 6f 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28  of information (
324a0 69 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64  in other.** word
324b0 73 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20  s, if the value 
324c0 69 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74  is a string that
324d0 20 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75   looks like a nu
324e0 6d 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68  mber).** then th
324f0 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20  e conversion is 
32500 70 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65  performed.  Othe
32510 72 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73  rwise no convers
32520 69 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54  ion occurs..** T
32530 68 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47  he [SQLITE_INTEG
32540 45 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61  ER | datatype] a
32550 66 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20  fter conversion 
32560 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a  is returned.)^.*
32570 2a 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20  *.** Please pay 
32580 70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e  particular atten
32590 74 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74  tion to the fact
325a0 20 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65   that the pointe
325b0 72 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72  r returned.** fr
325c0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  om [sqlite3_valu
325d0 65 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69  e_blob()], [sqli
325e0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29  te3_value_text()
325f0 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
32600 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29  3_value_text16()
32610 5d 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64  ] can be invalid
32620 61 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71  ated by a subseq
32630 75 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  uent call to.** 
32640 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62  [sqlite3_value_b
32650 79 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65  ytes()], [sqlite
32660 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
32670 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
32680 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f  ue_text()],.** o
32690 72 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  r [sqlite3_value
326a0 5f 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a  _text16()]..**.*
326b0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
326c0 20 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20   must be called 
326d0 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68  from the same th
326e0 72 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53  read as.** the S
326f0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74  QL function that
32700 20 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73   supplied the [s
32710 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70  qlite3_value*] p
32720 61 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f  arameters..*/.co
32730 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
32740 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c  3_value_blob(sql
32750 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
32760 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
32770 62 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61  bytes(sqlite3_va
32780 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
32790 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36  e3_value_bytes16
327a0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
327b0 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33  ;.double sqlite3
327c0 5f 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71  _value_double(sq
327d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
327e0 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
327f0 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c  _int(sqlite3_val
32800 75 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e  ue*);.sqlite3_in
32810 74 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64 sqlite3_valu
32820 65 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  e_int64(sqlite3_
32830 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75  value*);.const u
32840 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
32850 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32860 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
32870 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
32880 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
32890 31 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  16(sqlite3_value
328a0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
328b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
328c0 78 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76  xt16le(sqlite3_v
328d0 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f  alue*);.const vo
328e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75  id *sqlite3_valu
328f0 65 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74  e_text16be(sqlit
32900 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20  e3_value*);.int 
32910 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
32920 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32930 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  *);.int sqlite3_
32940 76 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79  value_numeric_ty
32950 70 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  pe(sqlite3_value
32960 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
32970 52 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72  REF: Obtain Aggr
32980 65 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43  egate Function C
32990 6f 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70  ontext.**.** Imp
329a0 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20  lementations of 
329b0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
329c0 6e 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73  nctions use this
329d0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61  .** routine to a
329e0 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66  llocate memory f
329f0 6f 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72  or storing their
32a00 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54   state..**.** ^T
32a10 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68  he first time th
32a20 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  e sqlite3_aggreg
32a30 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32a40 20 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c   routine is call
32a50 65 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72  ed .** for a par
32a60 74 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74  ticular aggregat
32a70 65 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69  e function, SQLi
32a80 74 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20  te.** allocates 
32a90 4e 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72  N of memory, zer
32aa0 6f 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d  oes out that mem
32ab0 6f 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73  ory, and returns
32ac0 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f   a pointer.** to
32ad0 20 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e   the new memory.
32ae0 20 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20   ^On second and 
32af0 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
32b00 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61   to.** sqlite3_a
32b10 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
32b20 28 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20  () for the same 
32b30 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
32b40 6f 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20  on instance,.** 
32b50 74 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20  the same buffer 
32b60 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71  is returned.  Sq
32b70 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
32b80 63 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72  context() is nor
32b90 6d 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20  mally.** called 
32ba0 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e  once for each in
32bb0 76 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20  vocation of the 
32bc0 78 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61  xStep callback a
32bd0 6e 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c  nd then one.** l
32be0 61 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68  ast time when th
32bf0 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  e xFinal callbac
32c00 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e  k is invoked.  ^
32c10 28 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61  (When no rows ma
32c20 74 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67  tch.** an aggreg
32c30 61 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78  ate query, the x
32c40 53 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20  Step() callback 
32c50 6f 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65  of the aggregate
32c60 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70   function.** imp
32c70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e  lementation is n
32c80 65 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20  ever called and 
32c90 78 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c  xFinal() is call
32ca0 65 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e  ed exactly once.
32cb0 0a 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73  .** In those cas
32cc0 65 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72  es, sqlite3_aggr
32cd0 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20  egate_context() 
32ce0 6d 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20  might be called 
32cf0 66 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74  for the.** first
32d00 20 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69   time from withi
32d10 6e 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a  n xFinal().)^.**
32d20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
32d30 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
32d40 78 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20  xt(C,N) routine 
32d50 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
32d60 6f 69 6e 74 65 72 20 0a 2a 2a 20 77 68 65 6e 20  ointer .** when 
32d70 66 69 72 73 74 20 63 61 6c 6c 65 64 20 69 66 20  first called if 
32d80 4e 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 6f  N is less than o
32d90 72 20 65 71 75 61 6c 20 74 6f 20 7a 65 72 6f 20  r equal to zero 
32da0 6f 72 20 69 66 20 61 20 6d 65 6d 6f 72 79 0a 2a  or if a memory.*
32db0 2a 20 61 6c 6c 6f 63 61 74 65 20 65 72 72 6f 72  * allocate error
32dc0 20 6f 63 63 75 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e   occurs..**.** ^
32dd0 28 54 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 73  (The amount of s
32de0 70 61 63 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  pace allocated b
32df0 79 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  y sqlite3_aggreg
32e00 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29  ate_context(C,N)
32e10 20 69 73 0a 2a 2a 20 64 65 74 65 72 6d 69 6e 65   is.** determine
32e20 64 20 62 79 20 74 68 65 20 4e 20 70 61 72 61 6d  d by the N param
32e30 65 74 65 72 20 6f 6e 20 66 69 72 73 74 20 73 75  eter on first su
32e40 63 63 65 73 73 66 75 6c 20 63 61 6c 6c 2e 20 20  ccessful call.  
32e50 43 68 61 6e 67 69 6e 67 20 74 68 65 0a 2a 2a 20  Changing the.** 
32e60 76 61 6c 75 65 20 6f 66 20 4e 20 69 6e 20 73 75  value of N in su
32e70 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f  bsequent call to
32e80 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
32e90 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 77 69 74  te_context() wit
32ea0 68 69 6e 0a 2a 2a 20 74 68 65 20 73 61 6d 65 20  hin.** the same 
32eb0 61 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69  aggregate functi
32ec0 6f 6e 20 69 6e 73 74 61 6e 63 65 20 77 69 6c 6c  on instance will
32ed0 20 6e 6f 74 20 72 65 73 69 7a 65 20 74 68 65 20   not resize the 
32ee0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
32ef0 74 69 6f 6e 2e 29 5e 20 20 57 69 74 68 69 6e 20  tion.)^  Within 
32f00 74 68 65 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62  the xFinal callb
32f10 61 63 6b 2c 20 69 74 20 69 73 20 63 75 73 74 6f  ack, it is custo
32f20 6d 61 72 79 20 74 6f 20 73 65 74 0a 2a 2a 20 4e  mary to set.** N
32f30 3d 30 20 69 6e 20 63 61 6c 6c 73 20 74 6f 20 73  =0 in calls to s
32f40 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32f50 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 73 6f  _context(C,N) so
32f60 20 74 68 61 74 20 6e 6f 20 0a 2a 2a 20 70 6f 69   that no .** poi
32f70 6e 74 6c 65 73 73 20 6d 65 6d 6f 72 79 20 61 6c  ntless memory al
32f80 6c 6f 63 61 74 69 6f 6e 73 20 6f 63 63 75 72 2e  locations occur.
32f90 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
32fa0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
32fb0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
32fc0 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
32fd0 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
32fe0 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
32ff0 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
33000 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
33010 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
33020 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
33030 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
33040 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
33050 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
33060 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
33070 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
33080 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
33090 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
330a0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
330b0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
330c0 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
330d0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
330e0 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
330f0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
33100 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
33110 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
33120 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
33130 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
33140 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
33150 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
33160 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
33170 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
33180 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
33190 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
331a0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
331b0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
331c0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
331d0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
331e0 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
331f0 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
33200 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
33210 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
33220 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
33230 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
33240 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
33250 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
33260 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
33270 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
33280 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
33290 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
332a0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
332b0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
332c0 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
332d0 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
332e0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
332f0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
33300 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
33310 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
33320 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
33330 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
33340 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
33350 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
33360 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
33370 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
33380 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
33390 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
333a0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
333b0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
333c0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
333d0 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
333e0 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
333f0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
33400 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
33410 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
33420 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
33430 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
33440 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
33450 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
33460 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
33470 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
33480 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
33490 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
334a0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
334b0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
334c0 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
334d0 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
334e0 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
334f0 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
33500 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
33510 2a 0a 2a 2a 20 54 68 65 73 65 20 66 75 6e 63 74  *.** These funct
33520 69 6f 6e 73 20 6d 61 79 20 62 65 20 75 73 65 64  ions may be used
33530 20 62 79 20 28 6e 6f 6e 2d 61 67 67 72 65 67 61   by (non-aggrega
33540 74 65 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  te) SQL function
33550 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
33560 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
33570 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
33580 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
33590 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
335a0 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
335b0 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
335c0 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
335d0 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
335e0 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
335f0 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
33600 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
33610 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
33620 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 20   be preserved.  
33630 41 6e 20 65 78 61 6d 70 6c 65 0a 2a 2a 20 6f 66  An example.** of
33640 20 77 68 65 72 65 20 74 68 69 73 20 6d 69 67 68   where this migh
33650 74 20 62 65 20 75 73 65 66 75 6c 20 69 73 20 69  t be useful is i
33660 6e 20 61 20 72 65 67 75 6c 61 72 2d 65 78 70 72  n a regular-expr
33670 65 73 73 69 6f 6e 20 6d 61 74 63 68 69 6e 67 0a  ession matching.
33680 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
33690 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
336a0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
336b0 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20   expression can 
336c0 62 65 20 73 74 6f 72 65 64 20 61 73 0a 2a 2a 20  be stored as.** 
336d0 6d 65 74 61 64 61 74 61 20 61 73 73 6f 63 69 61  metadata associa
336e0 74 65 64 20 77 69 74 68 20 74 68 65 20 70 61 74  ted with the pat
336f0 74 65 72 6e 20 73 74 72 69 6e 67 2e 20 20 0a 2a  tern string.  .*
33700 2a 20 54 68 65 6e 20 61 73 20 6c 6f 6e 67 20 61  * Then as long a
33710 73 20 74 68 65 20 70 61 74 74 65 72 6e 20 73 74  s the pattern st
33720 72 69 6e 67 20 72 65 6d 61 69 6e 73 20 74 68 65  ring remains the
33730 20 73 61 6d 65 2c 0a 2a 2a 20 74 68 65 20 63 6f   same,.** the co
33740 6d 70 69 6c 65 64 20 72 65 67 75 6c 61 72 20 65  mpiled regular e
33750 78 70 72 65 73 73 69 6f 6e 20 63 61 6e 20 62 65  xpression can be
33760 20 72 65 75 73 65 64 20 6f 6e 20 6d 75 6c 74 69   reused on multi
33770 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ple.** invocatio
33780 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 20 66  ns of the same f
33790 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  unction..**.** ^
337a0 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
337b0 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
337c0 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
337d0 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
337e0 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
337f0 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
33800 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
33810 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
33820 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
33830 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
33840 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
33850 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
33860 66 20 74 68 65 72 65 20 69 73 20 6e 6f 20 6d 65  f there is no me
33870 74 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69  tadata.** associ
33880 61 74 65 64 20 77 69 74 68 20 74 68 65 20 66 75  ated with the fu
33890 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2c  nction argument,
338a0 20 74 68 69 73 20 73 71 6c 69 74 65 33 5f 67 65   this sqlite3_ge
338b0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
338c0 72 66 61 63 65 0a 2a 2a 20 72 65 74 75 72 6e 73  rface.** returns
338d0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
338e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
338f0 74 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28  te3_set_auxdata(
33900 43 2c 4e 2c 50 2c 58 29 20 69 6e 74 65 72 66 61  C,N,P,X) interfa
33910 63 65 20 73 61 76 65 73 20 50 20 61 73 20 6d 65  ce saves P as me
33920 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20 4e  tadata for the N
33930 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  -th.** argument 
33940 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
33950 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
33960 69 6f 6e 2e 20 20 5e 53 75 62 73 65 71 75 65 6e  ion.  ^Subsequen
33970 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
33980 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
33990 61 28 43 2c 4e 29 20 72 65 74 75 72 6e 20 50 20  a(C,N) return P 
339a0 66 72 6f 6d 20 74 68 65 20 6d 6f 73 74 20 72 65  from the most re
339b0 63 65 6e 74 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cent.** sqlite3_
339c0 73 65 74 5f 61 75 78 64 61 74 61 28 43 2c 4e 2c  set_auxdata(C,N,
339d0 50 2c 58 29 20 63 61 6c 6c 20 69 66 20 74 68 65  P,X) call if the
339e0 20 6d 65 74 61 64 61 74 61 20 69 73 20 73 74 69   metadata is sti
339f0 6c 6c 20 76 61 6c 69 64 20 6f 72 0a 2a 2a 20 4e  ll valid or.** N
33a00 55 4c 4c 20 69 66 20 74 68 65 20 6d 65 74 61 64  ULL if the metad
33a10 61 74 61 20 68 61 73 20 62 65 65 6e 20 64 69 73  ata has been dis
33a20 63 61 72 64 65 64 2e 0a 2a 2a 20 5e 41 66 74 65  carded..** ^Afte
33a30 72 20 65 61 63 68 20 63 61 6c 6c 20 74 6f 20 73  r each call to s
33a40 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64 61  qlite3_set_auxda
33a50 74 61 28 43 2c 4e 2c 50 2c 58 29 20 77 68 65 72  ta(C,N,P,X) wher
33a60 65 20 58 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  e X is not NULL,
33a70 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
33a80 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
33a90 75 63 74 6f 72 20 66 75 6e 63 74 69 6f 6e 20 58  uctor function X
33aa0 20 77 69 74 68 20 70 61 72 61 6d 65 74 65 72 20   with parameter 
33ab0 50 20 65 78 61 63 74 6c 79 0a 2a 2a 20 6f 6e 63  P exactly.** onc
33ac0 65 2c 20 77 68 65 6e 20 74 68 65 20 6d 65 74 61  e, when the meta
33ad0 64 61 74 61 20 69 73 20 64 69 73 63 61 72 64 65  data is discarde
33ae0 64 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20  d..** SQLite is 
33af0 66 72 65 65 20 74 6f 20 64 69 73 63 61 72 64 20  free to discard 
33b00 74 68 65 20 6d 65 74 61 64 61 74 61 20 61 74 20  the metadata at 
33b10 61 6e 79 20 74 69 6d 65 2c 20 69 6e 63 6c 75 64  any time, includ
33b20 69 6e 67 3a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ing: <ul>.** <li
33b30 3e 20 77 68 65 6e 20 74 68 65 20 63 6f 72 72 65  > when the corre
33b40 73 70 6f 6e 64 69 6e 67 20 66 75 6e 63 74 69 6f  sponding functio
33b50 6e 20 70 61 72 61 6d 65 74 65 72 20 63 68 61 6e  n parameter chan
33b60 67 65 73 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20  ges, or.** <li> 
33b70 77 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65  when [sqlite3_re
33b80 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  set()] or [sqlit
33b90 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
33ba0 73 20 63 61 6c 6c 65 64 20 66 6f 72 20 74 68 65  s called for the
33bb0 0a 2a 2a 20 20 20 20 20 20 53 51 4c 20 73 74 61  .**      SQL sta
33bc0 74 65 6d 65 6e 74 2c 20 6f 72 0a 2a 2a 20 3c 6c  tement, or.** <l
33bd0 69 3e 20 77 68 65 6e 20 73 71 6c 69 74 65 33 5f  i> when sqlite3_
33be0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 69 73  set_auxdata() is
33bf0 20 69 6e 76 6f 6b 65 64 20 61 67 61 69 6e 20 6f   invoked again o
33c00 6e 20 74 68 65 20 73 61 6d 65 20 70 61 72 61 6d  n the same param
33c10 65 74 65 72 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e  eter, or.** <li>
33c20 20 64 75 72 69 6e 67 20 74 68 65 20 6f 72 69 67   during the orig
33c30 69 6e 61 6c 20 73 71 6c 69 74 65 33 5f 73 65 74  inal sqlite3_set
33c40 5f 61 75 78 64 61 74 61 28 29 20 63 61 6c 6c 20  _auxdata() call 
33c50 77 68 65 6e 20 61 20 6d 65 6d 6f 72 79 20 0a 2a  when a memory .*
33c60 2a 20 20 20 20 20 20 61 6c 6c 6f 63 61 74 69 6f  *      allocatio
33c70 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 20  n error occurs. 
33c80 3c 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 4e 6f  </ul>)^.**.** No
33c90 74 65 20 74 68 65 20 6c 61 73 74 20 62 75 6c 6c  te the last bull
33ca0 65 74 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  et in particular
33cb0 2e 20 20 54 68 65 20 64 65 73 74 72 75 63 74 6f  .  The destructo
33cc0 72 20 58 20 69 6e 20 0a 2a 2a 20 73 71 6c 69 74  r X in .** sqlit
33cd0 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 43  e3_set_auxdata(C
33ce0 2c 4e 2c 50 2c 58 29 20 6d 69 67 68 74 20 62 65  ,N,P,X) might be
33cf0 20 63 61 6c 6c 65 64 20 69 6d 6d 65 64 69 61 74   called immediat
33d00 65 6c 79 2c 20 62 65 66 6f 72 65 20 74 68 65 0a  ely, before the.
33d10 2a 2a 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  ** sqlite3_set_a
33d20 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
33d30 63 65 20 65 76 65 6e 20 72 65 74 75 72 6e 73 2e  ce even returns.
33d40 20 20 48 65 6e 63 65 20 73 71 6c 69 74 65 33 5f    Hence sqlite3_
33d50 73 65 74 5f 61 75 78 64 61 74 61 28 29 0a 2a 2a  set_auxdata().**
33d60 20 73 68 6f 75 6c 64 20 62 65 20 63 61 6c 6c 65   should be calle
33d70 64 20 6e 65 61 72 20 74 68 65 20 65 6e 64 20 6f  d near the end o
33d80 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
33d90 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 61 6e  mplementation an
33da0 64 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f  d the.** functio
33db0 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
33dc0 20 73 68 6f 75 6c 64 20 6e 6f 74 20 6d 61 6b 65   should not make
33dd0 20 61 6e 79 20 75 73 65 20 6f 66 20 50 20 61 66   any use of P af
33de0 74 65 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ter.** sqlite3_s
33df0 65 74 5f 61 75 78 64 61 74 61 28 29 20 68 61 73  et_auxdata() has
33e00 20 62 65 65 6e 20 63 61 6c 6c 65 64 2e 0a 2a 2a   been called..**
33e10 0a 2a 2a 20 5e 28 49 6e 20 70 72 61 63 74 69 63  .** ^(In practic
33e20 65 2c 20 6d 65 74 61 64 61 74 61 20 69 73 20 70  e, metadata is p
33e30 72 65 73 65 72 76 65 64 20 62 65 74 77 65 65 6e  reserved between
33e40 20 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20   function calls 
33e50 66 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  for.** function 
33e60 70 61 72 61 6d 65 74 65 72 73 20 74 68 61 74 20  parameters that 
33e70 61 72 65 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  are compile-time
33e80 20 63 6f 6e 73 74 61 6e 74 73 2c 20 69 6e 63 6c   constants, incl
33e90 75 64 69 6e 67 20 6c 69 74 65 72 61 6c 0a 2a 2a  uding literal.**
33ea0 20 76 61 6c 75 65 73 20 61 6e 64 20 5b 70 61 72   values and [par
33eb0 61 6d 65 74 65 72 73 5d 20 61 6e 64 20 65 78 70  ameters] and exp
33ec0 72 65 73 73 69 6f 6e 73 20 63 6f 6d 70 6f 73 65  ressions compose
33ed0 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65 2e  d from the same.
33ee0 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
33ef0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
33f00 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
33f10 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
33f20 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
33f30 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
33f40 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
33f50 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
33f60 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
33f70 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
33f80 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
33f90 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
33fa0 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
33fb0 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
33fc0 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
33fd0 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
33fe0 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
33ff0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
34000 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
34010 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
34020 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
34030 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
34040 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
34050 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
34060 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
34070 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
34080 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
34090 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
340a0 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
340b0 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
340c0 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
340d0 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
340e0 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
340f0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
34100 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
34110 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
34120 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
34130 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
34140 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
34150 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
34160 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
34170 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
34180 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
34190 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
341a0 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
341b0 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
341c0 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
341d0 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
341e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
341f0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
34200 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
34210 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
34220 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
34230 65 72 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ers..*/.typedef 
34240 76 6f 69 64 20 28 2a 73 71 6c 69 74 65 33 5f 64  void (*sqlite3_d
34250 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29 28  estructor_type)(
34260 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69 6e 65 20  void*);.#define 
34270 53 51 4c 49 54 45 5f 53 54 41 54 49 43 20 20 20  SQLITE_STATIC   
34280 20 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73     ((sqlite3_des
34290 74 72 75 63 74 6f 72 5f 74 79 70 65 29 30 29 0a  tructor_type)0).
342a0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54  #define SQLITE_T
342b0 52 41 4e 53 49 45 4e 54 20 20 20 28 28 73 71 6c  RANSIENT   ((sql
342c0 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f  ite3_destructor_
342d0 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a 2a 2a 20  type)-1)../*.** 
342e0 43 41 50 49 33 52 45 46 3a 20 53 65 74 74 69 6e  CAPI3REF: Settin
342f0 67 20 54 68 65 20 52 65 73 75 6c 74 20 4f 66 20  g The Result Of 
34300 41 6e 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 0a  An SQL Function.
34310 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74  **.** These rout
34320 69 6e 65 73 20 61 72 65 20 75 73 65 64 20 62 79  ines are used by
34330 20 74 68 65 20 78 46 75 6e 63 20 6f 72 20 78 46   the xFunc or xF
34340 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 73 20 74  inal callbacks t
34350 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  hat.** implement
34360 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 61   SQL functions a
34370 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 20 20  nd aggregates.  
34380 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  See.** [sqlite3_
34390 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
343a0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
343b0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31  create_function1
343c0 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61 64 64 69  6()].** for addi
343d0 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69  tional informati
343e0 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  on..**.** These 
343f0 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72 6b 20 76  functions work v
34400 65 72 79 20 6d 75 63 68 20 6c 69 6b 65 20 74 68  ery much like th
34410 65 20 5b 70 61 72 61 6d 65 74 65 72 20 62 69 6e  e [parameter bin
34420 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  ding] family of.
34430 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20 75 73 65  ** functions use
34440 64 20 74 6f 20 62 69 6e 64 20 76 61 6c 75 65 73  d to bind values
34450 20 74 6f 20 68 6f 73 74 20 70 61 72 61 6d 65 74   to host paramet
34460 65 72 73 20 69 6e 20 70 72 65 70 61 72 65 64 20  ers in prepared 
34470 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 52  statements..** R
34480 65 66 65 72 20 74 6f 20 74 68 65 20 5b 53 51 4c  efer to the [SQL
34490 20 70 61 72 61 6d 65 74 65 72 5d 20 64 6f 63 75   parameter] docu
344a0 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 20 61 64  mentation for ad
344b0 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
344c0 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
344d0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
344e0 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65  blob() interface
344f0 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74   sets the result
34500 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c   from.** an appl
34510 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
34520 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
34530 68 65 20 42 4c 4f 42 20 77 68 6f 73 65 20 63 6f  he BLOB whose co
34540 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e 74 65 64  ntent is pointed
34550 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65 20 73 65  .** to by the se
34560 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61  cond parameter a
34570 6e 64 20 77 68 69 63 68 20 69 73 20 4e 20 62 79  nd which is N by
34580 74 65 73 20 6c 6f 6e 67 20 77 68 65 72 65 20 4e  tes long where N
34590 20 69 73 20 74 68 65 0a 2a 2a 20 74 68 69 72 64   is the.** third
345a0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
345b0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
345c0 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28 29  esult_zeroblob()
345d0 20 69 6e 74 65 72 66 61 63 65 73 20 73 65 74 20   interfaces set 
345e0 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a 2a 2a  the result of.**
345f0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
34600 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
34610 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f 42 20 63  n to be a BLOB c
34620 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c 20 7a 65  ontaining all ze
34630 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61 6e 64 20  ro.** bytes and 
34640 4e 20 62 79 74 65 73 20 69 6e 20 73 69 7a 65 2c  N bytes in size,
34650 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
34660 76 61 6c 75 65 20 6f 66 20 74 68 65 20 32 6e 64  value of the 2nd
34670 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a   parameter..**.*
34680 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
34690 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28 29 20 69  esult_double() i
346a0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
346b0 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a  e result from.**
346c0 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d   an application-
346d0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
346e0 20 74 6f 20 62 65 20 61 20 66 6c 6f 61 74 69 6e   to be a floatin
346f0 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 20 73 70  g point value sp
34700 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 69 74  ecified.** by it
34710 73 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  s 2nd argument..
34720 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
34730 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34740 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
34750 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 66  sult_error16() f
34760 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63 61 75 73  unctions.** caus
34770 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 65  e the implemente
34780 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 74  d SQL function t
34790 6f 20 74 68 72 6f 77 20 61 6e 20 65 78 63 65 70  o throw an excep
347a0 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  tion..** ^SQLite
347b0 20 75 73 65 73 20 74 68 65 20 73 74 72 69 6e 67   uses the string
347c0 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74   pointed to by t
347d0 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72 61 6d 65  he.** 2nd parame
347e0 74 65 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 72  ter of sqlite3_r
347f0 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 6f 72  esult_error() or
34800 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34810 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20 61 73 20  error16().** as 
34820 74 68 65 20 74 65 78 74 20 6f 66 20 61 6e 20 65  the text of an e
34830 72 72 6f 72 20 6d 65 73 73 61 67 65 2e 20 20 5e  rror message.  ^
34840 53 51 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74  SQLite interpret
34850 73 20 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d  s the error.** m
34860 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 66 72  essage string fr
34870 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  om sqlite3_resul
34880 74 5f 65 72 72 6f 72 28 29 20 61 73 20 55 54 46  t_error() as UTF
34890 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a 2a 20 69  -8. ^SQLite.** i
348a0 6e 74 65 72 70 72 65 74 73 20 74 68 65 20 73 74  nterprets the st
348b0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
348c0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
348d0 28 29 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  () as UTF-16 in 
348e0 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74 65 20 6f  native.** byte o
348f0 72 64 65 72 2e 20 20 5e 49 66 20 74 68 65 20 74  rder.  ^If the t
34900 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
34910 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
34920 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
34930 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
34940 72 6f 72 31 36 28 29 20 69 73 20 6e 65 67 61 74  ror16() is negat
34950 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
34960 74 61 6b 65 73 20 61 73 20 74 68 65 20 65 72 72  takes as the err
34970 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 61 6c  or.** message al
34980 6c 20 74 65 78 74 20 75 70 20 74 68 72 6f 75 67  l text up throug
34990 68 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f  h the first zero
349a0 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e   character..** ^
349b0 49 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72  If the third par
349c0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
349d0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
349e0 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   or.** sqlite3_r
349f0 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20  esult_error16() 
34a00 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 20  is non-negative 
34a10 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65  then SQLite take
34a20 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a 2a 20 62  s that many.** b
34a30 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72 61 63  ytes (not charac
34a40 74 65 72 73 29 20 66 72 6f 6d 20 74 68 65 20 32  ters) from the 2
34a50 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20  nd parameter as 
34a60 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
34a70 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  e..** ^The sqlit
34a80 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34a90 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65  ) and sqlite3_re
34aa0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a  sult_error16().*
34ab0 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61 6b 65 20  * routines make 
34ac0 61 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f  a private copy o
34ad0 66 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  f the error mess
34ae0 61 67 65 20 74 65 78 74 20 62 65 66 6f 72 65 0a  age text before.
34af0 2a 2a 20 74 68 65 79 20 72 65 74 75 72 6e 2e 20  ** they return. 
34b00 20 48 65 6e 63 65 2c 20 74 68 65 20 63 61 6c 6c   Hence, the call
34b10 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e  ing function can
34b20 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f 72 0a 2a   deallocate or.*
34b30 2a 20 6d 6f 64 69 66 79 20 74 68 65 20 74 65 78  * modify the tex
34b40 74 20 61 66 74 65 72 20 74 68 65 79 20 72 65 74  t after they ret
34b50 75 72 6e 20 77 69 74 68 6f 75 74 20 68 61 72 6d  urn without harm
34b60 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  ..** ^The sqlite
34b70 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63  3_result_error_c
34b80 6f 64 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 63  ode() function c
34b90 68 61 6e 67 65 73 20 74 68 65 20 65 72 72 6f 72  hanges the error
34ba0 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75 72 6e 65   code.** returne
34bb0 64 20 62 79 20 53 51 4c 69 74 65 20 61 73 20 61  d by SQLite as a
34bc0 20 72 65 73 75 6c 74 20 6f 66 20 61 6e 20 65 72   result of an er
34bd0 72 6f 72 20 69 6e 20 61 20 66 75 6e 63 74 69 6f  ror in a functio
34be0 6e 2e 20 20 5e 42 79 20 64 65 66 61 75 6c 74 2c  n.  ^By default,
34bf0 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 63 6f  .** the error co
34c00 64 65 20 69 73 20 53 51 4c 49 54 45 5f 45 52 52  de is SQLITE_ERR
34c10 4f 52 2e 20 20 5e 41 20 73 75 62 73 65 71 75 65  OR.  ^A subseque
34c20 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  nt call to sqlit
34c30 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
34c40 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  ).** or sqlite3_
34c50 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
34c60 20 72 65 73 65 74 73 20 74 68 65 20 65 72 72 6f   resets the erro
34c70 72 20 63 6f 64 65 20 74 6f 20 53 51 4c 49 54 45  r code to SQLITE
34c80 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a 20 5e 54  _ERROR..**.** ^T
34c90 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
34ca0 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67 28 29  t_error_toobig()
34cb0 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
34cc0 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
34cd0 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
34ce0 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
34cf0 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69  string or BLOB i
34d00 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65  s too long to re
34d10 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  present..**.** ^
34d20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
34d30 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 29  lt_error_nomem()
34d40 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65   interface cause
34d50 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f  s SQLite to thro
34d60 77 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 20 69 6e  w an.** error in
34d70 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61 20  dicating that a 
34d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
34d90 6e 20 66 61 69 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20  n failed..**.** 
34da0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
34db0 75 6c 74 5f 69 6e 74 28 29 20 69 6e 74 65 72 66  ult_int() interf
34dc0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 74  ace sets the ret
34dd0 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20  urn value.** of 
34de0 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
34df0 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
34e00 20 74 6f 20 62 65 20 74 68 65 20 33 32 2d 62 69   to be the 32-bi
34e10 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  t signed integer
34e20 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e 20  .** value given 
34e30 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75 6d  in the 2nd argum
34e40 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ent..** ^The sql
34e50 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 36  ite3_result_int6
34e60 34 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65  4() interface se
34e70 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  ts the return va
34e80 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70  lue.** of the ap
34e90 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
34ea0 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65  d function to be
34eb0 20 74 68 65 20 36 34 2d 62 69 74 20 73 69 67 6e   the 64-bit sign
34ec0 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61  ed integer.** va
34ed0 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65  lue given in the
34ee0 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a   2nd argument..*
34ef0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
34f00 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 29 20  3_result_null() 
34f10 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74  interface sets t
34f20 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a  he return value.
34f30 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63  ** of the applic
34f40 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75  ation-defined fu
34f50 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 4e 55 4c  nction to be NUL
34f60 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  L..**.** ^The sq
34f70 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
34f80 74 28 29 2c 20 73 71 6c 69 74 65 33 5f 72 65 73  t(), sqlite3_res
34f90 75 6c 74 5f 74 65 78 74 31 36 28 29 2c 0a 2a 2a  ult_text16(),.**
34fa0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
34fb0 74 65 78 74 31 36 6c 65 28 29 2c 20 61 6e 64 20  text16le(), and 
34fc0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
34fd0 65 78 74 31 36 62 65 28 29 20 69 6e 74 65 72 66  ext16be() interf
34fe0 61 63 65 73 0a 2a 2a 20 73 65 74 20 74 68 65 20  aces.** set the 
34ff0 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
35000 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
35010 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
35020 20 74 6f 20 62 65 0a 2a 2a 20 61 20 74 65 78 74   to be.** a text
35030 20 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73   string which is
35040 20 72 65 70 72 65 73 65 6e 74 65 64 20 61 73 20   represented as 
35050 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 20 6e 61  UTF-8, UTF-16 na
35060 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2c  tive byte order,
35070 0a 2a 2a 20 55 54 46 2d 31 36 20 6c 69 74 74 6c  .** UTF-16 littl
35080 65 20 65 6e 64 69 61 6e 2c 20 6f 72 20 55 54 46  e endian, or UTF
35090 2d 31 36 20 62 69 67 20 65 6e 64 69 61 6e 2c 20  -16 big endian, 
350a0 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a  respectively..**
350b0 20 5e 53 51 4c 69 74 65 20 74 61 6b 65 73 20 74   ^SQLite takes t
350c0 68 65 20 74 65 78 74 20 72 65 73 75 6c 74 20 66  he text result f
350d0 72 6f 6d 20 74 68 65 20 61 70 70 6c 69 63 61 74  rom the applicat
350e0 69 6f 6e 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20  ion from.** the 
350f0 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f 66  2nd parameter of
35100 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   the sqlite3_res
35110 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66  ult_text* interf
35120 61 63 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  aces..** ^If the
35130 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20 74   3rd parameter t
35140 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65  o the sqlite3_re
35150 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72  sult_text* inter
35160 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 65 67 61  faces.** is nega
35170 74 69 76 65 2c 20 74 68 65 6e 20 53 51 4c 69 74  tive, then SQLit
35180 65 20 74 61 6b 65 73 20 72 65 73 75 6c 74 20 74  e takes result t
35190 65 78 74 20 66 72 6f 6d 20 74 68 65 20 32 6e 64  ext from the 2nd
351a0 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 68   parameter.** th
351b0 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
351c0 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
351d0 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20 70  ** ^If the 3rd p
351e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
351f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
35200 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a  ext* interfaces.
35210 2a 2a 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  ** is non-negati
35220 76 65 2c 20 74 68 65 6e 20 61 73 20 6d 61 6e 79  ve, then as many
35230 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61 72   bytes (not char
35240 61 63 74 65 72 73 29 20 6f 66 20 74 68 65 20 74  acters) of the t
35250 65 78 74 0a 2a 2a 20 70 6f 69 6e 74 65 64 20 74  ext.** pointed t
35260 6f 20 62 79 20 74 68 65 20 32 6e 64 20 70 61 72  o by the 2nd par
35270 61 6d 65 74 65 72 20 61 72 65 20 74 61 6b 65 6e  ameter are taken
35280 20 61 73 20 74 68 65 20 61 70 70 6c 69 63 61 74   as the applicat
35290 69 6f 6e 2d 64 65 66 69 6e 65 64 0a 2a 2a 20 66  ion-defined.** f
352a0 75 6e 63 74 69 6f 6e 20 72 65 73 75 6c 74 2e 20  unction result. 
352b0 20 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61   If the 3rd para
352c0 6d 65 74 65 72 20 69 73 20 6e 6f 6e 2d 6e 65 67  meter is non-neg
352d0 61 74 69 76 65 2c 20 74 68 65 6e 20 69 74 0a 2a  ative, then it.*
352e0 2a 20 6d 75 73 74 20 62 65 20 74 68 65 20 62 79  * must be the by
352f0 74 65 20 6f 66 66 73 65 74 20 69 6e 74 6f 20 74  te offset into t
35300 68 65 20 73 74 72 69 6e 67 20 77 68 65 72 65 20  he string where 
35310 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
35320 6f 72 20 77 6f 75 6c 64 0a 2a 2a 20 61 70 70 65  or would.** appe
35330 61 72 20 69 66 20 74 68 65 20 73 74 72 69 6e 67  ar if the string
35340 20 77 68 65 72 65 20 4e 55 4c 20 74 65 72 6d 69   where NUL termi
35350 6e 61 74 65 64 2e 20 20 49 66 20 61 6e 79 20 4e  nated.  If any N
35360 55 4c 20 63 68 61 72 61 63 74 65 72 73 20 6f 63  UL characters oc
35370 63 75 72 0a 2a 2a 20 69 6e 20 74 68 65 20 73 74  cur.** in the st
35380 72 69 6e 67 20 61 74 20 61 20 62 79 74 65 20 6f  ring at a byte o
35390 66 66 73 65 74 20 74 68 61 74 20 69 73 20 6c 65  ffset that is le
353a0 73 73 20 74 68 61 6e 20 74 68 65 20 76 61 6c 75  ss than the valu
353b0 65 20 6f 66 20 74 68 65 20 33 72 64 0a 2a 2a 20  e of the 3rd.** 
353c0 70 61 72 61 6d 65 74 65 72 2c 20 74 68 65 6e 20  parameter, then 
353d0 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73 74  the resulting st
353e0 72 69 6e 67 20 77 69 6c 6c 20 63 6f 6e 74 61 69  ring will contai
353f0 6e 20 65 6d 62 65 64 64 65 64 20 4e 55 4c 73 20  n embedded NULs 
35400 61 6e 64 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  and the.** resul
35410 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e 73  t of expressions
35420 20 6f 70 65 72 61 74 69 6e 67 20 6f 6e 20 73 74   operating on st
35430 72 69 6e 67 73 20 77 69 74 68 20 65 6d 62 65 64  rings with embed
35440 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64 65  ded NULs is unde
35450 66 69 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68  fined..** ^If th
35460 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
35470 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
35480 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
35490 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
354a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
354b0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
354c0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
354d0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
354e0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
354f0 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
35500 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
35510 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
35520 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
35530 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
35540 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
35550 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
35560 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
35570 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
35580 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
35590 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
355a0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
355b0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
355c0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
355d0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
355e0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
355f0 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
35600 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
35610 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
35620 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
35630 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
35640 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
35650 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
35660 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
35670 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
35680 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
35690 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
356a0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
356b0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
356c0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
356d0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
356e0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
356f0 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
35700 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
35710 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
35720 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
35730 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
35740 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
35750 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
35760 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
35770 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
35780 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
35790 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
357a0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
357b0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
357c0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
357d0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
357e0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
357f0 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
35800 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
35810 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
35820 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
35830 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
35840 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
35850 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
35860 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
35870 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
35880 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
35890 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
358a0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
358b0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
358c0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
358d0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
358e0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
358f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
35900 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
35910 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
35920 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
35930 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
35940 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
35950 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
35960 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
35970 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
35980 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
35990 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
359a0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
359b0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
359c0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
359d0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
359e0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
359f0 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
35a00 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
35a10 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
35a20 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
35a30 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
35a40 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
35a50 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
35a60 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
35a70 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
35a80 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
35a90 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
35aa0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
35ab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
35ac0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
35ad0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
35ae0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
35af0 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
35b00 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
35b10 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
35b20 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
35b30 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35b40 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
35b50 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
35b60 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
35b70 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
35b80 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
35b90 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
35ba0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
35bb0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
35bc0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
35bd0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35be0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
35bf0 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
35c00 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
35c10 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
35c20 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
35c30 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
35c40 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
35c50 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35c60 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
35c70 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
35c80 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
35c90 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
35ca0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
35cb0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
35cc0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
35cd0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
35ce0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
35cf0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
35d00 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35d10 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
35d20 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
35d30 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
35d40 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
35d50 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
35d60 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
35d70 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
35d80 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
35d90 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
35da0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
35db0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
35dc0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
35dd0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
35de0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
35df0 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
35e00 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
35e10 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
35e20 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
35e30 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
35e40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35e50 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
35e60 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
35e70 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
35e80 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
35e90 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
35ea0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
35eb0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
35ec0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
35ed0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
35ee0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
35ef0 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
35f00 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
35f10 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
35f20 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35f30 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
35f40 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
35f50 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
35f60 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
35f70 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
35f80 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
35f90 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
35fa0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
35fb0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
35fc0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
35fd0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
35fe0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
35ff0 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
36000 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
36010 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
36020 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
36030 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
36040 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
36050 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
36060 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
36070 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
36080 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
36090 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
360a0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
360b0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
360c0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
360d0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
360e0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
360f0 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
36100 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
36110 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
36120 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
36130 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
36140 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
36150 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
36160 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
36170 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
36180 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
36190 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
361a0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
361b0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
361c0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
361d0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
361e0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
361f0 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
36200 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
36210 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
36220 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
36230 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
36240 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
36250 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
36260 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
36270 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
36280 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
36290 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
362a0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
362b0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
362c0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
362d0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
362e0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
362f0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
36300 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
36310 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
36320 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
36330 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
36340 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
36350 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
36360 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
36370 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
36380 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
36390 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
363a0 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
363b0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
363c0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
363d0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
363e0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
363f0 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
36400 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
36410 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
36420 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
36430 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
36440 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
36450 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
36460 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
36470 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
36480 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
36490 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
364a0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
364b0 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
364c0 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
364d0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
364e0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
364f0 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
36500 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
36510 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
36520 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
36530 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
36540 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
36550 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
36560 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
36570 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
36580 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
36590 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
365a0 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
365b0 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
365c0 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
365d0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
365e0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
365f0 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
36600 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
36610 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
36620 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
36630 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
36640 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
36650 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
36660 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
36670 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
36680 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
36690 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
366a0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
366b0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
366c0 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
366d0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
366e0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
366f0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
36700 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
36710 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
36720 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
36730 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
36740 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
36750 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
36760 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
36770 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
36780 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
36790 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
367a0 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
367b0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
367c0 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
367d0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
367e0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
367f0 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
36800 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
36810 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
36820 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
36830 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
36840 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
36850 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
36860 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
36870 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
36880 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
36890 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
368a0 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
368b0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
368c0 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
368d0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
368e0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
368f0 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
36900 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
36910 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
36920 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
36930 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
36940 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
36950 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
36960 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
36970 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
36980 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
36990 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
369a0 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
369b0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
369c0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
369d0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
369e0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
369f0 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
36a00 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
36a10 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
36a20 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
36a30 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
36a40 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
36a50 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
36a60 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
36a70 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
36a80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
36a90 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
36aa0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
36ab0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
36ac0 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
36ad0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
36ae0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
36af0 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
36b00 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
36b10 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
36b20 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
36b30 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
36b40 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36b50 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
36b60 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
36b70 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
36b80 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
36b90 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
36ba0 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
36bb0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
36bc0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
36bd0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
36be0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
36bf0 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
36c00 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
36c10 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
36c20 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
36c30 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
36c40 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
36c50 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
36c60 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
36c70 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
36c80 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
36c90 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
36ca0 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
36cb0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
36cc0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
36cd0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
36ce0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
36cf0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
36d00 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
36d10 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
36d20 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
36d30 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
36d40 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
36d50 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
36d60 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
36d70 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
36d80 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36d90 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
36da0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
36db0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
36dc0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
36dd0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
36de0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
36df0 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
36e00 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
36e10 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
36e20 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
36e30 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
36e40 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
36e50 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
36e60 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
36e70 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
36e80 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
36e90 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
36ea0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
36eb0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
36ec0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
36ed0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
36ee0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
36ef0 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
36f00 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
36f10 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
36f20 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
36f30 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
36f40 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
36f50 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
36f60 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
36f70 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
36f80 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
36f90 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
36fa0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
36fb0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
36fc0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
36fd0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
36fe0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
36ff0 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
37000 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
37010 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
37020 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
37030 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
37040 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
37050 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37060 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
37070 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
37080 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
37090 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
370a0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
370b0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
370c0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
370d0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
370e0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
370f0 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
37100 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
37110 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
37120 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
37130 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
37140 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
37150 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
37160 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
37170 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
37180 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
37190 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
371a0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
371b0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
371c0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
371d0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
371e0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
371f0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
37200 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
37210 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
37220 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
37230 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
37240 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
37250 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
37260 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
37270 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
37280 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
37290 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
372a0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
372b0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
372c0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
372d0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
372e0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
372f0 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
37300 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
37310 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
37320 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
37330 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
37340 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
37350 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
37360 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
37370 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
37380 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
37390 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
373a0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
373b0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
373c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
373d0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
373e0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
373f0 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
37400 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
37410 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
37420 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
37430 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
37440 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
37450 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
37460 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
37470 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
37480 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
37490 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
374a0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
374b0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
374c0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
374d0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
374e0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
374f0 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
37500 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
37510 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
37520 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
37530 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
37540 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
37550 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
37560 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
37570 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
37580 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
37590 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
375a0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
375b0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
375c0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
375d0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
375e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
375f0 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
37600 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
37610 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
37620 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
37630 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 69   The key */.);.i
37640 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 5f 76  nt sqlite3_key_v
37650 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
37660 2c 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ,               
37670 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20      /* Database 
37680 74 6f 20 62 65 20 72 65 6b 65 79 65 64 20 2a 2f  to be rekeyed */
37690 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
376a0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 20  DbName,         
376b0 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 74 68 65    /* Name of the
376c0 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20 63   database */.  c
376d0 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
376e0 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
376f0 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
37700 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
37710 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
37720 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
37730 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
37740 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
37750 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
37760 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
37770 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
37780 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
37790 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
377a0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
377b0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
377c0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
377d0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
377e0 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
377f0 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
37800 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
37810 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
37820 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
37830 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
37840 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
37850 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
37860 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
37870 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
37880 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
37890 69 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 6b 65  int sqlite3_reke
378a0 79 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  y_v2(.  sqlite3 
378b0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
378c0 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61         /* Databa
378d0 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65 64  se to be rekeyed
378e0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
378f0 20 2a 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20   *zDbName,      
37900 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
37910 74 68 65 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  the database */.
37920 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b    const void *pK
37930 65 79 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20  ey, int nKey    
37940 20 2f 2a 20 54 68 65 20 6e 65 77 20 6b 65 79 20   /* The new key 
37950 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 53 70 65  */.);../*.** Spe
37960 63 69 66 79 20 74 68 65 20 61 63 74 69 76 61 74  cify the activat
37970 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20 53 45  ion key for a SE
37980 45 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c  E database.  Unl
37990 65 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65  ess .** activate
379a0 64 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 53  d, none of the S
379b0 45 45 20 72 6f 75 74 69 6e 65 73 20 77 69 6c 6c  EE routines will
379c0 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73   work..*/.void s
379d0 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65 5f  qlite3_activate_
379e0 73 65 65 28 0a 20 20 63 6f 6e 73 74 20 63 68 61  see(.  const cha
379f0 72 20 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20  r *zPassPhrase  
37a00 20 20 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74        /* Activat
37a10 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b  ion phrase */.);
37a20 0a 23 65 6e 64 69 66 0a 0a 23 69 66 64 65 66 20  .#endif..#ifdef 
37a30 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 43 45  SQLITE_ENABLE_CE
37a40 52 4f 44 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66  ROD./*.** Specif
37a50 79 20 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e  y the activation
37a60 20 6b 65 79 20 66 6f 72 20 61 20 43 45 52 4f 44   key for a CEROD
37a70 20 64 61 74 61 62 61 73 65 2e 20 20 55 6e 6c 65   database.  Unle
37a80 73 73 20 0a 2a 2a 20 61 63 74 69 76 61 74 65 64  ss .** activated
37a90 2c 20 6e 6f 6e 65 20 6f 66 20 74 68 65 20 43 45  , none of the CE
37aa0 52 4f 44 20 72 6f 75 74 69 6e 65 73 20 77 69 6c  ROD routines wil
37ab0 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76 6f 69 64 20  l work..*/.void 
37ac0 73 71 6c 69 74 65 33 5f 61 63 74 69 76 61 74 65  sqlite3_activate
37ad0 5f 63 65 72 6f 64 28 0a 20 20 63 6f 6e 73 74 20  _cerod(.  const 
37ae0 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72 61 73  char *zPassPhras
37af0 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63 74 69  e        /* Acti
37b00 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20 2a 2f  vation phrase */
37b10 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  .);.#endif../*.*
37b20 2a 20 43 41 50 49 33 52 45 46 3a 20 53 75 73 70  * CAPI3REF: Susp
37b30 65 6e 64 20 45 78 65 63 75 74 69 6f 6e 20 46 6f  end Execution Fo
37b40 72 20 41 20 53 68 6f 72 74 20 54 69 6d 65 0a 2a  r A Short Time.*
37b50 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
37b60 5f 73 6c 65 65 70 28 29 20 66 75 6e 63 74 69 6f  _sleep() functio
37b70 6e 20 63 61 75 73 65 73 20 74 68 65 20 63 75 72  n causes the cur
37b80 72 65 6e 74 20 74 68 72 65 61 64 20 74 6f 20 73  rent thread to s
37b90 75 73 70 65 6e 64 20 65 78 65 63 75 74 69 6f 6e  uspend execution
37ba0 0a 2a 2a 20 66 6f 72 20 61 74 20 6c 65 61 73 74  .** for at least
37bb0 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c   a number of mil
37bc0 6c 69 73 65 63 6f 6e 64 73 20 73 70 65 63 69 66  liseconds specif
37bd0 69 65 64 20 69 6e 20 69 74 73 20 70 61 72 61 6d  ied in its param
37be0 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  eter..**.** If t
37bf0 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73  he operating sys
37c00 74 65 6d 20 64 6f 65 73 20 6e 6f 74 20 73 75 70  tem does not sup
37c10 70 6f 72 74 20 73 6c 65 65 70 20 72 65 71 75 65  port sleep reque
37c20 73 74 73 20 77 69 74 68 0a 2a 2a 20 6d 69 6c 6c  sts with.** mill
37c30 69 73 65 63 6f 6e 64 20 74 69 6d 65 20 72 65 73  isecond time res
37c40 6f 6c 75 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68  olution, then th
37c50 65 20 74 69 6d 65 20 77 69 6c 6c 20 62 65 20 72  e time will be r
37c60 6f 75 6e 64 65 64 20 75 70 20 74 6f 0a 2a 2a 20  ounded up to.** 
37c70 74 68 65 20 6e 65 61 72 65 73 74 20 73 65 63 6f  the nearest seco
37c80 6e 64 2e 20 54 68 65 20 6e 75 6d 62 65 72 20 6f  nd. The number o
37c90 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f  f milliseconds o
37ca0 66 20 73 6c 65 65 70 20 61 63 74 75 61 6c 6c 79  f sleep actually
37cb0 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 66 72  .** requested fr
37cc0 6f 6d 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67  om the operating
37cd0 20 73 79 73 74 65 6d 20 69 73 20 72 65 74 75 72   system is retur
37ce0 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ned..**.** ^SQLi
37cf0 74 65 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  te implements th
37d00 69 73 20 69 6e 74 65 72 66 61 63 65 20 62 79 20  is interface by 
37d10 63 61 6c 6c 69 6e 67 20 74 68 65 20 78 53 6c 65  calling the xSle
37d20 65 70 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f  ep().** method o
37d30 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73  f the default [s
37d40 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
37d50 63 74 2e 20 20 49 66 20 74 68 65 20 78 53 6c 65  ct.  If the xSle
37d60 65 70 28 29 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f  ep() method.** o
37d70 66 20 74 68 65 20 64 65 66 61 75 6c 74 20 56 46  f the default VF
37d80 53 20 69 73 20 6e 6f 74 20 69 6d 70 6c 65 6d 65  S is not impleme
37d90 6e 74 65 64 20 63 6f 72 72 65 63 74 6c 79 2c 20  nted correctly, 
37da0 6f 72 20 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74  or not implement
37db0 65 64 20 61 74 0a 2a 2a 20 61 6c 6c 2c 20 74 68  ed at.** all, th
37dc0 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
37dd0 6f 66 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  of sqlite3_sleep
37de0 28 29 20 6d 61 79 20 64 65 76 69 61 74 65 20 66  () may deviate f
37df0 72 6f 6d 20 74 68 65 20 64 65 73 63 72 69 70 74  rom the descript
37e00 69 6f 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 70 72  ion.** in the pr
37e10 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70 68  evious paragraph
37e20 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  s..*/.int sqlite
37e30 33 5f 73 6c 65 65 70 28 69 6e 74 29 3b 0a 0a 2f  3_sleep(int);../
37e40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
37e50 61 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65  ame Of The Folde
37e60 72 20 48 6f 6c 64 69 6e 67 20 54 65 6d 70 6f 72  r Holding Tempor
37e70 61 72 79 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20  ary Files.**.** 
37e80 5e 28 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c  ^(If this global
37e90 20 76 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64   variable is mad
37ea0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20  e to point to a 
37eb0 73 74 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a  string which is.
37ec0 2a 2a 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61  ** the name of a
37ed0 20 66 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20   folder (a.k.a. 
37ee0 64 69 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e  directory), then
37ef0 20 61 6c 6c 20 74 65 6d 70 6f 72 61 72 79 20 66   all temporary f
37f00 69 6c 65 73 0a 2a 2a 20 63 72 65 61 74 65 64 20  iles.** created 
37f10 62 79 20 53 51 4c 69 74 65 20 77 68 65 6e 20 75  by SQLite when u
37f20 73 69 6e 67 20 61 20 62 75 69 6c 74 2d 69 6e 20  sing a built-in 
37f30 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 56  [sqlite3_vfs | V
37f40 46 53 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 70  FS].** will be p
37f50 6c 61 63 65 64 20 69 6e 20 74 68 61 74 20 64 69  laced in that di
37f60 72 65 63 74 6f 72 79 2e 29 5e 20 20 5e 49 66 20  rectory.)^  ^If 
37f70 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a 2a 2a  this variable.**
37f80 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   is a NULL point
37f90 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20  er, then SQLite 
37fa0 70 65 72 66 6f 72 6d 73 20 61 20 73 65 61 72 63  performs a searc
37fb0 68 20 66 6f 72 20 61 6e 20 61 70 70 72 6f 70 72  h for an appropr
37fc0 69 61 74 65 0a 2a 2a 20 74 65 6d 70 6f 72 61 72  iate.** temporar
37fd0 79 20 66 69 6c 65 20 64 69 72 65 63 74 6f 72 79  y file directory
37fe0 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74  ..**.** Applicat
37ff0 69 6f 6e 73 20 61 72 65 20 73 74 72 6f 6e 67 6c  ions are strongl
38000 79 20 64 69 73 63 6f 75 72 61 67 65 64 20 66 72  y discouraged fr
38010 6f 6d 20 75 73 69 6e 67 20 74 68 69 73 20 67 6c  om using this gl
38020 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 2e 0a 2a  obal variable..*
38030 2a 20 49 74 20 69 73 20 72 65 71 75 69 72 65 64  * It is required
38040 20 74 6f 20 73 65 74 20 61 20 74 65 6d 70 6f 72   to set a tempor
38050 61 72 79 20 66 6f 6c 64 65 72 20 6f 6e 20 57 69  ary folder on Wi
38060 6e 64 6f 77 73 20 52 75 6e 74 69 6d 65 20 28 57  ndows Runtime (W
38070 69 6e 52 54 29 2e 0a 2a 2a 20 42 75 74 20 66 6f  inRT)..** But fo
38080 72 20 61 6c 6c 20 6f 74 68 65 72 20 70 6c 61 74  r all other plat
38090 66 6f 72 6d 73 2c 20 69 74 20 69 73 20 68 69 67  forms, it is hig
380a0 68 6c 79 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20  hly recommended 
380b0 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e  that application
380c0 73 0a 2a 2a 20 6e 65 69 74 68 65 72 20 72 65 61  s.** neither rea
380d0 64 20 6e 6f 72 20 77 72 69 74 65 20 74 68 69 73  d nor write this
380e0 20 76 61 72 69 61 62 6c 65 2e 20 20 54 68 69 73   variable.  This
380f0 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65   global variable
38100 20 69 73 20 61 20 72 65 6c 69 63 0a 2a 2a 20 74   is a relic.** t
38110 68 61 74 20 65 78 69 73 74 73 20 66 6f 72 20 62  hat exists for b
38120 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69  ackwards compati
38130 62 69 6c 69 74 79 20 6f 66 20 6c 65 67 61 63 79  bility of legacy
38140 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 61 6e   applications an
38150 64 20 73 68 6f 75 6c 64 0a 2a 2a 20 62 65 20 61  d should.** be a
38160 76 6f 69 64 65 64 20 69 6e 20 6e 65 77 20 70 72  voided in new pr
38170 6f 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 49 74  ojects..**.** It
38180 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
38190 72 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74  read or modify t
381a0 68 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20  his variable in 
381b0 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a  more than one.**
381c0 20 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d   thread at a tim
381d0 65 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61  e.  It is not sa
381e0 66 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f  fe to read or mo
381f0 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62  dify this variab
38200 6c 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61  le.** if a [data
38210 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38220 20 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61   is being used a
38230 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20  t the same time 
38240 69 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a  in a separate.**
38250 20 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69   thread..** It i
38260 73 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20  s intended that 
38270 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65  this variable be
38280 20 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20   set once.** as 
38290 70 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20  part of process 
382a0 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61  initialization a
382b0 6e 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51  nd before any SQ
382c0 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a  Lite interface.*
382d0 2a 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20  * routines have 
382e0 62 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20  been called and 
382f0 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
38300 6c 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e  le remain unchan
38310 67 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65  ged.** thereafte
38320 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74  r..**.** ^The [t
38330 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
38340 6f 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20  ory pragma] may 
38350 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69  modify this vari
38360 61 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a  able and cause.*
38370 2a 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f  * it to point to
38380 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
38390 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
383a0 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65  alloc].  ^Furthe
383b0 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74  rmore,.** the [t
383c0 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
383d0 6f 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61  ory pragma] alwa
383e0 79 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20  ys assumes that 
383f0 61 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68  any string.** th
38400 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  at this variable
38410 20 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65   points to is he
38420 6c 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74  ld in memory obt
38430 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b  ained from .** [
38440 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20  sqlite3_malloc] 
38450 61 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d  and the pragma m
38460 61 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72  ay attempt to fr
38470 65 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a  ee that memory.*
38480 2a 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  * using [sqlite3
38490 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65  _free]..** Hence
384a0 2c 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62  , if this variab
384b0 6c 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64  le is modified d
384c0 69 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20  irectly, either 
384d0 69 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20  it should be.** 
384e0 6d 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64  made NULL or mad
384f0 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  e to point to me
38500 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
38510 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
38520 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74  oc].** or else t
38530 68 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74  he use of the [t
38540 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74  emp_store_direct
38550 6f 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75  ory pragma] shou
38560 6c 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a  ld be avoided..*
38570 2a 20 45 78 63 65 70 74 20 77 68 65 6e 20 72 65  * Except when re
38580 71 75 65 73 74 65 64 20 62 79 20 74 68 65 20 5b  quested by the [
38590 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63  temp_store_direc
385a0 74 6f 72 79 20 70 72 61 67 6d 61 5d 2c 20 53 51  tory pragma], SQ
385b0 4c 69 74 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74  Lite.** does not
385c0 20 66 72 65 65 20 74 68 65 20 6d 65 6d 6f 72 79   free the memory
385d0 20 74 68 61 74 20 73 71 6c 69 74 65 33 5f 74 65   that sqlite3_te
385e0 6d 70 5f 64 69 72 65 63 74 6f 72 79 20 70 6f 69  mp_directory poi
385f0 6e 74 73 20 74 6f 2e 20 20 49 66 0a 2a 2a 20 74  nts to.  If.** t
38600 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77  he application w
38610 61 6e 74 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ants that memory
38620 20 74 6f 20 62 65 20 66 72 65 65 64 2c 20 69 74   to be freed, it
38630 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 73 6f 20 69   must do.** so i
38640 74 73 65 6c 66 2c 20 74 61 6b 69 6e 67 20 63 61  tself, taking ca
38650 72 65 20 74 6f 20 6f 6e 6c 79 20 64 6f 20 73 6f  re to only do so
38660 20 61 66 74 65 72 20 61 6c 6c 20 5b 64 61 74 61   after all [data
38670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
38680 0a 2a 2a 20 6f 62 6a 65 63 74 73 20 68 61 76 65  .** objects have
38690 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
386a0 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74 65 20 74  .**.** <b>Note t
386b0 6f 20 57 69 6e 64 6f 77 73 20 52 75 6e 74 69 6d  o Windows Runtim
386c0 65 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  e users:</b>  Th
386d0 65 20 74 65 6d 70 6f 72 61 72 79 20 64 69 72 65  e temporary dire
386e0 63 74 6f 72 79 20 6d 75 73 74 20 62 65 20 73 65  ctory must be se
386f0 74 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 63 61  t.** prior to ca
38700 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6f  lling [sqlite3_o
38710 70 65 6e 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  pen] or [sqlite3
38720 5f 6f 70 65 6e 5f 76 32 5d 2e 20 20 4f 74 68 65  _open_v2].  Othe
38730 72 77 69 73 65 2c 20 76 61 72 69 6f 75 73 0a 2a  rwise, various.*
38740 2a 20 66 65 61 74 75 72 65 73 20 74 68 61 74 20  * features that 
38750 72 65 71 75 69 72 65 20 74 68 65 20 75 73 65 20  require the use 
38760 6f 66 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  of temporary fil
38770 65 73 20 6d 61 79 20 66 61 69 6c 2e 20 20 48 65  es may fail.  He
38780 72 65 20 69 73 20 61 6e 0a 2a 2a 20 65 78 61 6d  re is an.** exam
38790 70 6c 65 20 6f 66 20 68 6f 77 20 74 6f 20 64 6f  ple of how to do
387a0 20 74 68 69 73 20 75 73 69 6e 67 20 43 2b 2b 20   this using C++ 
387b0 77 69 74 68 20 74 68 65 20 57 69 6e 64 6f 77 73  with the Windows
387c0 20 52 75 6e 74 69 6d 65 3a 0a 2a 2a 0a 2a 2a 20   Runtime:.**.** 
387d0 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
387e0 3e 0a 2a 2a 20 4c 50 43 57 53 54 52 20 7a 50 61  >.** LPCWSTR zPa
387f0 74 68 20 3d 20 57 69 6e 64 6f 77 73 3a 3a 53 74  th = Windows::St
38800 6f 72 61 67 65 3a 3a 41 70 70 6c 69 63 61 74 69  orage::Applicati
38810 6f 6e 44 61 74 61 3a 3a 43 75 72 72 65 6e 74 2d  onData::Current-
38820 3e 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 20  >.** &nbsp;     
38830