/ Hex Artifact Content
Login

Artifact 06a5141bdc5cc8959fe04bc0f59b0fe0ff742c90:


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 69 73  3_close()].** is
23f0: 20 69 74 73 20 64 65 73 74 72 75 63 74 6f 72 2e   its destructor.
2400: 20 20 54 68 65 72 65 20 61 72 65 20 6d 61 6e 79    There are many
2410: 20 6f 74 68 65 72 20 69 6e 74 65 72 66 61 63 65   other interface
2420: 73 20 28 73 75 63 68 20 61 73 0a 2a 2a 20 5b 73  s (such as.** [s
2430: 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
2440: 32 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63  2()], [sqlite3_c
2450: 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29  reate_function()
2460: 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
2470: 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75 74 28  e3_busy_timeout(
2480: 29 5d 20 74 6f 20 6e 61 6d 65 20 62 75 74 20 74  )] to name but t
2490: 68 72 65 65 29 20 74 68 61 74 20 61 72 65 20 6d  hree) that are m
24a0: 65 74 68 6f 64 73 20 6f 6e 20 61 6e 0a 2a 2a 20  ethods on an.** 
24b0: 73 71 6c 69 74 65 33 20 6f 62 6a 65 63 74 2e 0a  sqlite3 object..
24c0: 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63  */.typedef struc
24d0: 74 20 73 71 6c 69 74 65 33 20 73 71 6c 69 74 65  t sqlite3 sqlite
24e0: 33 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  3;../*.** CAPI3R
24f0: 45 46 3a 20 36 34 2d 42 69 74 20 49 6e 74 65 67  EF: 64-Bit Integ
2500: 65 72 20 54 79 70 65 73 0a 2a 2a 20 4b 45 59 57  er Types.** KEYW
2510: 4f 52 44 53 3a 20 73 71 6c 69 74 65 5f 69 6e 74  ORDS: sqlite_int
2520: 36 34 20 73 71 6c 69 74 65 5f 75 69 6e 74 36 34  64 sqlite_uint64
2530: 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74  .**.** Because t
2540: 68 65 72 65 20 69 73 20 6e 6f 20 63 72 6f 73 73  here is no cross
2550: 2d 70 6c 61 74 66 6f 72 6d 20 77 61 79 20 74 6f  -platform way to
2560: 20 73 70 65 63 69 66 79 20 36 34 2d 62 69 74 20   specify 64-bit 
2570: 69 6e 74 65 67 65 72 20 74 79 70 65 73 0a 2a 2a  integer types.**
2580: 20 53 51 4c 69 74 65 20 69 6e 63 6c 75 64 65 73   SQLite includes
2590: 20 74 79 70 65 64 65 66 73 20 66 6f 72 20 36 34   typedefs for 64
25a0: 2d 62 69 74 20 73 69 67 6e 65 64 20 61 6e 64 20  -bit signed and 
25b0: 75 6e 73 69 67 6e 65 64 20 69 6e 74 65 67 65 72  unsigned integer
25c0: 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  s..**.** The sql
25d0: 69 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73  ite3_int64 and s
25e0: 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 20 61 72  qlite3_uint64 ar
25f0: 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64 20  e the preferred 
2600: 74 79 70 65 20 64 65 66 69 6e 69 74 69 6f 6e 73  type definitions
2610: 2e 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 5f  ..** The sqlite_
2620: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2630: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 61 72  _uint64 types ar
2640: 65 20 73 75 70 70 6f 72 74 65 64 20 66 6f 72 20  e supported for 
2650: 62 61 63 6b 77 61 72 64 73 0a 2a 2a 20 63 6f 6d  backwards.** com
2660: 70 61 74 69 62 69 6c 69 74 79 20 6f 6e 6c 79 2e  patibility only.
2670: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2680: 74 65 33 5f 69 6e 74 36 34 20 61 6e 64 20 73 71  te3_int64 and sq
2690: 6c 69 74 65 5f 69 6e 74 36 34 20 74 79 70 65 73  lite_int64 types
26a0: 20 63 61 6e 20 73 74 6f 72 65 20 69 6e 74 65 67   can store integ
26b0: 65 72 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  er values.** bet
26c0: 77 65 65 6e 20 2d 39 32 32 33 33 37 32 30 33 36  ween -9223372036
26d0: 38 35 34 37 37 35 38 30 38 20 61 6e 64 20 2b 39  854775808 and +9
26e0: 32 32 33 33 37 32 30 33 36 38 35 34 37 37 35 38  2233720368547758
26f0: 30 37 20 69 6e 63 6c 75 73 69 76 65 2e 20 20 5e  07 inclusive.  ^
2700: 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75  The.** sqlite3_u
2710: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
2720: 5f 75 69 6e 74 36 34 20 74 79 70 65 73 20 63 61  _uint64 types ca
2730: 6e 20 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20  n store integer 
2740: 76 61 6c 75 65 73 20 0a 2a 2a 20 62 65 74 77 65  values .** betwe
2750: 65 6e 20 30 20 61 6e 64 20 2b 31 38 34 34 36 37  en 0 and +184467
2760: 34 34 30 37 33 37 30 39 35 35 31 36 31 35 20 69  44073709551615 i
2770: 6e 63 6c 75 73 69 76 65 2e 0a 2a 2f 0a 23 69 66  nclusive..*/.#if
2780: 64 65 66 20 53 51 4c 49 54 45 5f 49 4e 54 36 34  def SQLITE_INT64
2790: 5f 54 59 50 45 0a 20 20 74 79 70 65 64 65 66 20  _TYPE.  typedef 
27a0: 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50  SQLITE_INT64_TYP
27b0: 45 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  E sqlite_int64;.
27c0: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
27d0: 65 64 20 53 51 4c 49 54 45 5f 49 4e 54 36 34 5f  ed SQLITE_INT64_
27e0: 54 59 50 45 20 73 71 6c 69 74 65 5f 75 69 6e 74  TYPE sqlite_uint
27f0: 36 34 3b 0a 23 65 6c 69 66 20 64 65 66 69 6e 65  64;.#elif define
2800: 64 28 5f 4d 53 43 5f 56 45 52 29 20 7c 7c 20 64  d(_MSC_VER) || d
2810: 65 66 69 6e 65 64 28 5f 5f 42 4f 52 4c 41 4e 44  efined(__BORLAND
2820: 43 5f 5f 29 0a 20 20 74 79 70 65 64 65 66 20 5f  C__).  typedef _
2830: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 5f 69 6e  _int64 sqlite_in
2840: 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20 75  t64;.  typedef u
2850: 6e 73 69 67 6e 65 64 20 5f 5f 69 6e 74 36 34 20  nsigned __int64 
2860: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
2870: 65 6c 73 65 0a 20 20 74 79 70 65 64 65 66 20 6c  else.  typedef l
2880: 6f 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c  ong long int sql
2890: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
28a0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 6c 6f  edef unsigned lo
28b0: 6e 67 20 6c 6f 6e 67 20 69 6e 74 20 73 71 6c 69  ng long int sqli
28c0: 74 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6e 64 69  te_uint64;.#endi
28d0: 66 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65  f.typedef sqlite
28e0: 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 69  _int64 sqlite3_i
28f0: 6e 74 36 34 3b 0a 74 79 70 65 64 65 66 20 73 71  nt64;.typedef sq
2900: 6c 69 74 65 5f 75 69 6e 74 36 34 20 73 71 6c 69  lite_uint64 sqli
2910: 74 65 33 5f 75 69 6e 74 36 34 3b 0a 0a 2f 2a 0a  te3_uint64;../*.
2920: 2a 2a 20 49 66 20 63 6f 6d 70 69 6c 69 6e 67 20  ** If compiling 
2930: 66 6f 72 20 61 20 70 72 6f 63 65 73 73 6f 72 20  for a processor 
2940: 74 68 61 74 20 6c 61 63 6b 73 20 66 6c 6f 61 74  that lacks float
2950: 69 6e 67 20 70 6f 69 6e 74 20 73 75 70 70 6f 72  ing point suppor
2960: 74 2c 0a 2a 2a 20 73 75 62 73 74 69 74 75 74 65  t,.** substitute
2970: 20 69 6e 74 65 67 65 72 20 66 6f 72 20 66 6c 6f   integer for flo
2980: 61 74 69 6e 67 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a  ating-point..*/.
2990: 23 69 66 64 65 66 20 53 51 4c 49 54 45 5f 4f 4d  #ifdef SQLITE_OM
29a0: 49 54 5f 46 4c 4f 41 54 49 4e 47 5f 50 4f 49 4e  IT_FLOATING_POIN
29b0: 54 0a 23 20 64 65 66 69 6e 65 20 64 6f 75 62 6c  T.# define doubl
29c0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 0a  e sqlite3_int64.
29d0: 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
29e0: 50 49 33 52 45 46 3a 20 43 6c 6f 73 69 6e 67 20  PI3REF: Closing 
29f0: 41 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  A Database Conne
2a00: 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ction.**.** ^The
2a10: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2a20: 20 72 6f 75 74 69 6e 65 20 69 73 20 74 68 65 20   routine is the 
2a30: 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2a40: 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
2a50: 65 63 74 2e 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74  ect..** ^Calls t
2a60: 6f 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28  o sqlite3_close(
2a70: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
2a80: 4f 4b 20 69 66 20 74 68 65 20 5b 73 71 6c 69 74  OK if the [sqlit
2a90: 65 33 5d 20 6f 62 6a 65 63 74 20 69 73 0a 2a 2a  e3] object is.**
2aa0: 20 73 75 63 63 65 73 73 66 75 6c 6c 79 20 64 65   successfully de
2ab0: 73 74 72 6f 79 65 64 20 61 6e 64 20 61 6c 6c 20  stroyed and all 
2ac0: 61 73 73 6f 63 69 61 74 65 64 20 72 65 73 6f 75  associated resou
2ad0: 72 63 65 73 20 61 72 65 20 64 65 61 6c 6c 6f 63  rces are dealloc
2ae0: 61 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c  ated..**.** Appl
2af0: 69 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 5b 73  ications must [s
2b00: 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 20  qlite3_finalize 
2b10: 7c 20 66 69 6e 61 6c 69 7a 65 5d 20 61 6c 6c 20  | finalize] all 
2b20: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b30: 65 6e 74 73 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71  ents].** and [sq
2b40: 6c 69 74 65 33 5f 62 6c 6f 62 5f 63 6c 6f 73 65  lite3_blob_close
2b50: 20 7c 20 63 6c 6f 73 65 5d 20 61 6c 6c 20 5b 42   | close] all [B
2b60: 4c 4f 42 20 68 61 6e 64 6c 65 73 5d 20 61 73 73  LOB handles] ass
2b70: 6f 63 69 61 74 65 64 20 77 69 74 68 0a 2a 2a 20  ociated with.** 
2b80: 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62  the [sqlite3] ob
2b90: 6a 65 63 74 20 70 72 69 6f 72 20 74 6f 20 61 74  ject prior to at
2ba0: 74 65 6d 70 74 69 6e 67 20 74 6f 20 63 6c 6f 73  tempting to clos
2bb0: 65 20 74 68 65 20 6f 62 6a 65 63 74 2e 20 20 5e  e the object.  ^
2bc0: 49 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6c  If.** sqlite3_cl
2bd0: 6f 73 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ose() is called 
2be0: 6f 6e 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  on a [database c
2bf0: 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 20  onnection] that 
2c00: 73 74 69 6c 6c 20 68 61 73 0a 2a 2a 20 6f 75 74  still has.** out
2c10: 73 74 61 6e 64 69 6e 67 20 5b 70 72 65 70 61 72  standing [prepar
2c20: 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20 6f  ed statements] o
2c30: 72 20 5b 42 4c 4f 42 20 68 61 6e 64 6c 65 73 5d  r [BLOB handles]
2c40: 2c 20 74 68 65 6e 20 69 74 20 72 65 74 75 72 6e  , then it return
2c50: 73 0a 2a 2a 20 53 51 4c 49 54 45 5f 42 55 53 59  s.** SQLITE_BUSY
2c60: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 73 71 6c  ..**.** ^If [sql
2c70: 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 69 73  ite3_close()] is
2c80: 20 69 6e 76 6f 6b 65 64 20 77 68 69 6c 65 20 61   invoked while a
2c90: 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
2ca0: 6f 70 65 6e 2c 0a 2a 2a 20 74 68 65 20 74 72 61  open,.** the tra
2cb0: 6e 73 61 63 74 69 6f 6e 20 69 73 20 61 75 74 6f  nsaction is auto
2cc0: 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c 65 64  matically rolled
2cd0: 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   back..**.** The
2ce0: 20 43 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20   C parameter to 
2cf0: 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 43  [sqlite3_close(C
2d00: 29 5d 20 6d 75 73 74 20 62 65 20 65 69 74 68 65  )] must be eithe
2d10: 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
2d20: 74 65 72 20 6f 72 20 61 6e 20 5b 73 71 6c 69 74  ter or an [sqlit
2d30: 65 33 5d 20 6f 62 6a 65 63 74 20 70 6f 69 6e 74  e3] object point
2d40: 65 72 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66  er obtained.** f
2d50: 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  rom [sqlite3_ope
2d60: 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f  n()], [sqlite3_o
2d70: 70 65 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20  pen16()], or.** 
2d80: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
2d90: 28 29 5d 2c 20 61 6e 64 20 6e 6f 74 20 70 72 65  ()], and not pre
2da0: 76 69 6f 75 73 6c 79 20 63 6c 6f 73 65 64 2e 0a  viously closed..
2db0: 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71 6c 69  ** ^Calling sqli
2dc0: 74 65 33 5f 63 6c 6f 73 65 28 29 20 77 69 74 68  te3_close() with
2dd0: 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
2de0: 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20 0a 2a  argument is a .*
2df0: 2a 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70  * harmless no-op
2e00: 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
2e10: 5f 63 6c 6f 73 65 28 73 71 6c 69 74 65 33 20 2a  _close(sqlite3 *
2e20: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 54 68 65 20 74 79  );../*.** The ty
2e30: 70 65 20 66 6f 72 20 61 20 63 61 6c 6c 62 61 63  pe for a callbac
2e40: 6b 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 54  k function..** T
2e50: 68 69 73 20 69 73 20 6c 65 67 61 63 79 20 61 6e  his is legacy an
2e60: 64 20 64 65 70 72 65 63 61 74 65 64 2e 20 20 49  d deprecated.  I
2e70: 74 20 69 73 20 69 6e 63 6c 75 64 65 64 20 66 6f  t is included fo
2e80: 72 20 68 69 73 74 6f 72 69 63 61 6c 0a 2a 2a 20  r historical.** 
2e90: 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 61 6e  compatibility an
2ea0: 64 20 69 73 20 6e 6f 74 20 64 6f 63 75 6d 65 6e  d is not documen
2eb0: 74 65 64 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20  ted..*/.typedef 
2ec0: 69 6e 74 20 28 2a 73 71 6c 69 74 65 33 5f 63 61  int (*sqlite3_ca
2ed0: 6c 6c 62 61 63 6b 29 28 76 6f 69 64 2a 2c 69 6e  llback)(void*,in
2ee0: 74 2c 63 68 61 72 2a 2a 2c 20 63 68 61 72 2a 2a  t,char**, char**
2ef0: 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f00: 45 46 3a 20 4f 6e 65 2d 53 74 65 70 20 51 75 65  EF: One-Step Que
2f10: 72 79 20 45 78 65 63 75 74 69 6f 6e 20 49 6e 74  ry Execution Int
2f20: 65 72 66 61 63 65 0a 2a 2a 0a 2a 2a 20 54 68 65  erface.**.** The
2f30: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
2f40: 69 6e 74 65 72 66 61 63 65 20 69 73 20 61 20 63  interface is a c
2f50: 6f 6e 76 65 6e 69 65 6e 63 65 20 77 72 61 70 70  onvenience wrapp
2f60: 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71  er around.** [sq
2f70: 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32  lite3_prepare_v2
2f80: 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  ()], [sqlite3_st
2f90: 65 70 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69  ep()], and [sqli
2fa0: 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 2c  te3_finalize()],
2fb0: 0a 2a 2a 20 74 68 61 74 20 61 6c 6c 6f 77 73 20  .** that allows 
2fc0: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 74  an application t
2fd0: 6f 20 72 75 6e 20 6d 75 6c 74 69 70 6c 65 20 73  o run multiple s
2fe0: 74 61 74 65 6d 65 6e 74 73 20 6f 66 20 53 51 4c  tatements of SQL
2ff0: 0a 2a 2a 20 77 69 74 68 6f 75 74 20 68 61 76 69  .** without havi
3000: 6e 67 20 74 6f 20 75 73 65 20 61 20 6c 6f 74 20  ng to use a lot 
3010: 6f 66 20 43 20 63 6f 64 65 2e 20 0a 2a 2a 0a 2a  of C code. .**.*
3020: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
3030: 78 65 63 28 29 20 69 6e 74 65 72 66 61 63 65 20  xec() interface 
3040: 72 75 6e 73 20 7a 65 72 6f 20 6f 72 20 6d 6f 72  runs zero or mor
3050: 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 2c  e UTF-8 encoded,
3060: 0a 2a 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65  .** semicolon-se
3070: 70 61 72 61 74 65 20 53 51 4c 20 73 74 61 74 65  parate SQL state
3080: 6d 65 6e 74 73 20 70 61 73 73 65 64 20 69 6e 74  ments passed int
3090: 6f 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  o its 2nd argume
30a0: 6e 74 2c 0a 2a 2a 20 69 6e 20 74 68 65 20 63 6f  nt,.** in the co
30b0: 6e 74 65 78 74 20 6f 66 20 74 68 65 20 5b 64 61  ntext of the [da
30c0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30d0: 6e 5d 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  n] passed in as 
30e0: 69 74 73 20 31 73 74 0a 2a 2a 20 61 72 67 75 6d  its 1st.** argum
30f0: 65 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 63 61  ent.  ^If the ca
3100: 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
3110: 6f 66 20 74 68 65 20 33 72 64 20 61 72 67 75 6d  of the 3rd argum
3120: 65 6e 74 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  ent to.** sqlite
3130: 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f 74 20  3_exec() is not 
3140: 4e 55 4c 4c 2c 20 74 68 65 6e 20 69 74 20 69 73  NULL, then it is
3150: 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20 65 61 63   invoked for eac
3160: 68 20 72 65 73 75 6c 74 20 72 6f 77 0a 2a 2a 20  h result row.** 
3170: 63 6f 6d 69 6e 67 20 6f 75 74 20 6f 66 20 74 68  coming out of th
3180: 65 20 65 76 61 6c 75 61 74 65 64 20 53 51 4c 20  e evaluated SQL 
3190: 73 74 61 74 65 6d 65 6e 74 73 2e 20 20 5e 54 68  statements.  ^Th
31a0: 65 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74  e 4th argument t
31b0: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
31c0: 63 28 29 20 69 73 20 72 65 6c 61 79 65 64 20 74  c() is relayed t
31d0: 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73  hrough to the 1s
31e0: 74 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61  t argument of ea
31f0: 63 68 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69  ch.** callback i
3200: 6e 76 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20  nvocation.  ^If 
3210: 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69  the callback poi
3220: 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  nter to sqlite3_
3230: 65 78 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c  exec().** is NUL
3240: 4c 2c 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62  L, then no callb
3250: 61 63 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f  ack is ever invo
3260: 6b 65 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72  ked and result r
3270: 6f 77 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72  ows are.** ignor
3280: 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ed..**.** ^If an
3290: 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68   error occurs wh
32a0: 69 6c 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74  ile evaluating t
32b0: 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
32c0: 73 20 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a  s passed into.**
32d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c   sqlite3_exec(),
32e0: 20 74 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20   then execution 
32f0: 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  of the current s
3300: 74 61 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61  tatement stops a
3310: 6e 64 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74  nd.** subsequent
3320: 20 73 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20   statements are 
3330: 73 6b 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68  skipped.  ^If th
3340: 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 5th parameter 
3350: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
3360: 29 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  ).** is not NULL
3370: 20 74 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20   then any error 
3380: 6d 65 73 73 61 67 65 20 69 73 20 77 72 69 74 74  message is writt
3390: 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f  en into memory o
33a0: 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20  btained.** from 
33b0: 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
33c0: 29 5d 20 61 6e 64 20 70 61 73 73 65 64 20 62 61  )] and passed ba
33d0: 63 6b 20 74 68 72 6f 75 67 68 20 74 68 65 20 35  ck through the 5
33e0: 74 68 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a  th parameter..**
33f0: 20 54 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79   To avoid memory
3400: 20 6c 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c   leaks, the appl
3410: 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69  ication should i
3420: 6e 76 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66  nvoke [sqlite3_f
3430: 72 65 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72  ree()].** on err
3440: 6f 72 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  or message strin
3450: 67 73 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f  gs returned thro
3460: 75 67 68 20 74 68 65 20 35 74 68 20 70 61 72 61  ugh the 5th para
3470: 6d 65 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73  meter of.** of s
3480: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 61 66  qlite3_exec() af
3490: 74 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65  ter the error me
34a0: 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73 20  ssage string is 
34b0: 6e 6f 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64  no longer needed
34c0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68  ..** ^If the 5th
34d0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
34e0: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73 20  lite3_exec() is 
34f0: 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20  not NULL and no 
3500: 65 72 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c  errors.** occur,
3510: 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78   then sqlite3_ex
3520: 65 63 28 29 20 73 65 74 73 20 74 68 65 20 70 6f  ec() sets the po
3530: 69 6e 74 65 72 20 69 6e 20 69 74 73 20 35 74 68  inter in its 5th
3540: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
3550: 20 4e 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74   NULL before ret
3560: 75 72 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49  urning..**.** ^I
3570: 66 20 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65  f an sqlite3_exe
3580: 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74  c() callback ret
3590: 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74  urns non-zero, t
35a0: 68 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  he sqlite3_exec(
35b0: 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74  ).** routine ret
35c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52  urns SQLITE_ABOR
35d0: 54 20 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69  T without invoki
35e0: 6e 67 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  ng the callback 
35f0: 61 67 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74  again and.** wit
3600: 68 6f 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79  hout running any
3610: 20 73 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20   subsequent SQL 
3620: 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a  statements..**.*
3630: 2a 20 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d  * ^The 2nd argum
3640: 65 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ent to the sqlit
3650: 65 33 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61  e3_exec() callba
3660: 63 6b 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74  ck function is t
3670: 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20  he.** number of 
3680: 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72  columns in the r
3690: 65 73 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64  esult.  ^The 3rd
36a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
36b0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
36c0: 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61  ** callback is a
36d0: 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
36e0: 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f  ers to strings o
36f0: 62 74 61 69 6e 65 64 20 61 73 20 69 66 20 66 72  btained as if fr
3700: 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  om.** [sqlite3_c
3710: 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f  olumn_text()], o
3720: 6e 65 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75  ne for each colu
3730: 6d 6e 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d  mn.  ^If an elem
3740: 65 6e 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75  ent of a.** resu
3750: 6c 74 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74  lt row is NULL t
3760: 68 65 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f  hen the correspo
3770: 6e 64 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69  nding string poi
3780: 6e 74 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20  nter for the.** 
3790: 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63  sqlite3_exec() c
37a0: 61 6c 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c  allback is a NUL
37b0: 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65  L pointer.  ^The
37c0: 20 34 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f   4th argument to
37d0: 20 74 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   the.** sqlite3_
37e0: 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20  exec() callback 
37f0: 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70  is an array of p
3800: 6f 69 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e  ointers to strin
3810: 67 73 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a  gs where each.**
3820: 20 65 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74   entry represent
3830: 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f  s the name of co
3840: 72 72 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75  rresponding resu
3850: 6c 74 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74  lt column as obt
3860: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
3870: 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
3880: 6d 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  me()]..**.** ^If
3890: 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
38a0: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
38b0: 65 63 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70  ec() is a NULL p
38c0: 6f 69 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65  ointer, a pointe
38d0: 72 0a 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79  r.** to an empty
38e0: 20 73 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f   string, or a po
38f0: 69 6e 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61  inter that conta
3900: 69 6e 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70  ins only whitesp
3910: 61 63 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53  ace and/or .** S
3920: 51 4c 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65  QL comments, the
3930: 6e 20 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65  n no SQL stateme
3940: 6e 74 73 20 61 72 65 20 65 76 61 6c 75 61 74 65  nts are evaluate
3950: 64 20 61 6e 64 20 74 68 65 20 64 61 74 61 62 61  d and the databa
3960: 73 65 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61  se.** is not cha
3970: 6e 67 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74  nged..**.** Rest
3980: 72 69 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20  rictions:.**.** 
3990: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
39a0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
39b0: 74 20 69 6e 73 75 72 65 20 74 68 61 74 20 74 68  t insure that th
39c0: 65 20 31 73 74 20 70 61 72 61 6d 65 74 65 72 20  e 1st parameter 
39d0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
39e0: 29 0a 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76  ).**      is a v
39f0: 61 6c 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64  alid and open [d
3a00: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
3a10: 6f 6e 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  on]..** <li> The
3a20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
3a30: 74 20 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74  t not close [dat
3a40: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a50: 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a  ] specified by.*
3a60: 2a 20 20 20 20 20 20 74 68 65 20 31 73 74 20 70  *      the 1st p
3a70: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
3a80: 74 65 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65  te3_exec() while
3a90: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20   sqlite3_exec() 
3aa0: 69 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c  is running..** <
3ab0: 6c 69 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74  li> The applicat
3ac0: 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64  ion must not mod
3ad0: 69 66 79 20 74 68 65 20 53 51 4c 20 73 74 61 74  ify the SQL stat
3ae0: 65 6d 65 6e 74 20 74 65 78 74 20 70 61 73 73 65  ement text passe
3af0: 64 20 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74  d into.**      t
3b00: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
3b10: 20 6f 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63   of sqlite3_exec
3b20: 28 29 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33  () while sqlite3
3b30: 5f 65 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69  _exec() is runni
3b40: 6e 67 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a  ng..** </ul>.*/.
3b50: 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63  int sqlite3_exec
3b60: 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 20  (.  sqlite3*,   
3b70: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3b80: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3b90: 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
3ba0: 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
3bb0: 61 72 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20  ar *sql,        
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20     /* SQL to be 
3be0: 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69  evaluated */.  i
3bf0: 6e 74 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76  nt (*callback)(v
3c00: 6f 69 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c  oid*,int,char**,
3c10: 63 68 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c  char**),  /* Cal
3c20: 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a  lback function *
3c30: 2f 0a 20 20 76 6f 69 64 20 2a 2c 20 20 20 20 20  /.  void *,     
3c40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3c50: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f                 /
3c60: 2a 20 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74  * 1st argument t
3c70: 6f 20 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20  o callback */.  
3c80: 63 68 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20  char **errmsg   
3c90: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3ca0: 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 45 72             /* Er
3cb0: 72 6f 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20  ror msg written 
3cc0: 68 65 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a  here */.);../*.*
3cd0: 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 73 75  * CAPI3REF: Resu
3ce0: 6c 74 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57  lt Codes.** KEYW
3cf0: 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20  ORDS: SQLITE_OK 
3d00: 7b 65 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72  {error code} {er
3d10: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
3d20: 59 57 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20  YWORDS: {result 
3d30: 63 6f 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f  code} {result co
3d40: 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20  des}.**.** Many 
3d50: 53 51 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73  SQLite functions
3d60: 20 72 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67   return an integ
3d70: 65 72 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66  er result code f
3d80: 72 6f 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77  rom the set show
3d90: 6e 0a 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64  n.** here in ord
3da0: 65 72 20 74 6f 20 69 6e 64 69 63 61 74 65 20 73  er to indicate s
3db0: 75 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72  uccess or failur
3dc0: 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72  e..**.** New err
3dd0: 6f 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20  or codes may be 
3de0: 61 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20  added in future 
3df0: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
3e00: 74 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  te..**.** See al
3e10: 73 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  so: [SQLITE_IOER
3e20: 52 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65  R_READ | extende
3e30: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c  d result codes],
3e40: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61  .** [sqlite3_vta
3e50: 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d  b_on_conflict()]
3e60: 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43   [SQLITE_ROLLBAC
3e70: 4b 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73  K | result codes
3e80: 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ]..*/.#define SQ
3e90: 4c 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20  LITE_OK         
3ea0: 20 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73    0   /* Success
3eb0: 66 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a  ful result */./*
3ec0: 20 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72   beginning-of-er
3ed0: 72 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65  ror-codes */.#de
3ee0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f  fine SQLITE_ERRO
3ef0: 52 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20  R        1   /* 
3f00: 53 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73  SQL error or mis
3f10: 73 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f  sing database */
3f20: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
3f30: 49 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20  INTERNAL     2  
3f40: 20 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67   /* Internal log
3f50: 69 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69  ic error in SQLi
3f60: 74 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  te */.#define SQ
3f70: 4c 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20  LITE_PERM       
3f80: 20 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20    3   /* Access 
3f90: 70 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65  permission denie
3fa0: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
3fb0: 49 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20  ITE_ABORT       
3fc0: 20 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b   4   /* Callback
3fd0: 20 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74   routine request
3fe0: 65 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23  ed an abort */.#
3ff0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55  define SQLITE_BU
4000: 53 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f  SY         5   /
4010: 2a 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66  * The database f
4020: 69 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f  ile is locked */
4030: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4040: 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20  LOCKED       6  
4050: 20 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74   /* A table in t
4060: 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c  he database is l
4070: 6f 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65  ocked */.#define
4080: 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20   SQLITE_NOMEM   
4090: 20 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61       7   /* A ma
40a0: 6c 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f  lloc() failed */
40b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
40c0: 52 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20  READONLY     8  
40d0: 20 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77   /* Attempt to w
40e0: 72 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20  rite a readonly 
40f0: 64 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66  database */.#def
4100: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52  ine SQLITE_INTER
4110: 52 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f  RUPT    9   /* O
4120: 70 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61  peration termina
4130: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
4140: 6e 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65  nterrupt()*/.#de
4150: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4160: 52 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20  R       10   /* 
4170: 53 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73  Some kind of dis
4180: 6b 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75  k I/O error occu
4190: 72 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  rred */.#define 
41a0: 53 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20  SQLITE_CORRUPT  
41b0: 20 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64     11   /* The d
41c0: 61 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61  atabase disk ima
41d0: 67 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20  ge is malformed 
41e0: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
41f0: 45 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32  E_NOTFOUND    12
4200: 20 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70     /* Unknown op
4210: 63 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f  code in sqlite3_
4220: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a  file_control() *
4230: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4240: 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20  _FULL        13 
4250: 20 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66    /* Insertion f
4260: 61 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61  ailed because da
4270: 74 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a  tabase is full *
4280: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
4290: 5f 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20  _CANTOPEN    14 
42a0: 20 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f    /* Unable to o
42b0: 70 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  pen the database
42c0: 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65   file */.#define
42d0: 20 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c   SQLITE_PROTOCOL
42e0: 20 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61      15   /* Data
42f0: 62 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63  base lock protoc
4300: 6f 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  ol error */.#def
4310: 69 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59  ine SQLITE_EMPTY
4320: 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44         16   /* D
4330: 61 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79  atabase is empty
4340: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
4350: 54 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31  TE_SCHEMA      1
4360: 37 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62  7   /* The datab
4370: 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67  ase schema chang
4380: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4390: 4c 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20  LITE_TOOBIG     
43a0: 20 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20   18   /* String 
43b0: 6f 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20  or BLOB exceeds 
43c0: 73 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64  size limit */.#d
43d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
43e0: 53 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a  STRAINT  19   /*
43f0: 20 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f   Abort due to co
4400: 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
4410: 6f 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  on */.#define SQ
4420: 4c 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20  LITE_MISMATCH   
4430: 20 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79   20   /* Data ty
4440: 70 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23  pe mismatch */.#
4450: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49  define SQLITE_MI
4460: 53 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f  SUSE      21   /
4470: 2a 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69  * Library used i
4480: 6e 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64  ncorrectly */.#d
4490: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c  efine SQLITE_NOL
44a0: 46 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a  FS       22   /*
44b0: 20 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65   Uses OS feature
44c0: 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20  s not supported 
44d0: 6f 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69  on host */.#defi
44e0: 6e 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20  ne SQLITE_AUTH  
44f0: 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75        23   /* Au
4500: 74 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69  thorization deni
4510: 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  ed */.#define SQ
4520: 4c 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20  LITE_FORMAT     
4530: 20 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61   24   /* Auxilia
4540: 72 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d  ry database form
4550: 61 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66  at error */.#def
4560: 69 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45  ine SQLITE_RANGE
4570: 20 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32         25   /* 2
4580: 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
4590: 73 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74  sqlite3_bind out
45a0: 20 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65   of range */.#de
45b0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41  fine SQLITE_NOTA
45c0: 44 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20  DB      26   /* 
45d0: 46 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74  File opened that
45e0: 20 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61   is not a databa
45f0: 73 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69  se file */.#defi
4600: 6e 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20  ne SQLITE_ROW   
4610: 20 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71        100  /* sq
4620: 6c 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73  lite3_step() has
4630: 20 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61   another row rea
4640: 64 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  dy */.#define SQ
4650: 4c 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20  LITE_DONE       
4660: 20 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33   101  /* sqlite3
4670: 5f 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69  _step() has fini
4680: 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a  shed executing *
4690: 2f 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f  /./* end-of-erro
46a0: 72 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a  r-codes */../*.*
46b0: 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65  * CAPI3REF: Exte
46c0: 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
46d0: 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b  s.** KEYWORDS: {
46e0: 65 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63  extended error c
46f0: 6f 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65  ode} {extended e
4700: 72 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b  rror codes}.** K
4710: 45 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64  EYWORDS: {extend
4720: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20  ed result code} 
4730: 7b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  {extended result
4740: 20 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e   codes}.**.** In
4750: 20 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e   its default con
4760: 66 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69  figuration, SQLi
4770: 74 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20  te API routines 
4780: 72 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36  return one of 26
4790: 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c   integer.** [SQL
47a0: 49 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20  ITE_OK | result 
47b0: 63 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72  codes].  However
47c0: 2c 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73  , experience has
47d0: 20 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79   shown that many
47e0: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73   of.** these res
47f0: 75 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f  ult codes are to
4800: 6f 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64  o coarse-grained
4810: 2e 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70  .  They do not p
4820: 72 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63  rovide as.** muc
4830: 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62  h information ab
4840: 6f 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20  out problems as 
4850: 70 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68  programmers migh
4860: 74 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65  t like.  In an e
4870: 66 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72  ffort to.** addr
4880: 65 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20  ess this, newer 
4890: 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
48a0: 74 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e  te (version 3.3.
48b0: 38 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63  8 and later) inc
48c0: 6c 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20  lude.** support 
48d0: 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72  for additional r
48e0: 65 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74  esult codes that
48f0: 20 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65   provide more de
4900: 74 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69  tailed informati
4910: 6f 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f  on.** about erro
4920: 72 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64  rs. The extended
4930: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72   result codes ar
4940: 65 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73  e enabled or dis
4950: 61 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65  abled.** on a pe
4960: 72 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  r database conne
4970: 63 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e  ction basis usin
4980: 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
4990: 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c  3_extended_resul
49a0: 74 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a  t_codes()] API..
49b0: 2a 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68  **.** Some of th
49c0: 65 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65  e available exte
49d0: 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
49e0: 73 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72  s are listed her
49f0: 65 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78  e..** One may ex
4a00: 70 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20  pect the number 
4a10: 6f 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75  of extended resu
4a20: 6c 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65  lt codes will be
4a30: 20 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20   expand.** over 
4a40: 74 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20  time.  Software 
4a50: 74 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64  that uses extend
4a60: 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20  ed result codes 
4a70: 73 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a  should expect.**
4a80: 20 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75   to see new resu
4a90: 6c 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75  lt codes in futu
4aa0: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
4ab0: 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  QLite..**.** The
4ac0: 20 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c   SQLITE_OK resul
4ad0: 74 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65  t code will neve
4ae0: 72 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20  r be extended.  
4af0: 49 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a  It will always.*
4b00: 2a 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72  * be exactly zer
4b10: 6f 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  o..*/.#define SQ
4b20: 4c 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20  LITE_IOERR_READ 
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51               (SQ
4b40: 4c 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c  LITE_IOERR | (1<
4b50: 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c  <8)).#define SQL
4b60: 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f  ITE_IOERR_SHORT_
4b70: 52 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c  READ        (SQL
4b80: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c  ITE_IOERR | (2<<
4b90: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4ba0: 54 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20  TE_IOERR_WRITE  
4bb0: 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49             (SQLI
4bc0: 54 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38  TE_IOERR | (3<<8
4bd0: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4be0: 45 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20  E_IOERR_FSYNC   
4bf0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4c00: 45 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29  E_IOERR | (4<<8)
4c10: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4c20: 5f 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43  _IOERR_DIR_FSYNC
4c30: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c40: 5f 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29  _IOERR | (5<<8))
4c50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c60: 49 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20  IOERR_TRUNCATE  
4c70: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c80: 49 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a  IOERR | (6<<8)).
4c90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4ca0: 4f 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20  OERR_FSTAT      
4cb0: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4cc0: 4f 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23  OERR | (7<<8)).#
4cd0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ce0: 45 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20  ERR_UNLOCK      
4cf0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4d00: 45 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64  ERR | (8<<8)).#d
4d10: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4d20: 52 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20  RR_RDLOCK       
4d30: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d40: 52 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65  RR | (9<<8)).#de
4d50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d60: 52 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20  R_DELETE        
4d70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d80: 52 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65  R | (10<<8)).#de
4d90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4da0: 52 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20  R_BLOCKED       
4db0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4dc0: 52 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65  R | (11<<8)).#de
4dd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4de0: 52 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20  R_NOMEM         
4df0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e00: 52 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65  R | (12<<8)).#de
4e10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e20: 52 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20  R_ACCESS        
4e30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4e40: 52 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65  R | (13<<8)).#de
4e50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4e60: 52 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c  R_CHECKRESERVEDL
4e70: 4f 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52  OCK (SQLITE_IOER
4e80: 52 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65  R | (14<<8)).#de
4e90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ea0: 52 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20  R_LOCK          
4eb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4ec0: 52 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65  R | (15<<8)).#de
4ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4ee0: 52 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20  R_CLOSE         
4ef0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f00: 52 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65  R | (16<<8)).#de
4f10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f20: 52 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20  R_DIR_CLOSE     
4f30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f40: 52 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65  R | (17<<8)).#de
4f50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4f60: 52 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20  R_SHMOPEN       
4f70: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4f80: 52 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65  R | (18<<8)).#de
4f90: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fa0: 52 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20  R_SHMSIZE       
4fb0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4fc0: 52 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65  R | (19<<8)).#de
4fd0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4fe0: 52 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20  R_SHMLOCK       
4ff0: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5000: 52 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65  R | (20<<8)).#de
5010: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5020: 52 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20  R_SHMMAP        
5030: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5040: 52 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65  R | (21<<8)).#de
5050: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
5060: 52 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20  R_SEEK          
5070: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
5080: 52 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65  R | (22<<8)).#de
5090: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
50a0: 45 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20  ED_SHAREDCACHE  
50b0: 20 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b      (SQLITE_LOCK
50c0: 45 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64  ED |  (1<<8)).#d
50d0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
50e0: 59 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20  Y_RECOVERY      
50f0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53       (SQLITE_BUS
5100: 59 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23  Y   |  (1<<8)).#
5110: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41  define SQLITE_CA
5120: 4e 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52  NTOPEN_NOTEMPDIR
5130: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41        (SQLITE_CA
5140: 4e 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29  NTOPEN | (1<<8))
5150: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 43 41 4e 54 4f 50 45 4e 5f 49 53 44 49 52 20 20  CANTOPEN_ISDIR  
5170: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
5180: 43 41 4e 54 4f 50 45 4e 20 7c 20 28 32 3c 3c 38  CANTOPEN | (2<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 43 4f 52 52 55 50 54 5f 56 54 41 42 20 20  E_CORRUPT_VTAB  
51b0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
51c0: 45 5f 43 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c  E_CORRUPT | (1<<
51d0: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
51e0: 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f  TE_READONLY_RECO
51f0: 56 45 52 59 20 20 20 20 20 20 20 28 53 51 4c 49  VERY       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31  TE_READONLY | (1
5210: 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51  <<8)).#define SQ
5220: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41  LITE_READONLY_CA
5230: 4e 54 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51  NTLOCK       (SQ
5240: 4c 49 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20  LITE_READONLY | 
5250: 28 32 3c 3c 38 29 29 0a 23 64 65 66 69 6e 65 20  (2<<8)).#define 
5260: 53 51 4c 49 54 45 5f 41 42 4f 52 54 5f 52 4f 4c  SQLITE_ABORT_ROL
5270: 4c 42 41 43 4b 20 20 20 20 20 20 20 20 20 20 28  LBACK          (
5280: 53 51 4c 49 54 45 5f 41 42 4f 52 54 20 7c 20 28  SQLITE_ABORT | (
5290: 32 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41  2<<8))../*.** CA
52a0: 50 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f  PI3REF: Flags Fo
52b0: 72 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72  r File Open Oper
52c0: 61 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ations.**.** The
52d0: 73 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72  se bit values ar
52e0: 65 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75  e intended for u
52f0: 73 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64  se in the.** 3rd
5300: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
5310: 65 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  e [sqlite3_open_
5320: 76 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  v2()] interface 
5330: 61 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74  and.** in the 4t
5340: 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
5350: 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e  he [sqlite3_vfs.
5360: 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a  xOpen] method..*
5370: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5380: 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20  _OPEN_READONLY  
5390: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53a0: 31 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  1  /* Ok for sql
53b0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
53c0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
53d0: 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
53e0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
53f0: 32 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  2  /* Ok for sql
5400: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5410: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5420: 5f 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20  _OPEN_CREATE    
5430: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30         0x0000000
5440: 34 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  4  /* Ok for sql
5450: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5460: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5470: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
5480: 4f 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30  OSE    0x0000000
5490: 38 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  8  /* VFS only *
54a0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54b0: 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20  _OPEN_EXCLUSIVE 
54c0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
54d0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
54e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
54f0: 5f 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20  _OPEN_AUTOPROXY 
5500: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5510: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5520: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5530: 5f 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20  _OPEN_URI       
5540: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34         0x0000004
5550: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5560: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5570: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5580: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20  _OPEN_MAIN_DB   
5590: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30         0x0000010
55a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
55b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
55c0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20  _OPEN_TEMP_DB   
55d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30         0x0000020
55e0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
55f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5600: 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f  _OPEN_TRANSIENT_
5610: 44 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30  DB     0x0000040
5620: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5630: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5640: 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e  _OPEN_MAIN_JOURN
5650: 41 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30  AL     0x0000080
5660: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5670: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5680: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
5690: 41 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30  AL     0x0000100
56a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
56b0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
56c0: 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c  _OPEN_SUBJOURNAL
56d0: 20 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30         0x0000200
56e0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
56f0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5700: 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55  _OPEN_MASTER_JOU
5710: 52 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30  RNAL   0x0000400
5720: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
5730: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5740: 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20  _OPEN_NOMUTEX   
5750: 20 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30         0x0000800
5760: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5770: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5780: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5790: 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20  _OPEN_FULLMUTEX 
57a0: 20 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30         0x0001000
57b0: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
57c0: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
57d0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
57e0: 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
57f0: 45 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30  E      0x0002000
5800: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5810: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5820: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5830: 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43  _OPEN_PRIVATECAC
5840: 48 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30  HE     0x0004000
5850: 30 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c  0  /* Ok for sql
5860: 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a  ite3_open_v2() *
5870: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
5880: 5f 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20  _OPEN_WAL       
5890: 20 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30         0x0008000
58a0: 30 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a  0  /* VFS only *
58b0: 2f 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20  /../* Reserved: 
58c0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
58d0: 20 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30          0x00F000
58e0: 30 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  00 */../*.** CAP
58f0: 49 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68  I3REF: Device Ch
5900: 61 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a  aracteristics.**
5910: 0a 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43  .** The xDeviceC
5920: 68 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d  haracteristics m
5930: 65 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71  ethod of the [sq
5940: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
5950: 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75  ].** object retu
5960: 72 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77  rns an integer w
5970: 68 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72  hich is a vector
5980: 20 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a   of the these.**
5990: 20 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72   bit values expr
59a0: 65 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61  essing I/O chara
59b0: 63 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68  cteristics of th
59c0: 65 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a  e mass storage.*
59d0: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f  * device that ho
59e0: 6c 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61  lds the file tha
59f0: 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69  t the [sqlite3_i
5a00: 6f 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65  o_methods].** re
5a10: 66 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54  fers to..**.** T
5a20: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
5a30: 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20  ATOMIC property 
5a40: 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77  means that all w
5a50: 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20  rites of.** any 
5a60: 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e  size are atomic.
5a70: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5a80: 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c  AP_ATOMICnnn val
5a90: 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74  ues.** mean that
5aa0: 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b   writes of block
5ab0: 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62  s that are nnn b
5ac0: 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64  ytes in size and
5ad0: 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20  .** are aligned 
5ae0: 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68  to an address wh
5af0: 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ich is an intege
5b00: 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a  r multiple of.**
5b10: 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e   nnn are atomic.
5b20: 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43    The SQLITE_IOC
5b30: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76  AP_SAFE_APPEND v
5b40: 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68  alue means.** th
5b50: 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20  at when data is 
5b60: 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69  appended to a fi
5b70: 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20  le, the data is 
5b80: 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73  appended.** firs
5b90: 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20  t then the size 
5ba0: 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65  of the file is e
5bb0: 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74  xtended, never t
5bc0: 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20  he other.** way 
5bd0: 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c  around.  The SQL
5be0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5bf0: 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65  TIAL property me
5c00: 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f  ans that.** info
5c10: 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74  rmation is writt
5c20: 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68  en to disk in th
5c30: 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20  e same order as 
5c40: 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69  calls.** to xWri
5c50: 74 65 28 29 2e 20 20 54 68 65 20 53 51 4c 49 54  te().  The SQLIT
5c60: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
5c70: 45 5f 4f 56 45 52 57 52 49 54 45 20 70 72 6f 70  E_OVERWRITE prop
5c80: 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a  erty means that.
5c90: 2a 2a 20 61 66 74 65 72 20 72 65 62 6f 6f 74 20  ** after reboot 
5ca0: 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 72 61 73  following a cras
5cb0: 68 20 6f 72 20 70 6f 77 65 72 20 6c 6f 73 73 2c  h or power loss,
5cc0: 20 74 68 65 20 6f 6e 6c 79 20 62 79 74 65 73 20   the only bytes 
5cd0: 69 6e 20 61 0a 2a 2a 20 66 69 6c 65 20 74 68 61  in a.** file tha
5ce0: 74 20 77 65 72 65 20 77 72 69 74 74 65 6e 20 61  t were written a
5cf0: 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  t the applicatio
5d00: 6e 20 6c 65 76 65 6c 20 6d 69 67 68 74 20 68 61  n level might ha
5d10: 76 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 61 6e  ve changed.** an
5d20: 64 20 74 68 61 74 20 61 64 6a 61 63 65 6e 74 20  d that adjacent 
5d30: 62 79 74 65 73 2c 20 65 76 65 6e 20 62 79 74 65  bytes, even byte
5d40: 73 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d  s within the sam
5d50: 65 20 73 65 63 74 6f 72 20 61 72 65 0a 2a 2a 20  e sector are.** 
5d60: 67 75 61 72 61 6e 74 65 65 64 20 74 6f 20 62 65  guaranteed to be
5d70: 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2f 0a 23   unchanged..*/.#
5d80: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5d90: 43 41 50 5f 41 54 4f 4d 49 43 20 20 20 20 20 20  CAP_ATOMIC      
5da0: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5db0: 30 30 30 30 31 0a 23 64 65 66 69 6e 65 20 53 51  00001.#define SQ
5dc0: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5dd0: 43 35 31 32 20 20 20 20 20 20 20 20 20 20 20 20  C512            
5de0: 20 20 30 78 30 30 30 30 30 30 30 32 0a 23 64 65    0x00000002.#de
5df0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5e00: 50 5f 41 54 4f 4d 49 43 31 4b 20 20 20 20 20 20  P_ATOMIC1K      
5e10: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5e20: 30 30 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  004.#define SQLI
5e30: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 32  TE_IOCAP_ATOMIC2
5e40: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5e50: 30 78 30 30 30 30 30 30 30 38 0a 23 64 65 66 69  0x00000008.#defi
5e60: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5e70: 41 54 4f 4d 49 43 34 4b 20 20 20 20 20 20 20 20  ATOMIC4K        
5e80: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31         0x0000001
5e90: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5ea0: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 38 4b 20  _IOCAP_ATOMIC8K 
5eb0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5ec0: 30 30 30 30 30 30 32 30 0a 23 64 65 66 69 6e 65  00000020.#define
5ed0: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5ee0: 4f 4d 49 43 31 36 4b 20 20 20 20 20 20 20 20 20  OMIC16K         
5ef0: 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30 0a       0x00000040.
5f00: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5f10: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 20 20  OCAP_ATOMIC32K  
5f20: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5f30: 30 30 30 30 38 30 0a 23 64 65 66 69 6e 65 20 53  000080.#define S
5f40: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
5f50: 49 43 36 34 4b 20 20 20 20 20 20 20 20 20 20 20  IC64K           
5f60: 20 20 20 30 78 30 30 30 30 30 31 30 30 0a 23 64     0x00000100.#d
5f70: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5f80: 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 20  AP_SAFE_APPEND  
5f90: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5fa0: 30 32 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0200.#define SQL
5fb0: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
5fc0: 54 49 41 4c 20 20 20 20 20 20 20 20 20 20 20 20  TIAL            
5fd0: 20 30 78 30 30 30 30 30 34 30 30 0a 23 64 65 66   0x00000400.#def
5fe0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  ine SQLITE_IOCAP
5ff0: 5f 55 4e 44 45 4c 45 54 41 42 4c 45 5f 57 48 45  _UNDELETABLE_WHE
6000: 4e 5f 4f 50 45 4e 20 20 30 78 30 30 30 30 30 38  N_OPEN  0x000008
6010: 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  00.#define SQLIT
6020: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
6030: 45 5f 4f 56 45 52 57 52 49 54 45 20 20 20 20 30  E_OVERWRITE    0
6040: 78 30 30 30 30 31 30 30 30 0a 0a 2f 2a 0a 2a 2a  x00001000../*.**
6050: 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c 65 20   CAPI3REF: File 
6060: 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73 0a 2a  Locking Levels.*
6070: 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65 73  *.** SQLite uses
6080: 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 69 6e   one of these in
6090: 74 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20  teger values as 
60a0: 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 61 72  the second.** ar
60b0: 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c 73 20  gument to calls 
60c0: 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68 65 20  it makes to the 
60d0: 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55 6e 6c  xLock() and xUnl
60e0: 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a 2a 2a  ock() methods.**
60f0: 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f   of an [sqlite3_
6100: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
6110: 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  ct..*/.#define S
6120: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 20  QLITE_LOCK_NONE 
6130: 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
6140: 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  ne SQLITE_LOCK_S
6150: 48 41 52 45 44 20 20 20 20 20 20 20 20 31 0a 23  HARED        1.#
6160: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f  define SQLITE_LO
6170: 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20 20 20  CK_RESERVED     
6180: 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   2.#define SQLIT
6190: 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 20 20  E_LOCK_PENDING  
61a0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
61b0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55  QLITE_LOCK_EXCLU
61c0: 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a 0a 2a  SIVE     4../*.*
61d0: 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79 6e 63  * CAPI3REF: Sync
61e0: 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79 70 65  hronization Type
61f0: 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57 68 65   Flags.**.** Whe
6200: 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  n SQLite invokes
6210: 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d 65 74   the xSync() met
6220: 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b 73 71  hod of an.** [sq
6230: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
6240: 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73 65 73  ] object it uses
6250: 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f   a combination o
6260: 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74 65 67  f.** these integ
6270: 65 72 20 76 61 6c 75 65 73 20 61 73 20 74 68 65  er values as the
6280: 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
6290: 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
62a0: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54   SQLITE_SYNC_DAT
62b0: 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20 75 73  AONLY flag is us
62c0: 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61  ed, it means tha
62d0: 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20 6f 70  t the.** sync op
62e0: 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e 65 65  eration only nee
62f0: 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61 74 61  ds to flush data
6300: 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61 67 65   to mass storage
6310: 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e 66 6f  .  Inode.** info
6320: 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e 6f 74  rmation need not
6330: 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49 66 20   be flushed. If 
6340: 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62  the lower four b
6350: 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61 67 0a  its of the flag.
6360: 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ** equal SQLITE_
6370: 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74 68 61  SYNC_NORMAL, tha
6380: 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65 20 6e  t means to use n
6390: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20 73 65  ormal fsync() se
63a0: 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66 20 74  mantics..** If t
63b0: 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20 62 69  he lower four bi
63c0: 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54 45 5f  ts equal SQLITE_
63d0: 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61 74 20  SYNC_FULL, that 
63e0: 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73 65 20  means.** to use 
63f0: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6400: 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61 64 20  ullsync instead 
6410: 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a 0a 2a  of fsync()..**.*
6420: 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75 73 65  * Do not confuse
6430: 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43   the SQLITE_SYNC
6440: 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51 4c 49  _NORMAL and SQLI
6450: 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66 6c 61  TE_SYNC_FULL fla
6460: 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b  gs.** with the [
6470: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
6480: 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64 20 5b  us]=NORMAL and [
6490: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
64a0: 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65 74 74  us]=FULL.** sett
64b0: 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79 6e 63  ings.  The [sync
64c0: 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61 5d 20  hronous pragma] 
64d0: 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65 6e 20  determines when 
64e0: 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a 2a 20  calls to the.** 
64f0: 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68 6f 64  xSync VFS method
6500: 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70 6c 69   occur and appli
6510: 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61 63 72  es uniformly acr
6520: 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f 72 6d  oss all platform
6530: 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  s..** The SQLITE
6540: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6550: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6560: 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d 69 6e  L flags determin
6570: 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67 65 74  e how.** energet
6580: 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73 20 6f  ic or rigorous o
6590: 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65 20 73  r forceful the s
65a0: 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73 20 61  ync operations a
65b0: 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79 20 6d  re and.** only m
65c0: 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e 63 65  ake a difference
65d0: 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f 72 20   on Mac OSX for 
65e0: 74 68 65 20 64 65 66 61 75 6c 74 20 53 51 4c 69  the default SQLi
65f0: 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54 68 69  te code..** (Thi
6600: 72 64 2d 70 61 72 74 79 20 56 46 53 20 69 6d 70  rd-party VFS imp
6610: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 69 67  lementations mig
6620: 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74 68 65  ht also make the
6630: 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a 2a 20   distinction.** 
6640: 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45 5f 53  between SQLITE_S
6650: 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53  YNC_NORMAL and S
6660: 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c  QLITE_SYNC_FULL,
6670: 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65 0a 2a   but among the.*
6680: 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  * operating syst
6690: 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73 75 70  ems natively sup
66a0: 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74 65  ported by SQLite
66b0: 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58 0a 2a  , only Mac OSX.*
66c0: 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20 74 68  * cares about th
66d0: 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29 0a 2a  e difference.).*
66e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
66f0: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20 20 20  _SYNC_NORMAL    
6700: 20 20 20 20 30 78 30 30 30 30 32 0a 23 64 65 66      0x00002.#def
6710: 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f  ine SQLITE_SYNC_
6720: 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20 30 78  FULL          0x
6730: 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20 53 51  00003.#define SQ
6740: 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f 4e  LITE_SYNC_DATAON
6750: 4c 59 20 20 20 20 20 20 30 78 30 30 30 31 30 0a  LY      0x00010.
6760: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
6770: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 70   OS Interface Op
6780: 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65 0a 2a  en File Handle.*
6790: 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74 65 33  *.** An [sqlite3
67a0: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 72 65  _file] object re
67b0: 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70 65 6e  presents an open
67c0: 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a 2a 2a   file in the .**
67d0: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20   [sqlite3_vfs | 
67e0: 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79  OS interface lay
67f0: 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75 61 6c  er].  Individual
6800: 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a   OS interface.**
6810: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73   implementations
6820: 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20 74 6f   will.** want to
6830: 20 73 75 62 63 6c 61 73 73 20 74 68 69 73 20 6f   subclass this o
6840: 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e 64 69  bject by appendi
6850: 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20 66 69  ng additional fi
6860: 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68 65 69  elds.** for thei
6870: 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68 65 20  r own use.  The 
6880: 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79 20 69  pMethods entry i
6890: 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
68a0: 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 69 6f  n.** [sqlite3_io
68b0: 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74  _methods] object
68c0: 20 74 68 61 74 20 64 65 66 69 6e 65 73 20 6d 65   that defines me
68d0: 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66 6f 72  thods for perfor
68e0: 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70 65 72  ming.** I/O oper
68f0: 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20 6f 70  ations on the op
6900: 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79 70 65  en file..*/.type
6910: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
6920: 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65 33 5f  e3_file sqlite3_
6930: 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73 71 6c  file;.struct sql
6940: 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20 63 6f  ite3_file {.  co
6950: 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c 69 74  nst struct sqlit
6960: 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 2a 70  e3_io_methods *p
6970: 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d 65 74  Methods;  /* Met
6980: 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70 65 6e  hods for an open
6990: 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a   file */.};../*.
69a0: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 53 20  ** CAPI3REF: OS 
69b0: 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65 20 56  Interface File V
69c0: 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73 20 4f  irtual Methods O
69d0: 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76 65 72  bject.**.** Ever
69e0: 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20 62 79  y file opened by
69f0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 66   the [sqlite3_vf
6a00: 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 20  s.xOpen] method 
6a10: 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a 2a 20  populates an.** 
6a20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
6a30: 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72 65 20  bject (or, more 
6a40: 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75 62 63  commonly, a subc
6a50: 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  lass of the.** [
6a60: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f 62  sqlite3_file] ob
6a70: 6a 65 63 74 29 20 77 69 74 68 20 61 20 70 6f 69  ject) with a poi
6a80: 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73 74 61  nter to an insta
6a90: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
6aa0: 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65  ct..** This obje
6ab0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 6d  ct defines the m
6ac0: 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f 20 70  ethods used to p
6ad0: 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73 20 6f  erform various o
6ae0: 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 67 61  perations.** aga
6af0: 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20 66 69  inst the open fi
6b00: 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64 20 62  le represented b
6b10: 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66  y the [sqlite3_f
6b20: 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a  ile] object..**.
6b30: 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c 69 74  ** If the [sqlit
6b40: 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65  e3_vfs.xOpen] me
6b50: 74 68 6f 64 20 73 65 74 73 20 74 68 65 20 73 71  thod sets the sq
6b60: 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68  lite3_file.pMeth
6b70: 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a 2a 20  ods element .** 
6b80: 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f  to a non-NULL po
6b90: 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20  inter, then the 
6ba0: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6bb0: 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68 6f 64  ds.xClose method
6bc0: 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76 6f 6b  .** may be invok
6bd0: 65 64 20 65 76 65 6e 20 69 66 20 74 68 65 20 5b  ed even if the [
6be0: 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65  sqlite3_vfs.xOpe
6bf0: 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68 61 74  n] reported that
6c00: 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54 68 65   it failed.  The
6c10: 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74 6f 20  .** only way to 
6c20: 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c 20 74  prevent a call t
6c30: 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f 77 69  o xClose followi
6c40: 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73 71 6c  ng a failed [sql
6c50: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 0a  ite3_vfs.xOpen].
6c60: 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20 5b 73  ** is for the [s
6c70: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6c80: 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73 71 6c  ] to set the sql
6c90: 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f  ite3_file.pMetho
6ca0: 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20 74 6f  ds element.** to
6cb0: 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65   NULL..**.** The
6cc0: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
6cd0: 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62 65 20  to xSync may be 
6ce0: 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f 53  one of [SQLITE_S
6cf0: 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72 0a 2a  YNC_NORMAL] or.*
6d00: 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  * [SQLITE_SYNC_F
6d10: 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72 73 74  ULL].  The first
6d20: 20 63 68 6f 69 63 65 20 69 73 20 74 68 65 20 6e   choice is the n
6d30: 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e 0a 2a  ormal fsync()..*
6d40: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63 68 6f  * The second cho
6d50: 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f 53 20  ice is a Mac OS 
6d60: 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79 6e 63  X style fullsync
6d70: 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 53  .  The [SQLITE_S
6d80: 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a 2a 2a  YNC_DATAONLY].**
6d90: 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f 52 65   flag may be ORe
6da0: 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61 74 65  d in to indicate
6db0: 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65 20 64   that only the d
6dc0: 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c 65 0a  ata of the file.
6dd0: 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73 20 69  ** and not its i
6de0: 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20 62 65  node needs to be
6df0: 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a 20 54   synced..**.** T
6e00: 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  he integer value
6e10: 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61 6e 64  s to xLock() and
6e20: 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65 20 6f   xUnlock() are o
6e30: 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  ne of.** <ul>.**
6e40: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f   <li> [SQLITE_LO
6e50: 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c 6c 69  CK_NONE],.** <li
6e60: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  > [SQLITE_LOCK_S
6e70: 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  HARED],.** <li> 
6e80: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
6e90: 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20  ERVED],.** <li> 
6ea0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e  [SQLITE_LOCK_PEN
6eb0: 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69  DING], or.** <li
6ec0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  > [SQLITE_LOCK_E
6ed0: 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20 3c 2f  XCLUSIVE]..** </
6ee0: 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29 20 69  ul>.** xLock() i
6ef0: 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ncreases the loc
6f00: 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64 65 63  k. xUnlock() dec
6f10: 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63 6b 2e  reases the lock.
6f20: 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b 52 65  .** The xCheckRe
6f30: 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d 65 74  servedLock() met
6f40: 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65 74 68  hod checks wheth
6f50: 65 72 20 61 6e 79 20 64 61 74 61 62 61 73 65 20  er any database 
6f60: 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a 20 65  connection,.** e
6f70: 69 74 68 65 72 20 69 6e 20 74 68 69 73 20 70 72  ither in this pr
6f80: 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f 6d 65  ocess or in some
6f90: 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73 2c 20   other process, 
6fa0: 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52 45 53  is holding a RES
6fb0: 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44 49 4e  ERVED,.** PENDIN
6fc0: 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20  G, or EXCLUSIVE 
6fd0: 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69 6c 65  lock on the file
6fe0: 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20 74 72  .  It returns tr
6ff0: 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20 61 20  ue.** if such a 
7000: 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e 64 20  lock exists and 
7010: 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73 65 2e  false otherwise.
7020: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69 6c 65  .**.** The xFile
7030: 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68 6f 64  Control() method
7040: 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 69 6e   is a generic in
7050: 74 65 72 66 61 63 65 20 74 68 61 74 20 61 6c 6c  terface that all
7060: 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20 56 46  ows custom.** VF
7070: 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
7080: 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20 63 6f  s to directly co
7090: 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20 66 69  ntrol an open fi
70a0: 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  le using the.** 
70b0: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
70c0: 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72 66 61  ntrol()] interfa
70d0: 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e 64 20  ce.  The second 
70e0: 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20 69 73  "op" argument is
70f0: 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72 20 6f   an.** integer o
7100: 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68 69 72  pcode.  The thir
7110: 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 20  d argument is a 
7120: 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65 72 20  generic pointer 
7130: 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a 20 70  intended to.** p
7140: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75 63 74  oint to a struct
7150: 75 72 65 20 74 68 61 74 20 6d 61 79 20 63 6f 6e  ure that may con
7160: 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73 20 6f  tain arguments o
7170: 72 20 73 70 61 63 65 20 69 6e 20 77 68 69 63 68  r space in which
7180: 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72 65 74   to.** write ret
7190: 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50 6f 74  urn values.  Pot
71a0: 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f 72 20  ential uses for 
71b0: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d  xFileControl() m
71c0: 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e 63 74  ight be.** funct
71d0: 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65 20 62  ions to enable b
71e0: 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20 77 69  locking locks wi
71f0: 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74 6f 20  th timeouts, to 
7200: 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20 6c 6f  change the.** lo
7210: 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79 20 28  cking strategy (
7220: 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f 20 75  for example to u
7230: 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f 63 6b  se dot-file lock
7240: 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65 0a 2a  s), to inquire.*
7250: 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74 61 74  * about the stat
7260: 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20 6f 72  us of a lock, or
7270: 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c 65 20   to break stale 
7280: 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51 4c 69  locks.  The SQLi
7290: 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73 65 72  te.** core reser
72a0: 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65 73 20  ves all opcodes 
72b0: 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 66 6f  less than 100 fo
72c0: 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e 0a 2a  r its own use..*
72d0: 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  * A [SQLITE_FCNT
72e0: 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20 6c 69  L_LOCKSTATE | li
72f0: 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d 20 6c  st of opcodes] l
7300: 65 73 73 20 74 68 61 6e 20 31 30 30 20 69 73 20  ess than 100 is 
7310: 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 41 70  available..** Ap
7320: 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
7330: 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f 6d 20  define a custom 
7340: 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74  xFileControl met
7350: 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65 20 6f  hod should use o
7360: 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61 74 65  pcodes.** greate
7370: 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20 61 76  r than 100 to av
7380: 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e 20 20  oid conflicts.  
7390: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
73a0: 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ons should.** re
73b0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  turn [SQLITE_NOT
73c0: 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c 65 20  FOUND] for file 
73d0: 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65 73 20  control opcodes 
73e0: 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f 74  that they do not
73f0: 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e 0a 2a  .** recognize..*
7400: 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74 6f 72  *.** The xSector
7410: 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20 72 65  Size() method re
7420: 74 75 72 6e 73 20 74 68 65 20 73 65 63 74 6f 72  turns the sector
7430: 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a 2a 20   size of the.** 
7440: 64 65 76 69 63 65 20 74 68 61 74 20 75 6e 64 65  device that unde
7450: 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65 2e 20  rlies the file. 
7460: 20 54 68 65 20 73 65 63 74 6f 72 20 73 69 7a 65   The sector size
7470: 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e 69 6d   is the.** minim
7480: 75 6d 20 77 72 69 74 65 20 74 68 61 74 20 63 61  um write that ca
7490: 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64 20 77  n be performed w
74a0: 69 74 68 6f 75 74 20 64 69 73 74 75 72 62 69 6e  ithout disturbin
74b0: 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74 65 73  g.** other bytes
74c0: 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20 20 54   in the file.  T
74d0: 68 65 20 78 44 65 76 69 63 65 43 68 61 72 61 63  he xDeviceCharac
74e0: 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a 20 6d  teristics().** m
74f0: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
7500: 62 69 74 20 76 65 63 74 6f 72 20 64 65 73 63 72  bit vector descr
7510: 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72 73 20  ibing behaviors 
7520: 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65 72 6c  of the.** underl
7530: 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a 2a 0a  ying device:.**.
7540: 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20  ** <ul>.** <li> 
7550: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7560: 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  OMIC].** <li> [S
7570: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d  QLITE_IOCAP_ATOM
7580: 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  IC512].** <li> [
7590: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75a0: 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC1K].** <li> [
75b0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75c0: 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC2K].** <li> [
75d0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
75e0: 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC4K].** <li> [
75f0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7600: 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b  MIC8K].** <li> [
7610: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
7620: 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69 3e 20  MIC16K].** <li> 
7630: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
7640: 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC32K].** <li>
7650: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7660: 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC64K].** <li
7670: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7680: 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a 2a 20  SAFE_APPEND].** 
7690: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
76a0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d 0a 2a  AP_SEQUENTIAL].*
76b0: 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68  * </ul>.**.** Th
76c0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
76d0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
76e0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
76f0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
7700: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
7710: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
7720: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
7730: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
7740: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
7750: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
7760: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
7770: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
7780: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
7790: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
77a0: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
77b0: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
77c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
77d0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
77e0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
77f0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
7800: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
7810: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
7820: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
7830: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
7840: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
7850: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
7860: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
7870: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
7880: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
7890: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
78a0: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
78b0: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
78c0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
78d0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
78e0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
78f0: 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 78 52  e()..**.** If xR
7900: 65 61 64 28 29 20 72 65 74 75 72 6e 73 20 53 51  ead() returns SQ
7910: 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54  LITE_IOERR_SHORT
7920: 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20 61 6c  _READ it must al
7930: 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20 74 68  so fill.** in th
7940: 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69 6f 6e  e unread portion
7950: 73 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20  s of the buffer 
7960: 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41 20 56  with zeros.  A V
7970: 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69 6c 73  FS that.** fails
7980: 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20 73 68   to zero-fill sh
7990: 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68 74 20  ort reads might 
79a0: 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20 20 48  seem to work.  H
79b0: 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69 6c 75  owever,.** failu
79c0: 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  re to zero-fill 
79d0: 73 68 6f 72 74 20 72 65 61 64 73 20 77 69 6c 6c  short reads will
79e0: 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65 61 64   eventually lead
79f0: 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73 65 20   to.** database 
7a00: 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 74  corruption..*/.t
7a10: 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
7a20: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7a30: 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68   sqlite3_io_meth
7a40: 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69  ods;.struct sqli
7a50: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20 7b  te3_io_methods {
7a60: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
7a70: 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73 65 29  .  int (*xClose)
7a80: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7a90: 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64 29 28  .  int (*xRead)(
7aa0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 76  sqlite3_file*, v
7ab0: 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20  oid*, int iAmt, 
7ac0: 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f  sqlite3_int64 iO
7ad0: 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 57  fst);.  int (*xW
7ae0: 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69  rite)(sqlite3_fi
7af0: 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  le*, const void*
7b00: 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71 6c 69  , int iAmt, sqli
7b10: 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73 74 29  te3_int64 iOfst)
7b20: 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75 6e 63  ;.  int (*xTrunc
7b30: 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  ate)(sqlite3_fil
7b40: 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36  e*, sqlite3_int6
7b50: 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74 20 28  4 size);.  int (
7b60: 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65 33 5f  *xSync)(sqlite3_
7b70: 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61 67 73  file*, int flags
7b80: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65  );.  int (*xFile
7b90: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7ba0: 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  le*, sqlite3_int
7bb0: 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20 69 6e  64 *pSize);.  in
7bc0: 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c 69 74  t (*xLock)(sqlit
7bd0: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a  e3_file*, int);.
7be0: 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63 6b 29    int (*xUnlock)
7bf0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20  (sqlite3_file*, 
7c00: 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  int);.  int (*xC
7c10: 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63 6b  heckReservedLock
7c20: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7c30: 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29 3b 0a   int *pResOut);.
7c40: 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43 6f 6e    int (*xFileCon
7c50: 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f 66 69  trol)(sqlite3_fi
7c60: 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76 6f 69  le*, int op, voi
7c70: 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e 74 20  d *pArg);.  int 
7c80: 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29 28 73  (*xSectorSize)(s
7c90: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7ca0: 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65 43 68   int (*xDeviceCh
7cb0: 61 72 61 63 74 65 72 69 73 74 69 63 73 29 28 73  aracteristics)(s
7cc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7cd0: 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f 76   /* Methods abov
7ce0: 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72 20  e are valid for 
7cf0: 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20 20 69  version 1 */.  i
7d00: 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28 73 71  nt (*xShmMap)(sq
7d10: 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74  lite3_file*, int
7d20: 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a 2c 20   iPg, int pgsz, 
7d30: 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61 74 69  int, void volati
7d40: 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78  le**);.  int (*x
7d50: 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  ShmLock)(sqlite3
7d60: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66 66 73  _file*, int offs
7d70: 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74 20 66  et, int n, int f
7d80: 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20 28 2a  lags);.  void (*
7d90: 78 53 68 6d 42 61 72 72 69 65 72 29 28 73 71 6c  xShmBarrier)(sql
7da0: 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20 20 69  ite3_file*);.  i
7db0: 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70 29 28  nt (*xShmUnmap)(
7dc0: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7dd0: 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29 3b 0a  nt deleteFlag);.
7de0: 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62 6f    /* Methods abo
7df0: 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f 72  ve are valid for
7e00: 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a 20 20   version 2 */.  
7e10: 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 6d 65  /* Additional me
7e20: 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61 64 64  thods may be add
7e30: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
7e40: 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  eases */.};../*.
7e50: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 74 61  ** CAPI3REF: Sta
7e60: 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e 74 72  ndard File Contr
7e70: 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a 2a 2a  ol Opcodes.**.**
7e80: 20 54 68 65 73 65 20 69 6e 74 65 67 65 72 20 63   These integer c
7e90: 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f 70 63  onstants are opc
7ea0: 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78 46 69  odes for the xFi
7eb0: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7ec0: 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
7ed0: 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20  te3_io_methods] 
7ee0: 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72 20 74  object and for t
7ef0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
7f00: 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a 20 69  _control()].** i
7f10: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20  nterface..**.** 
7f20: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
7f30: 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f 70 63  L_LOCKSTATE] opc
7f40: 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f 72 20  ode is used for 
7f50: 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68 69 73  debugging.  This
7f60: 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75 73 65  .** opcode cause
7f70: 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72  s the xFileContr
7f80: 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77 72 69  ol method to wri
7f90: 74 65 20 74 68 65 20 63 75 72 72 65 6e 74 20 73  te the current s
7fa0: 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65 20 6c  tate of.** the l
7fb0: 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53 51 4c  ock (one of [SQL
7fc0: 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 20  ITE_LOCK_NONE], 
7fd0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53 48 41  [SQLITE_LOCK_SHA
7fe0: 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45  RED],.** [SQLITE
7ff0: 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c  _LOCK_RESERVED],
8000: 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50 45   [SQLITE_LOCK_PE
8010: 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51 4c 49  NDING], or [SQLI
8020: 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56  TE_LOCK_EXCLUSIV
8030: 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e 20 69  E]).** into an i
8040: 6e 74 65 67 65 72 20 74 68 61 74 20 74 68 65 20  nteger that the 
8050: 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20 70 6f  pArg argument po
8060: 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20 63 61  ints to. This ca
8070: 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 75  pability.** is u
8080: 73 65 64 20 64 75 72 69 6e 67 20 74 65 73 74 69  sed during testi
8090: 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65 65 64  ng and only need
80a0: 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  s to be supporte
80b0: 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f 54 45  d when SQLITE_TE
80c0: 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e 65 64  ST.** is defined
80d0: 2e 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  ..** <ul>.** <li
80e0: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
80f0: 53 49 5a 45 5f 48 49 4e 54 5d 5d 0a 2a 2a 20 54  SIZE_HINT]].** T
8100: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
8110: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
8120: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
8130: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
8140: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
8150: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
8160: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
8170: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
8180: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
8190: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
81a0: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
81b0: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
81c0: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
81d0: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
81e0: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
81f0: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
8200: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
8210: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
8220: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
8230: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
8240: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
8250: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
8260: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8270: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8280: 72 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  r..**.** <li>[[S
8290: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e  QLITE_FCNTL_CHUN
82a0: 4b 5f 53 49 5a 45 5d 5d 0a 2a 2a 20 54 68 65 20  K_SIZE]].** The 
82b0: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48  [SQLITE_FCNTL_CH
82c0: 55 4e 4b 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65  UNK_SIZE] opcode
82d0: 20 69 73 20 75 73 65 64 20 74 6f 20 72 65 71 75   is used to requ
82e0: 65 73 74 20 74 68 61 74 20 74 68 65 20 56 46 53  est that the VFS
82f0: 0a 2a 2a 20 65 78 74 65 6e 64 73 20 61 6e 64 20  .** extends and 
8300: 74 72 75 6e 63 61 74 65 73 20 74 68 65 20 64 61  truncates the da
8310: 74 61 62 61 73 65 20 66 69 6c 65 20 69 6e 20 63  tabase file in c
8320: 68 75 6e 6b 73 20 6f 66 20 61 20 73 69 7a 65 20  hunks of a size 
8330: 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79 20  specified.** by 
8340: 74 68 65 20 75 73 65 72 2e 20 54 68 65 20 66 6f  the user. The fo
8350: 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f  urth argument to
8360: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63   [sqlite3_file_c
8370: 6f 6e 74 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64  ontrol()] should
8380: 20 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e   .** point to an
8390: 20 69 6e 74 65 67 65 72 20 28 74 79 70 65 20 69   integer (type i
83a0: 6e 74 29 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74  nt) containing t
83b0: 68 65 20 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a  he new chunk-siz
83c0: 65 20 74 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20  e to use.** for 
83d0: 74 68 65 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61  the nominated da
83e0: 74 61 62 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69  tabase. Allocati
83f0: 6e 67 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ng database file
8400: 20 73 70 61 63 65 20 69 6e 20 6c 61 72 67 65 0a   space in large.
8410: 2a 2a 20 63 68 75 6e 6b 73 20 28 73 61 79 20 31  ** chunks (say 1
8420: 4d 42 20 61 74 20 61 20 74 69 6d 65 29 2c 20 6d  MB at a time), m
8430: 61 79 20 72 65 64 75 63 65 20 66 69 6c 65 2d 73  ay reduce file-s
8440: 79 73 74 65 6d 20 66 72 61 67 6d 65 6e 74 61 74  ystem fragmentat
8450: 69 6f 6e 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f  ion and.** impro
8460: 76 65 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f  ve performance o
8470: 6e 20 73 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a  n some systems..
8480: 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49  **.** <li>[[SQLI
8490: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
84a0: 49 4e 54 45 52 5d 5d 0a 2a 2a 20 54 68 65 20 5b  INTER]].** The [
84b0: 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 46 49 4c  SQLITE_FCNTL_FIL
84c0: 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70 63 6f 64  E_POINTER] opcod
84d0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 6f 62 74  e is used to obt
84e0: 61 69 6e 20 61 20 70 6f 69 6e 74 65 72 0a 2a 2a  ain a pointer.**
84f0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
8500: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20 61 73  _file] object as
8510: 73 6f 63 69 61 74 65 64 20 77 69 74 68 20 61 20  sociated with a 
8520: 70 61 72 74 69 63 75 6c 61 72 20 64 61 74 61 62  particular datab
8530: 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  ase.** connectio
8540: 6e 2e 20 20 53 65 65 20 74 68 65 20 5b 73 71 6c  n.  See the [sql
8550: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
8560: 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69  l()] documentati
8570: 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74 69  on for.** additi
8580: 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  onal information
8590: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
85a0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f  LITE_FCNTL_SYNC_
85b0: 4f 4d 49 54 54 45 44 5d 5d 0a 2a 2a 20 5e 28 54  OMITTED]].** ^(T
85c0: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
85d0: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f  _SYNC_OMITTED] o
85e0: 70 63 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74  pcode is generat
85f0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
8600: 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73  .** SQLite and s
8610: 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73  ent to all VFSes
8620: 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63   in place of a c
8630: 61 6c 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63  all to the xSync
8640: 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20   method.** when 
8650: 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
8660: 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41  nection has [PRA
8670: 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d  GMA synchronous]
8680: 20 73 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a   set to OFF.)^.*
8690: 2a 20 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a  * Some specializ
86a0: 65 64 20 56 46 53 65 73 20 6e 65 65 64 20 74 68  ed VFSes need th
86b0: 69 73 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64  is signal in ord
86c0: 65 72 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f  er to operate co
86d0: 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20  rrectly.** when 
86e0: 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e  [PRAGMA synchron
86f0: 6f 75 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e  ous | PRAGMA syn
8700: 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73  chronous=OFF] is
8710: 20 73 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a   set, but most .
8720: 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20  ** VFSes do not 
8730: 6e 65 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c  need this signal
8740: 20 61 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65   and should sile
8750: 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73  ntly ignore this
8760: 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c   opcode..** Appl
8770: 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
8780: 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65  not call [sqlite
8790: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
87a0: 5d 20 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f  ] with this.** o
87b0: 70 63 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73  pcode as doing s
87c0: 6f 20 6d 61 79 20 64 69 73 72 75 70 74 20 74 68  o may disrupt th
87d0: 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74  e operation of t
87e0: 68 65 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56  he specialized V
87f0: 46 53 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20  FSes.** that do 
8800: 72 65 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a  require it.  .**
8810: 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c 49 54 45  .** <li>[[SQLITE
8820: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
8830: 52 45 54 52 59 5d 5d 0a 2a 2a 20 5e 54 68 65 20  RETRY]].** ^The 
8840: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 57 49  [SQLITE_FCNTL_WI
8850: 4e 33 32 5f 41 56 5f 52 45 54 52 59 5d 20 6f 70  N32_AV_RETRY] op
8860: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8870: 63 6f 6e 66 69 67 75 72 65 20 61 75 74 6f 6d 61  configure automa
8880: 74 69 63 0a 2a 2a 20 72 65 74 72 79 20 63 6f 75  tic.** retry cou
8890: 6e 74 73 20 61 6e 64 20 69 6e 74 65 72 76 61 6c  nts and interval
88a0: 73 20 66 6f 72 20 63 65 72 74 61 69 6e 20 64 69  s for certain di
88b0: 73 6b 20 49 2f 4f 20 6f 70 65 72 61 74 69 6f 6e  sk I/O operation
88c0: 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 77 69 6e  s for the.** win
88d0: 64 6f 77 73 20 5b 56 46 53 5d 20 69 6e 20 6f 72  dows [VFS] in or
88e0: 64 65 72 20 74 6f 20 70 72 6f 76 69 64 65 20 72  der to provide r
88f0: 6f 62 75 73 74 6e 65 73 73 20 69 6e 20 74 68 65  obustness in the
8900: 20 70 72 65 73 65 6e 63 65 20 6f 66 0a 2a 2a 20   presence of.** 
8910: 61 6e 74 69 2d 76 69 72 75 73 20 70 72 6f 67 72  anti-virus progr
8920: 61 6d 73 2e 20 20 42 79 20 64 65 66 61 75 6c 74  ams.  By default
8930: 2c 20 74 68 65 20 77 69 6e 64 6f 77 73 20 56 46  , the windows VF
8940: 53 20 77 69 6c 6c 20 72 65 74 72 79 20 66 69 6c  S will retry fil
8950: 65 20 72 65 61 64 2c 0a 2a 2a 20 66 69 6c 65 20  e read,.** file 
8960: 77 72 69 74 65 2c 20 61 6e 64 20 66 69 6c 65 20  write, and file 
8970: 64 65 6c 65 74 65 20 6f 70 65 72 61 74 69 6f 6e  delete operation
8980: 73 20 75 70 20 74 6f 20 31 30 20 74 69 6d 65 73  s up to 10 times
8990: 2c 20 77 69 74 68 20 61 20 64 65 6c 61 79 0a 2a  , with a delay.*
89a0: 2a 20 6f 66 20 32 35 20 6d 69 6c 6c 69 73 65 63  * of 25 millisec
89b0: 6f 6e 64 73 20 62 65 66 6f 72 65 20 74 68 65 20  onds before the 
89c0: 66 69 72 73 74 20 72 65 74 72 79 20 61 6e 64 20  first retry and 
89d0: 77 69 74 68 20 74 68 65 20 64 65 6c 61 79 20 69  with the delay i
89e0: 6e 63 72 65 61 73 69 6e 67 0a 2a 2a 20 62 79 20  ncreasing.** by 
89f0: 61 6e 20 61 64 64 69 74 69 6f 6e 61 6c 20 32 35  an additional 25
8a00: 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 77 69   milliseconds wi
8a10: 74 68 20 65 61 63 68 20 73 75 62 73 65 71 75 65  th each subseque
8a20: 6e 74 20 72 65 74 72 79 2e 20 20 54 68 69 73 0a  nt retry.  This.
8a30: 2a 2a 20 6f 70 63 6f 64 65 20 61 6c 6c 6f 77 73  ** opcode allows
8a40: 20 74 68 65 73 65 20 74 77 6f 20 76 61 6c 75 65   these two value
8a50: 73 20 28 31 30 20 72 65 74 72 69 65 73 20 61 6e  s (10 retries an
8a60: 64 20 32 35 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  d 25 millisecond
8a70: 73 20 6f 66 20 64 65 6c 61 79 29 0a 2a 2a 20 74  s of delay).** t
8a80: 6f 20 62 65 20 61 64 6a 75 73 74 65 64 2e 20 20  o be adjusted.  
8a90: 54 68 65 20 76 61 6c 75 65 73 20 61 72 65 20 63  The values are c
8aa0: 68 61 6e 67 65 64 20 66 6f 72 20 61 6c 6c 20 64  hanged for all d
8ab0: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
8ac0: 6f 6e 73 0a 2a 2a 20 77 69 74 68 69 6e 20 74 68  ons.** within th
8ad0: 65 20 73 61 6d 65 20 70 72 6f 63 65 73 73 2e 20  e same process. 
8ae0: 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   The argument is
8af0: 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
8b00: 20 61 72 72 61 79 20 6f 66 20 74 77 6f 0a 2a 2a   array of two.**
8b10: 20 69 6e 74 65 67 65 72 73 20 77 68 65 72 65 20   integers where 
8b20: 74 68 65 20 66 69 72 73 74 20 69 6e 74 65 67 65  the first intege
8b30: 72 20 69 20 74 68 65 20 6e 65 77 20 72 65 74 72  r i the new retr
8b40: 79 20 63 6f 75 6e 74 20 61 6e 64 20 74 68 65 20  y count and the 
8b50: 73 65 63 6f 6e 64 0a 2a 2a 20 69 6e 74 65 67 65  second.** intege
8b60: 72 20 69 73 20 74 68 65 20 64 65 6c 61 79 2e 20  r is the delay. 
8b70: 20 49 66 20 65 69 74 68 65 72 20 69 6e 74 65 67   If either integ
8b80: 65 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20  er is negative, 
8b90: 74 68 65 6e 20 74 68 65 20 73 65 74 74 69 6e 67  then the setting
8ba0: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
8bb0: 65 64 20 62 75 74 20 69 6e 73 74 65 61 64 20 74  ed but instead t
8bc0: 68 65 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f  he prior value o
8bd0: 66 20 74 68 61 74 20 73 65 74 74 69 6e 67 20 69  f that setting i
8be0: 73 20 77 72 69 74 74 65 6e 0a 2a 2a 20 69 6e 74  s written.** int
8bf0: 6f 20 74 68 65 20 61 72 72 61 79 20 65 6e 74 72  o the array entr
8c00: 79 2c 20 61 6c 6c 6f 77 69 6e 67 20 74 68 65 20  y, allowing the 
8c10: 63 75 72 72 65 6e 74 20 72 65 74 72 79 20 73 65  current retry se
8c20: 74 74 69 6e 67 73 20 74 6f 20 62 65 0a 2a 2a 20  ttings to be.** 
8c30: 69 6e 74 65 72 72 6f 67 61 74 65 64 2e 20 20 54  interrogated.  T
8c40: 68 65 20 7a 44 62 4e 61 6d 65 20 70 61 72 61 6d  he zDbName param
8c50: 65 74 65 72 20 69 73 20 69 67 6e 6f 72 65 64 2e  eter is ignored.
8c60: 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51 4c  .**.** <li>[[SQL
8c70: 49 54 45 5f 46 43 4e 54 4c 5f 50 45 52 53 49 53  ITE_FCNTL_PERSIS
8c80: 54 5f 57 41 4c 5d 5d 0a 2a 2a 20 5e 54 68 65 20  T_WAL]].** ^The 
8c90: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 45  [SQLITE_FCNTL_PE
8ca0: 52 53 49 53 54 5f 57 41 4c 5d 20 6f 70 63 6f 64  RSIST_WAL] opcod
8cb0: 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65 74  e is used to set
8cc0: 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a 2a   or query the.**
8cd0: 20 70 65 72 73 69 73 74 65 6e 74 20 5b 57 41 4c   persistent [WAL
8ce0: 20 7c 20 57 72 69 74 65 20 41 68 65 61 64 20 4c   | Write Ahead L
8cf0: 6f 67 5d 20 73 65 74 74 69 6e 67 2e 20 20 42 79  og] setting.  By
8d00: 20 64 65 66 61 75 6c 74 2c 20 74 68 65 20 61 75   default, the au
8d10: 78 69 6c 69 61 72 79 0a 2a 2a 20 77 72 69 74 65  xiliary.** write
8d20: 20 61 68 65 61 64 20 6c 6f 67 20 61 6e 64 20 73   ahead log and s
8d30: 68 61 72 65 64 20 6d 65 6d 6f 72 79 20 66 69 6c  hared memory fil
8d40: 65 73 20 75 73 65 64 20 66 6f 72 20 74 72 61 6e  es used for tran
8d50: 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f 6c 0a  saction control.
8d60: 2a 2a 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ** are automatic
8d70: 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 77 68 65  ally deleted whe
8d80: 6e 20 74 68 65 20 6c 61 74 65 73 74 20 63 6f 6e  n the latest con
8d90: 6e 65 63 74 69 6f 6e 20 74 6f 20 74 68 65 20 64  nection to the d
8da0: 61 74 61 62 61 73 65 0a 2a 2a 20 63 6c 6f 73 65  atabase.** close
8db0: 73 2e 20 20 53 65 74 74 69 6e 67 20 70 65 72 73  s.  Setting pers
8dc0: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8dd0: 63 61 75 73 65 73 20 74 68 6f 73 65 20 66 69 6c  causes those fil
8de0: 65 73 20 74 6f 20 70 65 72 73 69 73 74 20 61 66  es to persist af
8df0: 74 65 72 0a 2a 2a 20 63 6c 6f 73 65 2e 20 20 50  ter.** close.  P
8e00: 65 72 73 69 73 74 69 6e 67 20 74 68 65 20 66 69  ersisting the fi
8e10: 6c 65 73 20 69 73 20 75 73 65 66 75 6c 20 77 68  les is useful wh
8e20: 65 6e 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  en other process
8e30: 65 73 20 74 68 61 74 20 64 6f 20 6e 6f 74 0a 2a  es that do not.*
8e40: 2a 20 68 61 76 65 20 77 72 69 74 65 20 70 65 72  * have write per
8e50: 6d 69 73 73 69 6f 6e 20 6f 6e 20 74 68 65 20 64  mission on the d
8e60: 69 72 65 63 74 6f 72 79 20 63 6f 6e 74 61 69 6e  irectory contain
8e70: 69 6e 67 20 74 68 65 20 64 61 74 61 62 61 73 65  ing the database
8e80: 20 66 69 6c 65 20 77 61 6e 74 0a 2a 2a 20 74 6f   file want.** to
8e90: 20 72 65 61 64 20 74 68 65 20 64 61 74 61 62 61   read the databa
8ea0: 73 65 20 66 69 6c 65 2c 20 61 73 20 74 68 65 20  se file, as the 
8eb0: 57 41 4c 20 61 6e 64 20 73 68 61 72 65 64 20 6d  WAL and shared m
8ec0: 65 6d 6f 72 79 20 66 69 6c 65 73 20 6d 75 73 74  emory files must
8ed0: 20 65 78 69 73 74 0a 2a 2a 20 69 6e 20 6f 72 64   exist.** in ord
8ee0: 65 72 20 66 6f 72 20 74 68 65 20 64 61 74 61 62  er for the datab
8ef0: 61 73 65 20 74 6f 20 62 65 20 72 65 61 64 61 62  ase to be readab
8f00: 6c 65 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  le.  The fourth 
8f10: 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
8f20: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f  [sqlite3_file_co
8f30: 6e 74 72 6f 6c 28 29 5d 20 66 6f 72 20 74 68 69  ntrol()] for thi
8f40: 73 20 6f 70 63 6f 64 65 20 73 68 6f 75 6c 64 20  s opcode should 
8f50: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
8f60: 61 6e 20 69 6e 74 65 67 65 72 2e 0a 2a 2a 20 54  an integer..** T
8f70: 68 61 74 20 69 6e 74 65 67 65 72 20 69 73 20 30  hat integer is 0
8f80: 20 74 6f 20 64 69 73 61 62 6c 65 20 70 65 72 73   to disable pers
8f90: 69 73 74 65 6e 74 20 57 41 4c 20 6d 6f 64 65 20  istent WAL mode 
8fa0: 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c 65 20 70  or 1 to enable p
8fb0: 65 72 73 69 73 74 65 6e 74 0a 2a 2a 20 57 41 4c  ersistent.** WAL
8fc0: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
8fd0: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
8fe0: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
8ff0: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9000: 72 72 65 6e 74 0a 2a 2a 20 57 41 4c 20 70 65 72  rrent.** WAL per
9010: 73 69 73 74 65 6e 63 65 20 73 65 74 74 69 6e 67  sistence setting
9020: 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53 51  ..**.** <li>[[SQ
9030: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 4f 57 45 52  LITE_FCNTL_POWER
9040: 53 41 46 45 5f 4f 56 45 52 57 52 49 54 45 5d 5d  SAFE_OVERWRITE]]
9050: 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45  .** ^The [SQLITE
9060: 5f 46 43 4e 54 4c 5f 50 4f 57 45 52 53 41 46 45  _FCNTL_POWERSAFE
9070: 5f 4f 56 45 52 57 52 49 54 45 5d 20 6f 70 63 6f  _OVERWRITE] opco
9080: 64 65 20 69 73 20 75 73 65 64 20 74 6f 20 73 65  de is used to se
9090: 74 20 6f 72 20 71 75 65 72 79 20 74 68 65 0a 2a  t or query the.*
90a0: 2a 20 70 65 72 73 69 73 74 65 6e 74 20 22 70 6f  * persistent "po
90b0: 77 65 72 73 61 66 65 2d 6f 76 65 72 77 72 69 74  wersafe-overwrit
90c0: 65 22 20 6f 72 20 22 50 53 4f 57 22 20 73 65 74  e" or "PSOW" set
90d0: 74 69 6e 67 2e 20 20 54 68 65 20 50 53 4f 57 20  ting.  The PSOW 
90e0: 73 65 74 74 69 6e 67 0a 2a 2a 20 64 65 74 65 72  setting.** deter
90f0: 6d 69 6e 65 73 20 74 68 65 20 5b 53 51 4c 49 54  mines the [SQLIT
9100: 45 5f 49 4f 43 41 50 5f 50 4f 57 45 52 53 41 46  E_IOCAP_POWERSAF
9110: 45 5f 4f 56 45 52 57 52 49 54 45 5d 20 62 69 74  E_OVERWRITE] bit
9120: 20 6f 66 20 74 68 65 0a 2a 2a 20 78 44 65 76 69   of the.** xDevi
9130: 63 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63  ceCharacteristic
9140: 73 20 6d 65 74 68 6f 64 73 2e 20 54 68 65 20 66  s methods. The f
9150: 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
9160: 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  to.** [sqlite3_f
9170: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 66  ile_control()] f
9180: 6f 72 20 74 68 69 73 20 6f 70 63 6f 64 65 20 73  or this opcode s
9190: 68 6f 75 6c 64 20 62 65 20 61 20 70 6f 69 6e 74  hould be a point
91a0: 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
91b0: 2e 0a 2a 2a 20 54 68 61 74 20 69 6e 74 65 67 65  ..** That intege
91c0: 72 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  r is 0 to disabl
91d0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 20 6d 6f  e zero-damage mo
91e0: 64 65 20 6f 72 20 31 20 74 6f 20 65 6e 61 62 6c  de or 1 to enabl
91f0: 65 20 7a 65 72 6f 2d 64 61 6d 61 67 65 0a 2a 2a  e zero-damage.**
9200: 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 69   mode.  If the i
9210: 6e 74 65 67 65 72 20 69 73 20 2d 31 2c 20 74 68  nteger is -1, th
9220: 65 6e 20 69 74 20 69 73 20 6f 76 65 72 77 72 69  en it is overwri
9230: 74 74 65 6e 20 77 69 74 68 20 74 68 65 20 63 75  tten with the cu
9240: 72 72 65 6e 74 0a 2a 2a 20 7a 65 72 6f 2d 64 61  rrent.** zero-da
9250: 6d 61 67 65 20 6d 6f 64 65 20 73 65 74 74 69 6e  mage mode settin
9260: 67 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e 5b 5b 53  g..**.** <li>[[S
9270: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56 45 52  QLITE_FCNTL_OVER
9280: 57 52 49 54 45 5d 5d 0a 2a 2a 20 5e 54 68 65 20  WRITE]].** ^The 
9290: 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4f 56  [SQLITE_FCNTL_OV
92a0: 45 52 57 52 49 54 45 5d 20 6f 70 63 6f 64 65 20  ERWRITE] opcode 
92b0: 69 73 20 69 6e 76 6f 6b 65 64 20 62 79 20 53 51  is invoked by SQ
92c0: 4c 69 74 65 20 61 66 74 65 72 20 6f 70 65 6e 69  Lite after openi
92d0: 6e 67 0a 2a 2a 20 61 20 77 72 69 74 65 20 74 72  ng.** a write tr
92e0: 61 6e 73 61 63 74 69 6f 6e 20 74 6f 20 69 6e 64  ansaction to ind
92f0: 69 63 61 74 65 20 74 68 61 74 2c 20 75 6e 6c 65  icate that, unle
9300: 73 73 20 69 74 20 69 73 20 72 6f 6c 6c 65 64 20  ss it is rolled 
9310: 62 61 63 6b 20 66 6f 72 20 73 6f 6d 65 0a 2a 2a  back for some.**
9320: 20 72 65 61 73 6f 6e 2c 20 74 68 65 20 65 6e 74   reason, the ent
9330: 69 72 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  ire database fil
9340: 65 20 77 69 6c 6c 20 62 65 20 6f 76 65 72 77 72  e will be overwr
9350: 69 74 74 65 6e 20 62 79 20 74 68 65 20 63 75 72  itten by the cur
9360: 72 65 6e 74 20 0a 2a 2a 20 74 72 61 6e 73 61 63  rent .** transac
9370: 74 69 6f 6e 2e 20 54 68 69 73 20 69 73 20 75 73  tion. This is us
9380: 65 64 20 62 79 20 56 41 43 55 55 4d 20 6f 70 65  ed by VACUUM ope
9390: 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 3c  rations..**.** <
93a0: 6c 69 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54  li>[[SQLITE_FCNT
93b0: 4c 5f 56 46 53 4e 41 4d 45 5d 5d 0a 2a 2a 20 5e  L_VFSNAME]].** ^
93c0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
93d0: 4c 5f 56 46 53 4e 41 4d 45 5d 20 6f 70 63 6f 64  L_VFSNAME] opcod
93e0: 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f  e can be used to
93f0: 20 6f 62 74 61 69 6e 20 74 68 65 20 6e 61 6d 65   obtain the name
9400: 73 20 6f 66 0a 2a 2a 20 61 6c 6c 20 5b 56 46 53  s of.** all [VFS
9410: 65 73 5d 20 69 6e 20 74 68 65 20 56 46 53 20 73  es] in the VFS s
9420: 74 61 63 6b 2e 20 20 54 68 65 20 6e 61 6d 65 73  tack.  The names
9430: 20 61 72 65 20 6f 66 20 61 6c 6c 20 56 46 53 20   are of all VFS 
9440: 73 68 69 6d 73 20 61 6e 64 20 74 68 65 0a 2a 2a  shims and the.**
9450: 20 66 69 6e 61 6c 20 62 6f 74 74 6f 6d 2d 6c 65   final bottom-le
9460: 76 65 6c 20 56 46 53 20 61 72 65 20 77 72 69 74  vel VFS are writ
9470: 74 65 6e 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  ten into memory 
9480: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a 2a  obtained from .*
9490: 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  * [sqlite3_mallo
94a0: 63 28 29 5d 20 61 6e 64 20 74 68 65 20 72 65 73  c()] and the res
94b0: 75 6c 74 20 69 73 20 73 74 6f 72 65 64 20 69 6e  ult is stored in
94c0: 20 74 68 65 20 63 68 61 72 2a 20 76 61 72 69 61   the char* varia
94d0: 62 6c 65 0a 2a 2a 20 74 68 61 74 20 74 68 65 20  ble.** that the 
94e0: 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72  fourth parameter
94f0: 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c   of [sqlite3_fil
9500: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 70 6f 69  e_control()] poi
9510: 6e 74 73 20 74 6f 2e 0a 2a 2a 20 54 68 65 20 63  nts to..** The c
9520: 61 6c 6c 65 72 20 69 73 20 72 65 73 70 6f 6e 73  aller is respons
9530: 69 62 6c 65 20 66 6f 72 20 66 72 65 65 69 6e 67  ible for freeing
9540: 20 74 68 65 20 6d 65 6d 6f 72 79 20 77 68 65 6e   the memory when
9550: 20 64 6f 6e 65 2e 20 20 41 73 20 77 69 74 68 0a   done.  As with.
9560: 2a 2a 20 61 6c 6c 20 66 69 6c 65 2d 63 6f 6e 74  ** all file-cont
9570: 72 6f 6c 20 61 63 74 69 6f 6e 73 2c 20 74 68 65  rol actions, the
9580: 72 65 20 69 73 20 6e 6f 20 67 75 61 72 61 6e 74  re is no guarant
9590: 65 65 20 74 68 61 74 20 74 68 69 73 20 77 69 6c  ee that this wil
95a0: 6c 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 64 6f  l actually.** do
95b0: 20 61 6e 79 74 68 69 6e 67 2e 20 20 43 61 6c 6c   anything.  Call
95c0: 65 72 73 20 73 68 6f 75 6c 64 20 69 6e 69 74 69  ers should initi
95d0: 61 6c 69 7a 65 20 74 68 65 20 63 68 61 72 2a 20  alize the char* 
95e0: 76 61 72 69 61 62 6c 65 20 74 6f 20 61 20 4e 55  variable to a NU
95f0: 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  LL.** pointer in
9600: 20 63 61 73 65 20 74 68 69 73 20 66 69 6c 65 2d   case this file-
9610: 63 6f 6e 74 72 6f 6c 20 69 73 20 6e 6f 74 20 69  control is not i
9620: 6d 70 6c 65 6d 65 6e 74 65 64 2e 20 20 54 68 69  mplemented.  Thi
9630: 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c 0a 2a  s file-control.*
9640: 2a 20 69 73 20 69 6e 74 65 6e 64 65 64 20 66 6f  * is intended fo
9650: 72 20 64 69 61 67 6e 6f 73 74 69 63 20 75 73 65  r diagnostic use
9660: 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 3c 6c 69   only..**.** <li
9670: 3e 5b 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  >[[SQLITE_FCNTL_
9680: 50 52 41 47 4d 41 5d 5d 0a 2a 2a 20 5e 57 68 65  PRAGMA]].** ^Whe
9690: 6e 65 76 65 72 20 61 20 5b 50 52 41 47 4d 41 5d  never a [PRAGMA]
96a0: 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 70 61   statement is pa
96b0: 72 73 65 64 2c 20 61 6e 20 5b 53 51 4c 49 54 45  rsed, an [SQLITE
96c0: 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d 20 0a  _FCNTL_PRAGMA] .
96d0: 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  ** file control 
96e0: 69 73 20 73 65 6e 74 20 74 6f 20 74 68 65 20 6f  is sent to the o
96f0: 70 65 6e 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  pen [sqlite3_fil
9700: 65 5d 20 6f 62 6a 65 63 74 20 63 6f 72 72 65 73  e] object corres
9710: 70 6f 6e 64 69 6e 67 0a 2a 2a 20 74 6f 20 74 68  ponding.** to th
9720: 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
9730: 74 6f 20 77 68 69 63 68 20 74 68 65 20 70 72 61  to which the pra
9740: 67 6d 61 20 73 74 61 74 65 6d 65 6e 74 20 72 65  gma statement re
9750: 66 65 72 73 2e 20 5e 54 68 65 20 61 72 67 75 6d  fers. ^The argum
9760: 65 6e 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 53  ent.** to the [S
9770: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47  QLITE_FCNTL_PRAG
9780: 4d 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  MA] file control
9790: 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66 0a   is an array of.
97a0: 2a 2a 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 73  ** pointers to s
97b0: 74 72 69 6e 67 73 20 28 63 68 61 72 2a 2a 29 20  trings (char**) 
97c0: 69 6e 20 77 68 69 63 68 20 74 68 65 20 73 65 63  in which the sec
97d0: 6f 6e 64 20 65 6c 65 6d 65 6e 74 20 6f 66 20 74  ond element of t
97e0: 68 65 20 61 72 72 61 79 0a 2a 2a 20 69 73 20 74  he array.** is t
97f0: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 70  he name of the p
9800: 72 61 67 6d 61 20 61 6e 64 20 74 68 65 20 74 68  ragma and the th
9810: 69 72 64 20 65 6c 65 6d 65 6e 74 20 69 73 20 74  ird element is t
9820: 68 65 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  he argument to t
9830: 68 65 0a 2a 2a 20 70 72 61 67 6d 61 20 6f 72 20  he.** pragma or 
9840: 4e 55 4c 4c 20 69 66 20 74 68 65 20 70 72 61 67  NULL if the prag
9850: 6d 61 20 68 61 73 20 6e 6f 20 61 72 67 75 6d 65  ma has no argume
9860: 6e 74 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65  nt.  ^The handle
9870: 72 20 66 6f 72 20 61 6e 0a 2a 2a 20 5b 53 51 4c  r for an.** [SQL
9880: 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41  ITE_FCNTL_PRAGMA
9890: 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 63  ] file control c
98a0: 61 6e 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 6d 61  an optionally ma
98b0: 6b 65 20 74 68 65 20 66 69 72 73 74 20 65 6c 65  ke the first ele
98c0: 6d 65 6e 74 0a 2a 2a 20 6f 66 20 74 68 65 20 63  ment.** of the c
98d0: 68 61 72 2a 2a 20 61 72 67 75 6d 65 6e 74 20 70  har** argument p
98e0: 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
98f0: 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
9900: 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
9910: 29 5d 0a 2a 2a 20 6f 72 20 74 68 65 20 65 71 75  )].** or the equ
9920: 69 76 61 6c 65 6e 74 20 61 6e 64 20 74 68 61 74  ivalent and that
9930: 20 73 74 72 69 6e 67 20 77 69 6c 6c 20 62 65 63   string will bec
9940: 6f 6d 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f  ome the result o
9950: 66 20 74 68 65 20 70 72 61 67 6d 61 20 6f 72 0a  f the pragma or.
9960: 2a 2a 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  ** the error mes
9970: 73 61 67 65 20 69 66 20 74 68 65 20 70 72 61 67  sage if the prag
9980: 6d 61 20 66 61 69 6c 73 2e 20 5e 49 66 20 74 68  ma fails. ^If th
9990: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 43 4e  e.** [SQLITE_FCN
99a0: 54 4c 5f 50 52 41 47 4d 41 5d 20 66 69 6c 65 20  TL_PRAGMA] file 
99b0: 63 6f 6e 74 72 6f 6c 20 72 65 74 75 72 6e 73 20  control returns 
99c0: 5b 53 51 4c 49 54 45 5f 4e 4f 54 46 4f 55 4e 44  [SQLITE_NOTFOUND
99d0: 5d 2c 20 74 68 65 6e 20 6e 6f 72 6d 61 6c 20 0a  ], then normal .
99e0: 2a 2a 20 5b 50 52 41 47 4d 41 5d 20 70 72 6f 63  ** [PRAGMA] proc
99f0: 65 73 73 69 6e 67 20 63 6f 6e 74 69 6e 75 65 73  essing continues
9a00: 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49  .  ^If the [SQLI
9a10: 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d 41 5d  TE_FCNTL_PRAGMA]
9a20: 0a 2a 2a 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c  .** file control
9a30: 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
9a40: 5f 4f 4b 5d 2c 20 74 68 65 6e 20 74 68 65 20 70  _OK], then the p
9a50: 61 72 73 65 72 20 61 73 73 75 6d 65 73 20 74 68  arser assumes th
9a60: 61 74 20 74 68 65 0a 2a 2a 20 56 46 53 20 68 61  at the.** VFS ha
9a70: 73 20 68 61 6e 64 6c 65 64 20 74 68 65 20 50 52  s handled the PR
9a80: 41 47 4d 41 20 69 74 73 65 6c 66 20 61 6e 64 20  AGMA itself and 
9a90: 74 68 65 20 70 61 72 73 65 72 20 67 65 6e 65 72  the parser gener
9aa0: 61 74 65 73 20 61 20 6e 6f 2d 6f 70 0a 2a 2a 20  ates a no-op.** 
9ab0: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
9ac0: 6e 74 2e 20 20 5e 49 66 20 74 68 65 20 5b 53 51  nt.  ^If the [SQ
9ad0: 4c 49 54 45 5f 46 43 4e 54 4c 5f 50 52 41 47 4d  LITE_FCNTL_PRAGM
9ae0: 41 5d 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20  A] file control 
9af0: 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20 72  returns.** any r
9b00: 65 73 75 6c 74 20 63 6f 64 65 20 6f 74 68 65 72  esult code other
9b10: 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b   than [SQLITE_OK
9b20: 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e 4f 54  ] or [SQLITE_NOT
9b30: 46 4f 55 4e 44 5d 2c 20 74 68 61 74 20 6d 65 61  FOUND], that mea
9b40: 6e 73 0a 2a 2a 20 74 68 61 74 20 74 68 65 20 56  ns.** that the V
9b50: 46 53 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 61  FS encountered a
9b60: 6e 20 65 72 72 6f 72 20 77 68 69 6c 65 20 68 61  n error while ha
9b70: 6e 64 6c 69 6e 67 20 74 68 65 20 5b 50 52 41 47  ndling the [PRAG
9b80: 4d 41 5d 20 61 6e 64 20 74 68 65 0a 2a 2a 20 63  MA] and the.** c
9b90: 6f 6d 70 69 6c 61 74 69 6f 6e 20 6f 66 20 74 68  ompilation of th
9ba0: 65 20 50 52 41 47 4d 41 20 66 61 69 6c 73 20 77  e PRAGMA fails w
9bb0: 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
9bc0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54  The [SQLITE_FCNT
9bd0: 4c 5f 50 52 41 47 4d 41 5d 0a 2a 2a 20 66 69 6c  L_PRAGMA].** fil
9be0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 63 63 75 72 73  e control occurs
9bf0: 20 61 74 20 74 68 65 20 62 65 67 69 6e 6e 69 6e   at the beginnin
9c00: 67 20 6f 66 20 70 72 61 67 6d 61 20 73 74 61 74  g of pragma stat
9c10: 65 6d 65 6e 74 20 61 6e 61 6c 79 73 69 73 20 61  ement analysis a
9c20: 6e 64 20 73 6f 0a 2a 2a 20 69 74 20 69 73 20 61  nd so.** it is a
9c30: 62 6c 65 20 74 6f 20 6f 76 65 72 72 69 64 65 20  ble to override 
9c40: 62 75 69 6c 74 2d 69 6e 20 5b 50 52 41 47 4d 41  built-in [PRAGMA
9c50: 5d 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a  ] statements..**
9c60: 20 3c 2f 75 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </ul>.*/.#defin
9c70: 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 4c  e SQLITE_FCNTL_L
9c80: 4f 43 4b 53 54 41 54 45 20 20 20 20 20 20 20 20  OCKSTATE        
9c90: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
9ca0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
9cb0: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20  PROXYFILE       
9cc0: 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
9cd0: 53 51 4c 49 54 45 5f 53 45 54 5f 4c 4f 43 4b 50  SQLITE_SET_LOCKP
9ce0: 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 20 20  ROXYFILE        
9cf0: 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
9d00: 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52 4e 4f  QLITE_LAST_ERRNO
9d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
9d20: 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
9d30: 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f  LITE_FCNTL_SIZE_
9d40: 48 49 4e 54 20 20 20 20 20 20 20 20 20 20 20 20  HINT            
9d50: 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53 51 4c     5.#define SQL
9d60: 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f  ITE_FCNTL_CHUNK_
9d70: 53 49 5a 45 20 20 20 20 20 20 20 20 20 20 20 20  SIZE            
9d80: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
9d90: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
9da0: 49 4e 54 45 52 20 20 20 20 20 20 20 20 20 20 20  INTER           
9db0: 20 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   7.#define SQLIT
9dc0: 45 5f 46 43 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49  E_FCNTL_SYNC_OMI
9dd0: 54 54 45 44 20 20 20 20 20 20 20 20 20 20 20 20  TTED            
9de0: 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  8.#define SQLITE
9df0: 5f 46 43 4e 54 4c 5f 57 49 4e 33 32 5f 41 56 5f  _FCNTL_WIN32_AV_
9e00: 52 45 54 52 59 20 20 20 20 20 20 20 20 20 20 39  RETRY          9
9e10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
9e20: 46 43 4e 54 4c 5f 50 45 52 53 49 53 54 5f 57 41  FCNTL_PERSIST_WA
9e30: 4c 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  L            10.
9e40: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
9e50: 43 4e 54 4c 5f 4f 56 45 52 57 52 49 54 45 20 20  CNTL_OVERWRITE  
9e60: 20 20 20 20 20 20 20 20 20 20 20 20 31 31 0a 23              11.#
9e70: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43  define SQLITE_FC
9e80: 4e 54 4c 5f 56 46 53 4e 41 4d 45 20 20 20 20 20  NTL_VFSNAME     
9e90: 20 20 20 20 20 20 20 20 20 20 20 31 32 0a 23 64             12.#d
9ea0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e  efine SQLITE_FCN
9eb0: 54 4c 5f 50 4f 57 45 52 53 41 46 45 5f 4f 56 45  TL_POWERSAFE_OVE
9ec0: 52 57 52 49 54 45 20 20 20 20 31 33 0a 23 64 65  RWRITE    13.#de
9ed0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54  fine SQLITE_FCNT
9ee0: 4c 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20  L_PRAGMA        
9ef0: 20 20 20 20 20 20 20 20 20 31 34 0a 0a 2f 2a 0a           14../*.
9f00: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74  ** CAPI3REF: Mut
9f10: 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20  ex Handle.**.** 
9f20: 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65  The mutex module
9f30: 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64   within SQLite d
9f40: 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f  efines [sqlite3_
9f50: 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a  mutex] to be an.
9f60: 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70 65  ** abstract type
9f70: 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a   for a mutex obj
9f80: 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65  ect.  The SQLite
9f90: 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b   core never look
9fa0: 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65  s.** at the inte
9fb0: 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
9fc0: 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74  ion of an [sqlit
9fd0: 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f  e3_mutex].  It o
9fe0: 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74  nly.** deals wit
9ff0: 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68  h pointers to th
a000: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
a010: 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20  ] object..**.** 
a020: 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65 61  Mutexes are crea
a030: 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  ted using [sqlit
a040: 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29  e3_mutex_alloc()
a050: 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ]..*/.typedef st
a060: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74  ruct sqlite3_mut
a070: 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ex sqlite3_mutex
a080: 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
a090: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
a0a0: 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20  Object.**.** An 
a0b0: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
a0c0: 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65  sqlite3_vfs obje
a0d0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
a0e0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
a0f0: 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63  .** the SQLite c
a100: 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65  ore and the unde
a110: 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67  rlying operating
a120: 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76   system.  The "v
a130: 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61  fs".** in the na
a140: 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74  me of the object
a150: 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72   stands for "vir
a160: 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d  tual file system
a170: 22 2e 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b  ".  See.** the [
a180: 56 46 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65  VFS | VFS docume
a190: 6e 74 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72  ntation] for fur
a1a0: 74 68 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  ther information
a1b0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75  ..**.** The valu
a1c0: 65 20 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f  e of the iVersio
a1d0: 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69  n field is initi
a1e0: 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62  ally 1 but may b
a1f0: 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66  e larger in.** f
a200: 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f  uture versions o
a210: 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74  f SQLite.  Addit
a220: 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79  ional fields may
a230: 20 62 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20   be appended to 
a240: 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77  this.** object w
a250: 68 65 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e  hen the iVersion
a260: 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61   value is increa
a270: 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20  sed.  Note that 
a280: 74 68 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a  the structure.**
a290: 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
a2a0: 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67  vfs object chang
a2b0: 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61  es in the transa
a2c0: 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a  ction between.**
a2d0: 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
a2e0: 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20  3.5.9 and 3.6.0 
a2f0: 61 6e 64 20 79 65 74 20 74 68 65 20 69 56 65 72  and yet the iVer
a300: 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e  sion field was n
a310: 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a  ot.** modified..
a320: 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69  **.** The szOsFi
a330: 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68 65 20  le field is the 
a340: 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63  size of the subc
a350: 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f  lassed [sqlite3_
a360: 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75  file].** structu
a370: 72 65 20 75 73 65 64 20 62 79 20 74 68 69 73 20  re used by this 
a380: 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65  VFS.  mxPathname
a390: 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20   is the maximum 
a3a0: 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70  length of.** a p
a3b0: 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20  athname in this 
a3c0: 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73  VFS..**.** Regis
a3d0: 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66  tered sqlite3_vf
a3e0: 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65  s objects are ke
a3f0: 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c  pt on a linked l
a400: 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a  ist formed by.**
a410: 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74   the pNext point
a420: 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65  er.  The [sqlite
a430: 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72 28 29  3_vfs_register()
a440: 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65  ].** and [sqlite
a450: 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72  3_vfs_unregister
a460: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d  ()] interfaces m
a470: 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a  anage this list.
a480: 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73  ** in a thread-s
a490: 61 66 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73  afe way.  The [s
a4a0: 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28  qlite3_vfs_find(
a4b0: 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  )] interface.** 
a4c0: 73 65 61 72 63 68 65 73 20 74 68 65 20 6c 69 73  searches the lis
a4d0: 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68 65 20  t.  Neither the 
a4e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65  application code
a4f0: 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20   nor the VFS.** 
a500: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73  implementation s
a510: 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e  hould use the pN
a520: 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ext pointer..**.
a530: 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66 69 65  ** The pNext fie
a540: 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66  ld is the only f
a550: 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69  ield in the sqli
a560: 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63  te3_vfs.** struc
a570: 74 75 72 65 20 74 68 61 74 20 53 51 4c 69 74 65  ture that SQLite
a580: 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66   will ever modif
a590: 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  y.  SQLite will 
a5a0: 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f  only access.** o
a5b0: 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69  r modify this fi
a5c0: 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e  eld while holdin
a5d0: 67 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 73  g a particular s
a5e0: 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20  tatic mutex..** 
a5f0: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  The application 
a600: 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64  should never mod
a610: 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74  ify anything wit
a620: 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hin the sqlite3_
a630: 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e  vfs.** object on
a640: 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61  ce the object ha
a650: 73 20 62 65 65 6e 20 72 65 67 69 73 74 65 72 65  s been registere
a660: 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61  d..**.** The zNa
a670: 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74  me field holds t
a680: 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56  he name of the V
a690: 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20  FS module.  The 
a6a0: 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20  name must.** be 
a6b0: 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c  unique across al
a6c0: 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a  l VFS modules..*
a6d0: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
a6e0: 66 73 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53  fs.xOpen]].** ^S
a6f0: 51 4c 69 74 65 20 67 75 61 72 61 6e 74 65 65 73  QLite guarantees
a700: 20 74 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e   that the zFilen
a710: 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ame parameter to
a720: 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74   xOpen.** is eit
a730: 68 65 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  her a NULL point
a740: 65 72 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74  er or string obt
a750: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46  ained.** from xF
a760: 75 6c 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69  ullPathname() wi
a770: 74 68 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73  th an optional s
a780: 75 66 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20  uffix added..** 
a790: 5e 49 66 20 61 20 73 75 66 66 69 78 20 69 73 20  ^If a suffix is 
a7a0: 61 64 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69  added to the zFi
a7b0: 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72  lename parameter
a7c0: 2c 20 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e  , it will.** con
a7d0: 73 69 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65  sist of a single
a7e0: 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 20 66   "-" character f
a7f0: 6f 6c 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f  ollowed by no mo
a800: 72 65 20 74 68 61 6e 0a 2a 2a 20 31 31 20 61 6c  re than.** 11 al
a810: 70 68 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f  phanumeric and/o
a820: 72 20 22 2d 22 20 63 68 61 72 61 63 74 65 72 73  r "-" characters
a830: 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72  ..** ^SQLite fur
a840: 74 68 65 72 20 67 75 61 72 61 6e 74 65 65 73 20  ther guarantees 
a850: 74 68 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69  that.** the stri
a860: 6e 67 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64  ng will be valid
a870: 20 61 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75   and unchanged u
a880: 6e 74 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73  ntil xClose() is
a890: 0a 2a 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61  .** called. Beca
a8a0: 75 73 65 20 6f 66 20 74 68 65 20 70 72 65 76 69  use of the previ
a8b0: 6f 75 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a  ous sentence,.**
a8c0: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
a8d0: 6c 65 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73  le] can safely s
a8e0: 74 6f 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74  tore a pointer t
a8f0: 6f 20 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d  o the.** filenam
a900: 65 20 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f  e if it needs to
a910: 20 72 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69   remember the fi
a920: 6c 65 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20  lename for some 
a930: 72 65 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68  reason..** If th
a940: 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61  e zFilename para
a950: 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69  meter to xOpen i
a960: 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
a970: 20 74 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d   then xOpen.** m
a980: 75 73 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f  ust invent its o
a990: 77 6e 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d  wn temporary nam
a9a0: 65 20 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20  e for the file. 
a9b0: 20 5e 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a   ^Whenever the .
a9c0: 2a 2a 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72  ** xFilename par
a9d0: 61 6d 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69  ameter is NULL i
a9e0: 74 20 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74  t will also be t
a9f0: 68 65 20 63 61 73 65 20 74 68 61 74 20 74 68 65  he case that the
aa00: 0a 2a 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65  .** flags parame
aa10: 74 65 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65  ter will include
aa20: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
aa30: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a  LETEONCLOSE]..**
aa40: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
aa50: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28  gument to xOpen(
aa60: 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62  ) includes all b
aa70: 69 74 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68  its set in.** th
aa80: 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74  e flags argument
aa90: 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   to [sqlite3_ope
aaa0: 6e 5f 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20  n_v2()].  Or if 
aab0: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
aac0: 0a 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  .** or [sqlite3_
aad0: 6f 70 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65  open16()] is use
aae0: 64 2c 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e  d, then flags in
aaf0: 63 6c 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a  cludes at least.
ab00: 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
ab10: 52 45 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51  READWRITE] | [SQ
ab20: 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45  LITE_OPEN_CREATE
ab30: 5d 2e 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28  ]. .** If xOpen(
ab40: 29 20 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72  ) opens a file r
ab50: 65 61 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74  ead-only then it
ab60: 20 73 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73   sets *pOutFlags
ab70: 20 74 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b   to.** include [
ab80: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44  SQLITE_OPEN_READ
ab90: 4f 4e 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69  ONLY].  Other bi
aba0: 74 73 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73  ts in *pOutFlags
abb0: 20 6d 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a   may be set..**.
abc0: 2a 2a 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c  ** ^(SQLite will
abd0: 20 61 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66   also add one of
abe0: 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66   the following f
abf0: 6c 61 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65  lags to the xOpe
ac00: 6e 28 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70  n().** call, dep
ac10: 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62  ending on the ob
ac20: 6a 65 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65  ject being opene
ac30: 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  d:.**.** <ul>.**
ac40: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
ac50: 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20  PEN_MAIN_DB].** 
ac60: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
ac70: 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d  EN_MAIN_JOURNAL]
ac80: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
ac90: 45 5f 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a  E_OPEN_TEMP_DB].
aca0: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
acb0: 5f 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e  _OPEN_TEMP_JOURN
acc0: 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51  AL].** <li>  [SQ
acd0: 4c 49 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49  LITE_OPEN_TRANSI
ace0: 45 4e 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20  ENT_DB].** <li> 
acf0: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55   [SQLITE_OPEN_SU
ad00: 42 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  BJOURNAL].** <li
ad10: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
ad20: 4d 41 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a  MASTER_JOURNAL].
ad30: 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45  ** <li>  [SQLITE
ad40: 5f 4f 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f  _OPEN_WAL].** </
ad50: 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ul>)^.**.** The 
ad60: 66 69 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65  file I/O impleme
ad70: 6e 74 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20  ntation can use 
ad80: 74 68 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20  the object type 
ad90: 66 6c 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e  flags to.** chan
ada0: 67 65 20 74 68 65 20 77 61 79 20 69 74 20 64 65  ge the way it de
adb0: 61 6c 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20  als with files. 
adc0: 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e   For example, an
add0: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
ade0: 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61  that does not ca
adf0: 72 65 20 61 62 6f 75 74 20 63 72 61 73 68 20 72  re about crash r
ae00: 65 63 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62  ecovery or rollb
ae10: 61 63 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a  ack might make.*
ae20: 2a 20 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20  * the open of a 
ae30: 6a 6f 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e  journal file a n
ae40: 6f 2d 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f  o-op.  Writes to
ae50: 20 74 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f   this journal wo
ae60: 75 6c 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e  uld.** also be n
ae70: 6f 2d 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61  o-ops, and any a
ae80: 74 74 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74  ttempt to read t
ae90: 68 65 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64  he journal would
aea0: 20 72 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54   return.** SQLIT
aeb0: 45 5f 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65  E_IOERR.  Or the
aec0: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
aed0: 6d 69 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20  might recognize 
aee0: 74 68 61 74 20 61 20 64 61 74 61 62 61 73 65 0a  that a database.
aef0: 2a 2a 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20  ** file will be 
af00: 64 6f 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e  doing page-align
af10: 65 64 20 73 65 63 74 6f 72 20 72 65 61 64 73 20  ed sector reads 
af20: 61 6e 64 20 77 72 69 74 65 73 20 69 6e 20 61 20  and writes in a 
af30: 72 61 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20  random.** order 
af40: 61 6e 64 20 73 65 74 20 75 70 20 69 74 73 20 49  and set up its I
af50: 2f 4f 20 73 75 62 73 79 73 74 65 6d 20 61 63 63  /O subsystem acc
af60: 6f 72 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20  ordingly..**.** 
af70: 53 51 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73  SQLite might als
af80: 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65  o add one of the
af90: 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73   following flags
afa0: 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65   to the xOpen me
afb0: 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e  thod:.**.** <ul>
afc0: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
afd0: 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c  _OPEN_DELETEONCL
afe0: 4f 53 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  OSE].** <li> [SQ
aff0: 4c 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53  LITE_OPEN_EXCLUS
b000: 49 56 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  IVE].** </ul>.**
b010: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
b020: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
b030: 53 45 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74  SE] flag means t
b040: 68 65 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62  he file should b
b050: 65 0a 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65  e.** deleted whe
b060: 6e 20 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20  n it is closed. 
b070: 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50   ^The [SQLITE_OP
b080: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
b090: 5d 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74  ].** will be set
b0a0: 20 66 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61   for TEMP databa
b0b0: 73 65 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f  ses and their jo
b0c0: 75 72 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e  urnals, transien
b0d0: 74 0a 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20  t.** databases, 
b0e0: 61 6e 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e  and subjournals.
b0f0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c  .**.** ^The [SQL
b100: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
b110: 56 45 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61  VE] flag is alwa
b120: 79 73 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75  ys used in conju
b130: 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74  nction.** with t
b140: 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
b150: 43 52 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68  CREATE] flag, wh
b160: 69 63 68 20 61 72 65 20 62 6f 74 68 20 64 69 72  ich are both dir
b170: 65 63 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f  ectly.** analogo
b180: 75 73 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c  us to the O_EXCL
b190: 20 61 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61   and O_CREAT fla
b1a0: 67 73 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20  gs of the POSIX 
b1b0: 6f 70 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20  open().** API.  
b1c0: 54 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  The SQLITE_OPEN_
b1d0: 45 58 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20  EXCLUSIVE flag, 
b1e0: 77 68 65 6e 20 70 61 69 72 65 64 20 77 69 74 68  when paired with
b1f0: 20 74 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f   the .** SQLITE_
b200: 4f 50 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20  OPEN_CREATE, is 
b210: 75 73 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65  used to indicate
b220: 20 74 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c   that file shoul
b230: 64 20 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63  d always.** be c
b240: 72 65 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74  reated, and that
b250: 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20   it is an error 
b260: 69 66 20 69 74 20 61 6c 72 65 61 64 79 20 65 78  if it already ex
b270: 69 73 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c  ists..** It is <
b280: 69 3e 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74  i>not</i> used t
b290: 6f 20 69 6e 64 69 63 61 74 65 20 74 68 65 20 66  o indicate the f
b2a0: 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70  ile should be op
b2b0: 65 6e 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63  ened .** for exc
b2c0: 6c 75 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a  lusive access..*
b2d0: 2a 0a 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73  *.** ^At least s
b2e0: 7a 4f 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66  zOsFile bytes of
b2f0: 20 6d 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f   memory are allo
b300: 63 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a  cated by SQLite.
b310: 2a 2a 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20  ** to hold the  
b320: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73  [sqlite3_file] s
b330: 74 72 75 63 74 75 72 65 20 70 61 73 73 65 64 20  tructure passed 
b340: 61 73 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20  as the third.** 
b350: 61 72 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65  argument to xOpe
b360: 6e 2e 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65  n.  The xOpen me
b370: 74 68 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61  thod does not ha
b380: 76 65 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74  ve to.** allocat
b390: 65 20 74 68 65 20 73 74 72 75 63 74 75 72 65 3b  e the structure;
b3a0: 20 69 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20   it should just 
b3b0: 66 69 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74  fill it in.  Not
b3c0: 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f  e that.** the xO
b3d0: 70 65 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20  pen method must 
b3e0: 73 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f  set the sqlite3_
b3f0: 66 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f  file.pMethods to
b400: 20 65 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c   either.** a val
b410: 69 64 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  id [sqlite3_io_m
b420: 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f  ethods] object o
b430: 72 20 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65  r to NULL.  xOpe
b440: 6e 20 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69  n must do.** thi
b450: 73 20 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70  s even if the op
b460: 65 6e 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74  en fails.  SQLit
b470: 65 20 65 78 70 65 63 74 73 20 74 68 61 74 20 74  e expects that t
b480: 68 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e  he sqlite3_file.
b490: 70 4d 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d  pMethods.** elem
b4a0: 65 6e 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69  ent will be vali
b4b0: 64 20 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65  d after xOpen re
b4c0: 74 75 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73  turns regardless
b4d0: 20 6f 66 20 74 68 65 20 73 75 63 63 65 73 73 0a   of the success.
b4e0: 2a 2a 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66  ** or failure of
b4f0: 20 74 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e   the xOpen call.
b500: 0a 2a 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33  .**.** [[sqlite3
b510: 5f 76 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a  _vfs.xAccess]].*
b520: 2a 20 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67  * ^The flags arg
b530: 75 6d 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73  ument to xAccess
b540: 28 29 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54  () may be [SQLIT
b550: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d  E_ACCESS_EXISTS]
b560: 0a 2a 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20  .** to test for 
b570: 74 68 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66  the existence of
b580: 20 61 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c   a file, or [SQL
b590: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
b5a0: 52 49 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74  RITE] to.** test
b5b0: 20 77 68 65 74 68 65 72 20 61 20 66 69 6c 65 20   whether a file 
b5c0: 69 73 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  is readable and 
b5d0: 77 72 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51  writable, or [SQ
b5e0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
b5f0: 5d 0a 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65  ].** to test whe
b600: 74 68 65 72 20 61 20 66 69 6c 65 20 69 73 20 61  ther a file is a
b610: 74 20 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65  t least readable
b620: 2e 20 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e  .   The file can
b630: 20 62 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f   be a.** directo
b640: 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74  ry..**.** ^SQLit
b650: 65 20 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c  e will always al
b660: 6c 6f 63 61 74 65 20 61 74 20 6c 65 61 73 74 20  locate at least 
b670: 6d 78 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74  mxPathname+1 byt
b680: 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75  es for the.** ou
b690: 74 70 75 74 20 62 75 66 66 65 72 20 78 46 75 6c  tput buffer xFul
b6a0: 6c 50 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20  lPathname.  The 
b6b0: 65 78 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68  exact size of th
b6c0: 65 20 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a  e output buffer.
b6d0: 2a 2a 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65  ** is also passe
b6e0: 64 20 61 73 20 61 20 70 61 72 61 6d 65 74 65 72  d as a parameter
b6f0: 20 74 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64   to both  method
b700: 73 2e 20 49 66 20 74 68 65 20 6f 75 74 70 75 74  s. If the output
b710: 20 62 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f   buffer.** is no
b720: 74 20 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20  t large enough, 
b730: 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e  [SQLITE_CANTOPEN
b740: 5d 20 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75  ] should be retu
b750: 72 6e 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73  rned. Since this
b760: 20 69 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61   is.** handled a
b770: 73 20 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20  s a fatal error 
b780: 62 79 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69  by SQLite, vfs i
b790: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73  mplementations s
b7a0: 68 6f 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a  hould endeavor.*
b7b0: 2a 20 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69  * to prevent thi
b7c0: 73 20 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50  s by setting mxP
b7d0: 61 74 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66  athname to a suf
b7e0: 66 69 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20  ficiently large 
b7f0: 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  value..**.** The
b800: 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20   xRandomness(), 
b810: 78 53 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65  xSleep(), xCurre
b820: 6e 74 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43  ntTime(), and xC
b830: 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28  urrentTimeInt64(
b840: 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  ).** interfaces 
b850: 61 72 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  are not strictly
b860: 20 61 20 70 61 72 74 20 6f 66 20 74 68 65 20 66   a part of the f
b870: 69 6c 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74  ilesystem, but t
b880: 68 65 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75  hey are.** inclu
b890: 64 65 64 20 69 6e 20 74 68 65 20 56 46 53 20 73  ded in the VFS s
b8a0: 74 72 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d  tructure for com
b8b0: 70 6c 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68  pleteness..** Th
b8c0: 65 20 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20  e xRandomness() 
b8d0: 66 75 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74  function attempt
b8e0: 73 20 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74  s to return nByt
b8f0: 65 73 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67  es bytes.** of g
b900: 6f 6f 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64  ood-quality rand
b910: 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74  omness into zOut
b920: 2e 20 20 54 68 65 20 72 65 74 75 72 6e 20 76 61  .  The return va
b930: 6c 75 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63  lue is.** the ac
b940: 74 75 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62  tual number of b
b950: 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
b960: 73 73 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20  ss obtained..** 
b970: 54 68 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74  The xSleep() met
b980: 68 6f 64 20 63 61 75 73 65 73 20 74 68 65 20 63  hod causes the c
b990: 61 6c 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f  alling thread to
b9a0: 20 73 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a   sleep for at.**
b9b0: 20 6c 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65   least the numbe
b9c0: 72 20 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64  r of microsecond
b9d0: 73 20 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78  s given.  ^The x
b9e0: 43 75 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a  CurrentTime().**
b9f0: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
ba00: 61 20 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d  a Julian Day Num
ba10: 62 65 72 20 66 6f 72 20 74 68 65 20 63 75 72 72  ber for the curr
ba20: 65 6e 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d  ent date and tim
ba30: 65 20 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69  e as.** a floati
ba40: 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a  ng point value..
ba50: 2a 2a 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74  ** ^The xCurrent
ba60: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
ba70: 6f 64 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61  od returns, as a
ba80: 6e 20 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a  n integer, the J
ba90: 75 6c 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d  ulian.** Day Num
baa0: 62 65 72 20 6d 75 6c 74 69 70 6c 69 65 64 20 62  ber multiplied b
bab0: 79 20 38 36 34 30 30 30 30 30 20 28 74 68 65 20  y 86400000 (the 
bac0: 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73  number of millis
bad0: 65 63 6f 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20  econds in .** a 
bae0: 32 34 2d 68 6f 75 72 20 64 61 79 29 2e 20 20 0a  24-hour day).  .
baf0: 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
bb00: 75 73 65 20 74 68 65 20 78 43 75 72 72 65 6e 74  use the xCurrent
bb10: 54 69 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68  TimeInt64() meth
bb20: 6f 64 20 74 6f 20 67 65 74 20 74 68 65 20 63 75  od to get the cu
bb30: 72 72 65 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e  rrent.** date an
bb40: 64 20 74 69 6d 65 20 69 66 20 74 68 61 74 20 6d  d time if that m
bb50: 65 74 68 6f 64 20 69 73 20 61 76 61 69 6c 61 62  ethod is availab
bb60: 6c 65 20 28 69 66 20 69 56 65 72 73 69 6f 6e 20  le (if iVersion 
bb70: 69 73 20 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61  is 2 or .** grea
bb80: 74 65 72 20 61 6e 64 20 74 68 65 20 66 75 6e 63  ter and the func
bb90: 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20  tion pointer is 
bba0: 6e 6f 74 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69  not NULL) and wi
bbb0: 6c 6c 20 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20  ll fall back.** 
bbc0: 74 6f 20 78 43 75 72 72 65 6e 74 54 69 6d 65 28  to xCurrentTime(
bbd0: 29 20 69 66 20 78 43 75 72 72 65 6e 74 54 69 6d  ) if xCurrentTim
bbe0: 65 49 6e 74 36 34 28 29 20 69 73 20 75 6e 61 76  eInt64() is unav
bbf0: 61 69 6c 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ailable..**.** ^
bc00: 54 68 65 20 78 53 65 74 53 79 73 74 65 6d 43 61  The xSetSystemCa
bc10: 6c 6c 28 29 2c 20 78 47 65 74 53 79 73 74 65 6d  ll(), xGetSystem
bc20: 43 61 6c 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73  Call(), and xNes
bc30: 74 53 79 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e  tSystemCall() in
bc40: 74 65 72 66 61 63 65 73 0a 2a 2a 20 61 72 65 20  terfaces.** are 
bc50: 6e 6f 74 20 75 73 65 64 20 62 79 20 74 68 65 20  not used by the 
bc60: 53 51 4c 69 74 65 20 63 6f 72 65 2e 20 20 54 68  SQLite core.  Th
bc70: 65 73 65 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74  ese optional int
bc80: 65 72 66 61 63 65 73 20 61 72 65 20 70 72 6f 76  erfaces are prov
bc90: 69 64 65 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20  ided.** by some 
bca0: 56 46 53 65 73 20 74 6f 20 66 61 63 69 6c 69 74  VFSes to facilit
bcb0: 61 74 65 20 74 65 73 74 69 6e 67 20 6f 66 20 74  ate testing of t
bcc0: 68 65 20 56 46 53 20 63 6f 64 65 2e 20 42 79 20  he VFS code. By 
bcd0: 6f 76 65 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73  overriding .** s
bce0: 79 73 74 65 6d 20 63 61 6c 6c 73 20 77 69 74 68  ystem calls with
bcf0: 20 66 75 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72   functions under
bd00: 20 69 74 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20   its control, a 
bd10: 74 65 73 74 20 70 72 6f 67 72 61 6d 20 63 61 6e  test program can
bd20: 0a 2a 2a 20 73 69 6d 75 6c 61 74 65 20 66 61 75  .** simulate fau
bd30: 6c 74 73 20 61 6e 64 20 65 72 72 6f 72 20 63 6f  lts and error co
bd40: 6e 64 69 74 69 6f 6e 73 20 74 68 61 74 20 77 6f  nditions that wo
bd50: 75 6c 64 20 6f 74 68 65 72 77 69 73 65 20 62 65  uld otherwise be
bd60: 20 64 69 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72   difficult.** or
bd70: 20 69 6d 70 6f 73 73 69 62 6c 65 20 74 6f 20 69   impossible to i
bd80: 6e 64 75 63 65 2e 20 20 54 68 65 20 73 65 74 20  nduce.  The set 
bd90: 6f 66 20 73 79 73 74 65 6d 20 63 61 6c 6c 73 20  of system calls 
bda0: 74 68 61 74 20 63 61 6e 20 62 65 20 6f 76 65 72  that can be over
bdb0: 72 69 64 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73  ridden.** varies
bdc0: 20 66 72 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f   from one VFS to
bdd0: 20 61 6e 6f 74 68 65 72 2c 20 61 6e 64 20 66 72   another, and fr
bde0: 6f 6d 20 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f  om one version o
bdf0: 66 20 74 68 65 20 73 61 6d 65 20 56 46 53 20 74  f the same VFS t
be00: 6f 20 74 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20  o the.** next.  
be10: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
be20: 74 20 75 73 65 20 74 68 65 73 65 20 69 6e 74 65  t use these inte
be30: 72 66 61 63 65 73 20 6d 75 73 74 20 62 65 20 70  rfaces must be p
be40: 72 65 70 61 72 65 64 20 66 6f 72 20 61 6e 79 0a  repared for any.
be50: 2a 2a 20 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65  ** or all of the
be60: 73 65 20 69 6e 74 65 72 66 61 63 65 73 20 74 6f  se interfaces to
be70: 20 62 65 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20   be NULL or for 
be80: 74 68 65 69 72 20 62 65 68 61 76 69 6f 72 20 74  their behavior t
be90: 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d  o change.** from
bea0: 20 6f 6e 65 20 72 65 6c 65 61 73 65 20 74 6f 20   one release to 
beb0: 74 68 65 20 6e 65 78 74 2e 20 20 41 70 70 6c 69  the next.  Appli
bec0: 63 61 74 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74  cations must not
bed0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 63 65   attempt to acce
bee0: 73 73 0a 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65  ss.** any of the
bef0: 73 65 20 6d 65 74 68 6f 64 73 20 69 66 20 74 68  se methods if th
bf00: 65 20 69 56 65 72 73 69 6f 6e 20 6f 66 20 74 68  e iVersion of th
bf10: 65 20 56 46 53 20 69 73 20 6c 65 73 73 20 74 68  e VFS is less th
bf20: 61 6e 20 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66  an 3..*/.typedef
bf30: 20 73 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f   struct sqlite3_
bf40: 76 66 73 20 73 71 6c 69 74 65 33 5f 76 66 73 3b  vfs sqlite3_vfs;
bf50: 0a 74 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a  .typedef void (*
bf60: 73 71 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f  sqlite3_syscall_
bf70: 70 74 72 29 28 76 6f 69 64 29 3b 0a 73 74 72 75  ptr)(void);.stru
bf80: 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73 20 7b  ct sqlite3_vfs {
bf90: 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b  .  int iVersion;
bfa0: 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53              /* S
bfb0: 74 72 75 63 74 75 72 65 20 76 65 72 73 69 6f 6e  tructure version
bfc0: 20 6e 75 6d 62 65 72 20 28 63 75 72 72 65 6e 74   number (current
bfd0: 6c 79 20 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73  ly 3) */.  int s
bfe0: 7a 4f 73 46 69 6c 65 3b 20 20 20 20 20 20 20 20  zOsFile;        
bff0: 20 20 20 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73      /* Size of s
c000: 75 62 63 6c 61 73 73 65 64 20 73 71 6c 69 74 65  ubclassed sqlite
c010: 33 5f 66 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20  3_file */.  int 
c020: 6d 78 50 61 74 68 6e 61 6d 65 3b 20 20 20 20 20  mxPathname;     
c030: 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
c040: 66 69 6c 65 20 70 61 74 68 6e 61 6d 65 20 6c 65  file pathname le
c050: 6e 67 74 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65  ngth */.  sqlite
c060: 33 5f 76 66 73 20 2a 70 4e 65 78 74 3b 20 20 20  3_vfs *pNext;   
c070: 20 20 20 2f 2a 20 4e 65 78 74 20 72 65 67 69 73     /* Next regis
c080: 74 65 72 65 64 20 56 46 53 20 2a 2f 0a 20 20 63  tered VFS */.  c
c090: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
c0a0: 3b 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20  ;       /* Name 
c0b0: 6f 66 20 74 68 69 73 20 76 69 72 74 75 61 6c 20  of this virtual 
c0c0: 66 69 6c 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20  file system */. 
c0d0: 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61 3b   void *pAppData;
c0e0: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 50 6f 69            /* Poi
c0f0: 6e 74 65 72 20 74 6f 20 61 70 70 6c 69 63 61 74  nter to applicat
c100: 69 6f 6e 2d 73 70 65 63 69 66 69 63 20 64 61 74  ion-specific dat
c110: 61 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70  a */.  int (*xOp
c120: 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  en)(sqlite3_vfs*
c130: 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e  , const char *zN
c140: 61 6d 65 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c  ame, sqlite3_fil
c150: 65 2a 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  e*,.            
c160: 20 20 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e     int flags, in
c170: 74 20 2a 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20  t *pOutFlags);. 
c180: 20 69 6e 74 20 28 2a 78 44 65 6c 65 74 65 29 28   int (*xDelete)(
c190: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1a0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c1b0: 20 69 6e 74 20 73 79 6e 63 44 69 72 29 3b 0a 20   int syncDir);. 
c1c0: 20 69 6e 74 20 28 2a 78 41 63 63 65 73 73 29 28   int (*xAccess)(
c1d0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f  sqlite3_vfs*, co
c1e0: 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
c1f0: 20 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20   int flags, int 
c200: 2a 70 52 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74  *pResOut);.  int
c210: 20 28 2a 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65   (*xFullPathname
c220: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20  )(sqlite3_vfs*, 
c230: 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
c240: 65 2c 20 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61  e, int nOut, cha
c250: 72 20 2a 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64  r *zOut);.  void
c260: 20 2a 28 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c   *(*xDlOpen)(sql
c270: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c280: 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65   char *zFilename
c290: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 45  );.  void (*xDlE
c2a0: 72 72 6f 72 29 28 73 71 6c 69 74 65 33 5f 76 66  rror)(sqlite3_vf
c2b0: 73 2a 2c 20 69 6e 74 20 6e 42 79 74 65 2c 20 63  s*, int nByte, c
c2c0: 68 61 72 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20  har *zErrMsg);. 
c2d0: 20 76 6f 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d   void (*(*xDlSym
c2e0: 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76  )(sqlite3_vfs*,v
c2f0: 6f 69 64 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72  oid*, const char
c300: 20 2a 7a 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64   *zSymbol))(void
c310: 29 3b 0a 20 20 76 6f 69 64 20 28 2a 78 44 6c 43  );.  void (*xDlC
c320: 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f 76 66  lose)(sqlite3_vf
c330: 73 2a 2c 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e  s*, void*);.  in
c340: 74 20 28 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29  t (*xRandomness)
c350: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69  (sqlite3_vfs*, i
c360: 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72 20 2a  nt nByte, char *
c370: 7a 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  zOut);.  int (*x
c380: 53 6c 65 65 70 29 28 73 71 6c 69 74 65 33 5f 76  Sleep)(sqlite3_v
c390: 66 73 2a 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65  fs*, int microse
c3a0: 63 6f 6e 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a  conds);.  int (*
c3b0: 78 43 75 72 72 65 6e 74 54 69 6d 65 29 28 73 71  xCurrentTime)(sq
c3c0: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62  lite3_vfs*, doub
c3d0: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47  le*);.  int (*xG
c3e0: 65 74 4c 61 73 74 45 72 72 6f 72 29 28 73 71 6c  etLastError)(sql
c3f0: 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20  ite3_vfs*, int, 
c400: 63 68 61 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20  char *);.  /*.  
c410: 2a 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  ** The methods a
c420: 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
c430: 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
c440: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20  ite_vfs object. 
c450: 20 2a 2a 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20   ** definition. 
c460: 20 54 68 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c   Those that foll
c470: 6f 77 20 61 72 65 20 61 64 64 65 64 20 69 6e 20  ow are added in 
c480: 76 65 72 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74  version 2 or lat
c490: 65 72 0a 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  er.  */.  int (*
c4a0: 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e 74 36  xCurrentTimeInt6
c4b0: 34 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  4)(sqlite3_vfs*,
c4c0: 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29   sqlite3_int64*)
c4d0: 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20  ;.  /*.  ** The 
c4e0: 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72  methods above ar
c4f0: 65 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20  e in versions 1 
c500: 61 6e 64 20 32 20 6f 66 20 74 68 65 20 73 71 6c  and 2 of the sql
c510: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
c520: 20 20 2a 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77    ** Those below
c530: 20 61 72 65 20 66 6f 72 20 76 65 72 73 69 6f 6e   are for version
c540: 20 33 20 61 6e 64 20 67 72 65 61 74 65 72 2e 0a   3 and greater..
c550: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65    */.  int (*xSe
c560: 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c  tSystemCall)(sql
c570: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
c580: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71   char *zName, sq
c590: 6c 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74  lite3_syscall_pt
c5a0: 72 29 3b 0a 20 20 73 71 6c 69 74 65 33 5f 73 79  r);.  sqlite3_sy
c5b0: 73 63 61 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74  scall_ptr (*xGet
c5c0: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
c5d0: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
c5e0: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
c5f0: 63 6f 6e 73 74 20 63 68 61 72 20 2a 28 2a 78 4e  const char *(*xN
c600: 65 78 74 53 79 73 74 65 6d 43 61 6c 6c 29 28 73  extSystemCall)(s
c610: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
c620: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b  st char *zName);
c630: 0a 20 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d  .  /*.  ** The m
c640: 65 74 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65  ethods above are
c650: 20 69 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 74   in versions 1 t
c660: 68 72 6f 75 67 68 20 33 20 6f 66 20 74 68 65 20  hrough 3 of the 
c670: 73 71 6c 69 74 65 5f 76 66 73 20 6f 62 6a 65 63  sqlite_vfs objec
c680: 74 2e 0a 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c  t..  ** New fiel
c690: 64 73 20 6d 61 79 20 62 65 20 61 70 70 65 6e 64  ds may be append
c6a0: 65 64 20 69 6e 20 66 69 67 75 72 65 20 76 65 72  ed in figure ver
c6b0: 73 69 6f 6e 73 2e 20 20 54 68 65 20 69 56 65 72  sions.  The iVer
c6c0: 73 69 6f 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20  sion.  ** value 
c6d0: 77 69 6c 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77  will increment w
c6e0: 68 65 6e 65 76 65 72 20 74 68 69 73 20 68 61 70  henever this hap
c6f0: 70 65 6e 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a  pens. .  */.};..
c700: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
c710: 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20 78 41  Flags for the xA
c720: 63 63 65 73 73 20 56 46 53 20 6d 65 74 68 6f 64  ccess VFS method
c730: 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74  .**.** These int
c740: 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20 63  eger constants c
c750: 61 6e 20 62 65 20 75 73 65 64 20 61 73 20 74 68  an be used as th
c760: 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
c770: 72 20 74 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63  r to.** the xAcc
c780: 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e  ess method of an
c790: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
c7a0: 62 6a 65 63 74 2e 20 20 54 68 65 79 20 64 65 74  bject.  They det
c7b0: 65 72 6d 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b  ermine.** what k
c7c0: 69 6e 64 20 6f 66 20 70 65 72 6d 69 73 73 69 6f  ind of permissio
c7d0: 6e 73 20 74 68 65 20 78 41 63 63 65 73 73 20 6d  ns the xAccess m
c7e0: 65 74 68 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67  ethod is looking
c7f0: 20 66 6f 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51   for..** With SQ
c800: 4c 49 54 45 5f 41 43 43 45 53 53 5f 45 58 49 53  LITE_ACCESS_EXIS
c810: 54 53 2c 20 74 68 65 20 78 41 63 63 65 73 73 20  TS, the xAccess 
c820: 6d 65 74 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79  method.** simply
c830: 20 63 68 65 63 6b 73 20 77 68 65 74 68 65 72 20   checks whether 
c840: 74 68 65 20 66 69 6c 65 20 65 78 69 73 74 73 2e  the file exists.
c850: 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54 45 5f  .** With SQLITE_
c860: 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54 45  ACCESS_READWRITE
c870: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c880: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
c890: 68 65 74 68 65 72 20 74 68 65 20 6e 61 6d 65 64  hether the named
c8a0: 20 64 69 72 65 63 74 6f 72 79 20 69 73 20 62 6f   directory is bo
c8b0: 74 68 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20  th readable and 
c8c0: 77 72 69 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20  writable.** (in 
c8d0: 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69 66 20  other words, if 
c8e0: 66 69 6c 65 73 20 63 61 6e 20 62 65 20 61 64 64  files can be add
c8f0: 65 64 2c 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64  ed, removed, and
c900: 20 72 65 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a   renamed within.
c910: 2a 2a 20 74 68 65 20 64 69 72 65 63 74 6f 72 79  ** the directory
c920: 29 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45  )..** The SQLITE
c930: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
c940: 45 20 63 6f 6e 73 74 61 6e 74 20 69 73 20 63 75  E constant is cu
c950: 72 72 65 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c  rrently used onl
c960: 79 20 62 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d  y by the.** [tem
c970: 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72  p_store_director
c980: 79 20 70 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67  y pragma], thoug
c990: 68 20 74 68 69 73 20 63 6f 75 6c 64 20 63 68 61  h this could cha
c9a0: 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
c9b0: 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
c9c0: 4c 69 74 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51  Lite..** With SQ
c9d0: 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44  LITE_ACCESS_READ
c9e0: 2c 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65  , the xAccess me
c9f0: 74 68 6f 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77  thod.** checks w
ca00: 68 65 74 68 65 72 20 74 68 65 20 66 69 6c 65 20  hether the file 
ca10: 69 73 20 72 65 61 64 61 62 6c 65 2e 20 20 54 68  is readable.  Th
ca20: 65 20 53 51 4c 49 54 45 5f 41 43 43 45 53 53 5f  e SQLITE_ACCESS_
ca30: 52 45 41 44 20 63 6f 6e 73 74 61 6e 74 20 69 73  READ constant is
ca40: 0a 2a 2a 20 63 75 72 72 65 6e 74 6c 79 20 75 6e  .** currently un
ca50: 75 73 65 64 2c 20 74 68 6f 75 67 68 20 69 74 20  used, though it 
ca60: 6d 69 67 68 74 20 62 65 20 75 73 65 64 20 69 6e  might be used in
ca70: 20 61 20 66 75 74 75 72 65 20 72 65 6c 65 61 73   a future releas
ca80: 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a  e of.** SQLite..
ca90: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
caa0: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 20  E_ACCESS_EXISTS 
cab0: 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51 4c     0.#define SQL
cac0: 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57  ITE_ACCESS_READW
cad0: 52 49 54 45 20 31 20 20 20 2f 2a 20 55 73 65 64  RITE 1   /* Used
cae0: 20 62 79 20 50 52 41 47 4d 41 20 74 65 6d 70 5f   by PRAGMA temp_
caf0: 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20  store_directory 
cb00: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
cb10: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 20 20 20  E_ACCESS_READ   
cb20: 20 20 20 32 20 20 20 2f 2a 20 55 6e 75 73 65 64     2   /* Unused
cb30: 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33   */../*.** CAPI3
cb40: 52 45 46 3a 20 46 6c 61 67 73 20 66 6f 72 20 74  REF: Flags for t
cb50: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20  he xShmLock VFS 
cb60: 6d 65 74 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65  method.**.** The
cb70: 73 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 73 74  se integer const
cb80: 61 6e 74 73 20 64 65 66 69 6e 65 20 74 68 65 20  ants define the 
cb90: 76 61 72 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20  various locking 
cba0: 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c  operations.** al
cbb0: 6c 6f 77 65 64 20 62 79 20 74 68 65 20 78 53 68  lowed by the xSh
cbc0: 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20  mLock method of 
cbd0: 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68  [sqlite3_io_meth
cbe0: 6f 64 73 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f  ods].  The.** fo
cbf0: 6c 6c 6f 77 69 6e 67 20 61 72 65 20 74 68 65 20  llowing are the 
cc00: 6f 6e 6c 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69  only legal combi
cc10: 6e 61 74 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73  nations of flags
cc20: 20 74 6f 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c   to the.** xShmL
cc30: 6f 63 6b 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a  ock method:.**.*
cc40: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
cc50: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
cc60: 7c 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  | SQLITE_SHM_SHA
cc70: 52 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  RED.** <li>  SQL
cc80: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
cc90: 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53  QLITE_SHM_EXCLUS
cca0: 49 56 45 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  IVE.** <li>  SQL
ccb0: 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c  ITE_SHM_UNLOCK |
ccc0: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52   SQLITE_SHM_SHAR
ccd0: 45 44 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49  ED.** <li>  SQLI
cce0: 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20  TE_SHM_UNLOCK | 
ccf0: 53 51 4c 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55  SQLITE_SHM_EXCLU
cd00: 53 49 56 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a  SIVE.** </ul>.**
cd10: 0a 2a 2a 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69  .** When unlocki
cd20: 6e 67 2c 20 74 68 65 20 73 61 6d 65 20 53 48 41  ng, the same SHA
cd30: 52 45 44 20 6f 72 20 45 58 43 4c 55 53 49 56 45  RED or EXCLUSIVE
cd40: 20 66 6c 61 67 20 6d 75 73 74 20 62 65 20 73 75   flag must be su
cd50: 70 70 6c 69 65 64 20 61 73 0a 2a 2a 20 77 61 73  pplied as.** was
cd60: 20 67 69 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f   given no the co
cd70: 72 72 65 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b  rresponding lock
cd80: 2e 20 20 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53  .  .**.** The xS
cd90: 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61  hmLock method ca
cda0: 6e 20 74 72 61 6e 73 69 74 69 6f 6e 20 62 65 74  n transition bet
cdb0: 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e  ween unlocked an
cdc0: 64 20 53 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62  d SHARED or.** b
cdd0: 65 74 77 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20  etween unlocked 
cde0: 61 6e 64 20 45 58 43 4c 55 53 49 56 45 2e 20 20  and EXCLUSIVE.  
cdf0: 49 74 20 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69  It cannot transi
ce00: 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 53 48 41  tion between SHA
ce10: 52 45 44 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55  RED.** and EXCLU
ce20: 53 49 56 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  SIVE..*/.#define
ce30: 20 53 51 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f   SQLITE_SHM_UNLO
ce40: 43 4b 20 20 20 20 20 20 20 31 0a 23 64 65 66 69  CK       1.#defi
ce50: 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f  ne SQLITE_SHM_LO
ce60: 43 4b 20 20 20 20 20 20 20 20 20 32 0a 23 64 65  CK         2.#de
ce70: 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f  fine SQLITE_SHM_
ce80: 53 48 41 52 45 44 20 20 20 20 20 20 20 34 0a 23  SHARED       4.#
ce90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 48  define SQLITE_SH
cea0: 4d 5f 45 58 43 4c 55 53 49 56 45 20 20 20 20 38  M_EXCLUSIVE    8
ceb0: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
cec0: 3a 20 4d 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f  : Maximum xShmLo
ced0: 63 6b 20 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54  ck index.**.** T
cee0: 68 65 20 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68  he xShmLock meth
cef0: 6f 64 20 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69  od on [sqlite3_i
cf00: 6f 5f 6d 65 74 68 6f 64 73 5d 20 6d 61 79 20 75  o_methods] may u
cf10: 73 65 20 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74  se values.** bet
cf20: 77 65 65 6e 20 30 20 61 6e 64 20 74 68 69 73 20  ween 0 and this 
cf30: 75 70 70 65 72 20 62 6f 75 6e 64 20 61 73 20 69  upper bound as i
cf40: 74 73 20 22 6f 66 66 73 65 74 22 20 61 72 67 75  ts "offset" argu
cf50: 6d 65 6e 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c  ment..** The SQL
cf60: 69 74 65 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65  ite core will ne
cf70: 76 65 72 20 61 74 74 65 6d 70 74 20 74 6f 20 61  ver attempt to a
cf80: 63 71 75 69 72 65 20 6f 72 20 72 65 6c 65 61 73  cquire or releas
cf90: 65 20 61 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73  e a.** lock outs
cfa0: 69 64 65 20 6f 66 20 74 68 69 73 20 72 61 6e 67  ide of this rang
cfb0: 65 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e.*/.#define SQL
cfc0: 49 54 45 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20  ITE_SHM_NLOCK   
cfd0: 20 20 20 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43       8.../*.** C
cfe0: 41 50 49 33 52 45 46 3a 20 49 6e 69 74 69 61 6c  API3REF: Initial
cff0: 69 7a 65 20 54 68 65 20 53 51 4c 69 74 65 20 4c  ize The SQLite L
d000: 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  ibrary.**.** ^Th
d010: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d020: 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69  lize() routine i
d030: 6e 69 74 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a  nitializes the.*
d040: 2a 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  * SQLite library
d050: 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  .  ^The sqlite3_
d060: 73 68 75 74 64 6f 77 6e 28 29 20 72 6f 75 74 69  shutdown() routi
d070: 6e 65 0a 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65  ne.** deallocate
d080: 73 20 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20  s any resources 
d090: 74 68 61 74 20 77 65 72 65 20 61 6c 6c 6f 63 61  that were alloca
d0a0: 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69  ted by sqlite3_i
d0b0: 6e 69 74 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20  nitialize()..** 
d0c0: 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61  These routines a
d0d0: 72 65 20 64 65 73 69 67 6e 65 64 20 74 6f 20 61  re designed to a
d0e0: 69 64 20 69 6e 20 70 72 6f 63 65 73 73 20 69 6e  id in process in
d0f0: 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64  itialization and
d100: 0a 2a 2a 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20  .** shutdown on 
d110: 65 6d 62 65 64 64 65 64 20 73 79 73 74 65 6d 73  embedded systems
d120: 2e 20 20 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61  .  Workstation a
d130: 70 70 6c 69 63 61 74 69 6f 6e 73 20 75 73 69 6e  pplications usin
d140: 67 0a 2a 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d  g.** SQLite norm
d150: 61 6c 6c 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64  ally do not need
d160: 20 74 6f 20 69 6e 76 6f 6b 65 20 65 69 74 68 65   to invoke eithe
d170: 72 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  r of these routi
d180: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c  nes..**.** A cal
d190: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69  l to sqlite3_ini
d1a0: 74 69 61 6c 69 7a 65 28 29 20 69 73 20 61 6e 20  tialize() is an 
d1b0: 22 65 66 66 65 63 74 69 76 65 22 20 63 61 6c 6c  "effective" call
d1c0: 20 69 66 20 69 74 20 69 73 0a 2a 2a 20 74 68 65   if it is.** the
d1d0: 20 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69   first time sqli
d1e0: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d1f0: 20 69 73 20 69 6e 76 6f 6b 65 64 20 64 75 72 69   is invoked duri
d200: 6e 67 20 74 68 65 20 6c 69 66 65 74 69 6d 65 20  ng the lifetime 
d210: 6f 66 0a 2a 2a 20 74 68 65 20 70 72 6f 63 65 73  of.** the proces
d220: 73 2c 20 6f 72 20 69 66 20 69 74 20 69 73 20 74  s, or if it is t
d230: 68 65 20 66 69 72 73 74 20 74 69 6d 65 20 73 71  he first time sq
d240: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
d250: 28 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a  () is invoked.**
d260: 20 66 6f 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c   following a cal
d270: 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 68 75  l to sqlite3_shu
d280: 74 64 6f 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79  tdown().  ^(Only
d290: 20 61 6e 20 65 66 66 65 63 74 69 76 65 20 63 61   an effective ca
d2a0: 6c 6c 0a 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33  ll.** of sqlite3
d2b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 6f  _initialize() do
d2c0: 65 73 20 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a  es any initializ
d2d0: 61 74 69 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65  ation.  All othe
d2e0: 72 20 63 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68  r calls.** are h
d2f0: 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29  armless no-ops.)
d300: 5e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ^.**.** A call t
d310: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d320: 77 6e 28 29 20 69 73 20 61 6e 20 22 65 66 66 65  wn() is an "effe
d330: 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66 20 69  ctive" call if i
d340: 74 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  t is the first.*
d350: 2a 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  * call to sqlite
d360: 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 73 69 6e  3_shutdown() sin
d370: 63 65 20 74 68 65 20 6c 61 73 74 20 73 71 6c 69  ce the last sqli
d380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d390: 2e 20 20 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20  .  ^(Only.** an 
d3a0: 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 20 74  effective call t
d3b0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
d3c0: 77 6e 28 29 20 64 6f 65 73 20 61 6e 79 20 64 65  wn() does any de
d3d0: 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a  initialization..
d3e0: 2a 2a 20 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c  ** All other val
d3f0: 69 64 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69  id calls to sqli
d400: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 20 61  te3_shutdown() a
d410: 72 65 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f  re harmless no-o
d420: 70 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ps.)^.**.** The 
d430: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
d440: 7a 65 28 29 20 69 6e 74 65 72 66 61 63 65 20 69  ze() interface i
d450: 73 20 74 68 72 65 61 64 73 61 66 65 2c 20 62 75  s threadsafe, bu
d460: 74 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  t sqlite3_shutdo
d470: 77 6e 28 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20  wn().** is not. 
d480: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75   The sqlite3_shu
d490: 74 64 6f 77 6e 28 29 20 69 6e 74 65 72 66 61 63  tdown() interfac
d4a0: 65 20 6d 75 73 74 20 6f 6e 6c 79 20 62 65 20 63  e must only be c
d4b0: 61 6c 6c 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20  alled from a.** 
d4c0: 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20 20  single thread.  
d4d0: 41 6c 6c 20 6f 70 65 6e 20 5b 64 61 74 61 62 61  All open [databa
d4e0: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
d4f0: 6d 75 73 74 20 62 65 20 63 6c 6f 73 65 64 20 61  must be closed a
d500: 6e 64 20 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20  nd all.** other 
d510: 53 51 4c 69 74 65 20 72 65 73 6f 75 72 63 65 73  SQLite resources
d520: 20 6d 75 73 74 20 62 65 20 64 65 61 6c 6c 6f 63   must be dealloc
d530: 61 74 65 64 20 70 72 69 6f 72 20 74 6f 20 69 6e  ated prior to in
d540: 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  voking.** sqlite
d550: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a  3_shutdown()..**
d560: 0a 2a 2a 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20  .** Among other 
d570: 74 68 69 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33  things, ^sqlite3
d580: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 77 69  _initialize() wi
d590: 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c  ll invoke.** sql
d5a0: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20  ite3_os_init(). 
d5b0: 20 53 69 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c   Similarly, ^sql
d5c0: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a  ite3_shutdown().
d5d0: 2a 2a 20 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73  ** will invoke s
d5e0: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e  qlite3_os_end().
d5f0: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
d600: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
d610: 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
d620: 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
d630: 73 75 63 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20  success..** ^If 
d640: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c  for some reason,
d650: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
d660: 69 7a 65 28 29 20 69 73 20 75 6e 61 62 6c 65 20  ize() is unable 
d670: 74 6f 20 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a  to initialize.**
d680: 20 74 68 65 20 6c 69 62 72 61 72 79 20 28 70 65   the library (pe
d690: 72 68 61 70 73 20 69 74 20 69 73 20 75 6e 61 62  rhaps it is unab
d6a0: 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61  le to allocate a
d6b0: 20 6e 65 65 64 65 64 20 72 65 73 6f 75 72 63 65   needed resource
d6c0: 20 73 75 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75   such.** as a mu
d6d0: 74 65 78 29 20 69 74 20 72 65 74 75 72 6e 73 20  tex) it returns 
d6e0: 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20  an [error code] 
d6f0: 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
d700: 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54  TE_OK]..**.** ^T
d710: 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  he sqlite3_initi
d720: 61 6c 69 7a 65 28 29 20 72 6f 75 74 69 6e 65 20  alize() routine 
d730: 69 73 20 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e  is called intern
d740: 61 6c 6c 79 20 62 79 20 6d 61 6e 79 20 6f 74 68  ally by many oth
d750: 65 72 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  er.** SQLite int
d760: 65 72 66 61 63 65 73 20 73 6f 20 74 68 61 74 20  erfaces so that 
d770: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75  an application u
d780: 73 75 61 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20  sually does not 
d790: 6e 65 65 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b  need to.** invok
d7a0: 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  e sqlite3_initia
d7b0: 6c 69 7a 65 28 29 20 64 69 72 65 63 74 6c 79 2e  lize() directly.
d7c0: 20 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b    For example, [
d7d0: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a  sqlite3_open()].
d7e0: 2a 2a 20 63 61 6c 6c 73 20 73 71 6c 69 74 65 33  ** calls sqlite3
d7f0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 73 6f  _initialize() so
d800: 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72   the SQLite libr
d810: 61 72 79 20 77 69 6c 6c 20 62 65 20 61 75 74 6f  ary will be auto
d820: 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69  matically.** ini
d830: 74 69 61 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73  tialized when [s
d840: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69  qlite3_open()] i
d850: 73 20 63 61 6c 6c 65 64 20 69 66 20 69 74 20 68  s called if it h
d860: 61 73 20 6e 6f 74 20 62 65 20 69 6e 69 74 69 61  as not be initia
d870: 6c 69 7a 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79  lized.** already
d880: 2e 20 20 5e 48 6f 77 65 76 65 72 2c 20 69 66 20  .  ^However, if 
d890: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
d8a0: 65 64 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ed with the [SQL
d8b0: 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49  ITE_OMIT_AUTOINI
d8c0: 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
d8d0: 6d 65 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  me option, then 
d8e0: 74 68 65 20 61 75 74 6f 6d 61 74 69 63 20 63 61  the automatic ca
d8f0: 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 69  lls to sqlite3_i
d900: 6e 69 74 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61  nitialize().** a
d910: 72 65 20 6f 6d 69 74 74 65 64 20 61 6e 64 20 74  re omitted and t
d920: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
d930: 75 73 74 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  ust call sqlite3
d940: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 64 69  _initialize() di
d950: 72 65 63 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20  rectly.** prior 
d960: 74 6f 20 75 73 69 6e 67 20 61 6e 79 20 6f 74 68  to using any oth
d970: 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  er SQLite interf
d980: 61 63 65 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75  ace.  For maximu
d990: 6d 20 70 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a  m portability,.*
d9a0: 2a 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e  * it is recommen
d9b0: 64 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61  ded that applica
d9c0: 74 69 6f 6e 73 20 61 6c 77 61 79 73 20 69 6e 76  tions always inv
d9d0: 6f 6b 65 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  oke sqlite3_init
d9e0: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65  ialize().** dire
d9f0: 63 74 6c 79 20 70 72 69 6f 72 20 74 6f 20 75 73  ctly prior to us
da00: 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20 53 51  ing any other SQ
da10: 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 20  Lite interface. 
da20: 20 46 75 74 75 72 65 20 72 65 6c 65 61 73 65 73   Future releases
da30: 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 20 6d 61  .** of SQLite ma
da40: 79 20 72 65 71 75 69 72 65 20 74 68 69 73 2e 20  y require this. 
da50: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
da60: 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 65 78   the behavior ex
da70: 68 69 62 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20  hibited.** when 
da80: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
da90: 65 64 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f  ed with [SQLITE_
daa0: 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d  OMIT_AUTOINIT] m
dab0: 69 67 68 74 20 62 65 63 6f 6d 65 20 74 68 65 0a  ight become the.
dac0: 2a 2a 20 64 65 66 61 75 6c 74 20 62 65 68 61 76  ** default behav
dad0: 69 6f 72 20 69 6e 20 73 6f 6d 65 20 66 75 74 75  ior in some futu
dae0: 72 65 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  re release of SQ
daf0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
db00: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
db10: 29 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f  ) routine does o
db20: 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65 6d 20  perating-system 
db30: 73 70 65 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74  specific.** init
db40: 69 61 6c 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68  ialization of th
db50: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
db60: 2e 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f  .  The sqlite3_o
db70: 73 5f 65 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69  s_end().** routi
db80: 6e 65 20 75 6e 64 6f 65 73 20 74 68 65 20 65 66  ne undoes the ef
db90: 66 65 63 74 20 6f 66 20 73 71 6c 69 74 65 33 5f  fect of sqlite3_
dba0: 6f 73 5f 69 6e 69 74 28 29 2e 20 20 54 79 70 69  os_init().  Typi
dbb0: 63 61 6c 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72  cal tasks.** per
dbc0: 66 6f 72 6d 65 64 20 62 79 20 74 68 65 73 65 20  formed by these 
dbd0: 72 6f 75 74 69 6e 65 73 20 69 6e 63 6c 75 64 65  routines include
dbe0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64   allocation or d
dbf0: 65 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f  eallocation.** o
dc00: 66 20 73 74 61 74 69 63 20 72 65 73 6f 75 72 63  f static resourc
dc10: 65 73 2c 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  es, initializati
dc20: 6f 6e 20 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72  on of global var
dc30: 69 61 62 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69  iables,.** setti
dc40: 6e 67 20 75 70 20 61 20 64 65 66 61 75 6c 74 20  ng up a default 
dc50: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f  [sqlite3_vfs] mo
dc60: 64 75 6c 65 2c 20 6f 72 20 73 65 74 74 69 6e 67  dule, or setting
dc70: 20 75 70 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74   up.** a default
dc80: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75   configuration u
dc90: 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f  sing [sqlite3_co
dca0: 6e 66 69 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54  nfig()]..**.** T
dcb0: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73  he application s
dcc0: 68 6f 75 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f  hould never invo
dcd0: 6b 65 20 65 69 74 68 65 72 20 73 71 6c 69 74 65  ke either sqlite
dce0: 33 5f 6f 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f  3_os_init().** o
dcf0: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64  r sqlite3_os_end
dd00: 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 54 68  () directly.  Th
dd10: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
dd20: 6f 75 6c 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65  ould only invoke
dd30: 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69 6e 69 74  .** sqlite3_init
dd40: 69 61 6c 69 7a 65 28 29 20 61 6e 64 20 73 71 6c  ialize() and sql
dd50: 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e  ite3_shutdown().
dd60: 20 20 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73    The sqlite3_os
dd70: 5f 69 6e 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72  _init().** inter
dd80: 66 61 63 65 20 69 73 20 63 61 6c 6c 65 64 20 61  face is called a
dd90: 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79 20  utomatically by 
dda0: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
ddb0: 7a 65 28 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69  ze() and.** sqli
ddc0: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20  te3_os_end() is 
ddd0: 63 61 6c 6c 65 64 20 62 79 20 73 71 6c 69 74 65  called by sqlite
dde0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 41  3_shutdown().  A
ddf0: 70 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d  ppropriate.** im
de00: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f  plementations fo
de10: 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69  r sqlite3_os_ini
de20: 74 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  t() and sqlite3_
de30: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20  os_end().** are 
de40: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
de50: 65 20 77 68 65 6e 20 69 74 20 69 73 20 63 6f 6d  e when it is com
de60: 70 69 6c 65 64 20 66 6f 72 20 55 6e 69 78 2c 20  piled for Unix, 
de70: 57 69 6e 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32  Windows, or OS/2
de80: 2e 0a 2a 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f  ..** When [custo
de90: 6d 20 62 75 69 6c 64 73 20 7c 20 62 75 69 6c 74  m builds | built
dea0: 20 66 6f 72 20 6f 74 68 65 72 20 70 6c 61 74 66   for other platf
deb0: 6f 72 6d 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20  orms].** (using 
dec0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f  the [SQLITE_OS_O
ded0: 54 48 45 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d  THER=1] compile-
dee0: 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20  time.** option) 
def0: 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
df00: 6d 75 73 74 20 73 75 70 70 6c 79 20 61 20 73 75  must supply a su
df10: 69 74 61 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74  itable implement
df20: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c  ation for.** sql
df30: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61  ite3_os_init() a
df40: 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e  nd sqlite3_os_en
df50: 64 28 29 2e 20 20 41 6e 20 61 70 70 6c 69 63 61  d().  An applica
df60: 74 69 6f 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a  tion-supplied.**
df70: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
df80: 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  of sqlite3_os_in
df90: 69 74 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  it() or sqlite3_
dfa0: 6f 73 5f 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74  os_end().** must
dfb0: 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f   return [SQLITE_
dfc0: 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73 20 61  OK] on success a
dfd0: 6e 64 20 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65  nd some other [e
dfe0: 72 72 6f 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a  rror code] upon.
dff0: 2a 2a 20 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69  ** failure..*/.i
e000: 6e 74 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69  nt sqlite3_initi
e010: 61 6c 69 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74  alize(void);.int
e020: 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77   sqlite3_shutdow
e030: 6e 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c  n(void);.int sql
e040: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69  ite3_os_init(voi
e050: 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  d);.int sqlite3_
e060: 6f 73 5f 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f  os_end(void);../
e070: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e080: 6f 6e 66 69 67 75 72 69 6e 67 20 54 68 65 20 53  onfiguring The S
e090: 51 4c 69 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a  QLite Library.**
e0a0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
e0b0: 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66 61  config() interfa
e0c0: 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d 61  ce is used to ma
e0d0: 6b 65 20 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67  ke global config
e0e0: 75 72 61 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67  uration.** chang
e0f0: 65 73 20 74 6f 20 53 51 4c 69 74 65 20 69 6e 20  es to SQLite in 
e100: 6f 72 64 65 72 20 74 6f 20 74 75 6e 65 20 53 51  order to tune SQ
e110: 4c 69 74 65 20 74 6f 20 74 68 65 20 73 70 65 63  Lite to the spec
e120: 69 66 69 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a  ific needs of.**
e130: 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
e140: 2e 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 63  .  The default c
e150: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 69 73 20  onfiguration is 
e160: 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20  recommended for 
e170: 6d 6f 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74  most.** applicat
e180: 69 6f 6e 73 20 61 6e 64 20 73 6f 20 74 68 69 73  ions and so this
e190: 20 72 6f 75 74 69 6e 65 20 69 73 20 75 73 75 61   routine is usua
e1a0: 6c 6c 79 20 6e 6f 74 20 6e 65 63 65 73 73 61 72  lly not necessar
e1b0: 79 2e 20 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f  y.  It is.** pro
e1c0: 76 69 64 65 64 20 74 6f 20 73 75 70 70 6f 72 74  vided to support
e1d0: 20 72 61 72 65 20 61 70 70 6c 69 63 61 74 69 6f   rare applicatio
e1e0: 6e 73 20 77 69 74 68 20 75 6e 75 73 75 61 6c 20  ns with unusual 
e1f0: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  needs..**.** The
e200: 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28   sqlite3_config(
e210: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  ) interface is n
e220: 6f 74 20 74 68 72 65 61 64 73 61 66 65 2e 20 20  ot threadsafe.  
e230: 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a  The application.
e240: 2a 2a 20 6d 75 73 74 20 69 6e 73 75 72 65 20 74  ** must insure t
e250: 68 61 74 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c  hat no other SQL
e260: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 61  ite interfaces a
e270: 72 65 20 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74  re invoked by ot
e280: 68 65 72 0a 2a 2a 20 74 68 72 65 61 64 73 20 77  her.** threads w
e290: 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e  hile sqlite3_con
e2a0: 66 69 67 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  fig() is running
e2b0: 2e 20 20 46 75 72 74 68 65 72 6d 6f 72 65 2c 20  .  Furthermore, 
e2c0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e2d0: 0a 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20  .** may only be 
e2e0: 69 6e 76 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f  invoked prior to
e2f0: 20 6c 69 62 72 61 72 79 20 69 6e 69 74 69 61 6c   library initial
e300: 69 7a 61 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a  ization using.**
e310: 20 5b 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61   [sqlite3_initia
e320: 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
e330: 20 73 68 75 74 64 6f 77 6e 20 62 79 20 5b 73 71   shutdown by [sq
e340: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
e350: 5d 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  ]..** ^If sqlite
e360: 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 63 61  3_config() is ca
e370: 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
e380: 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29  te3_initialize()
e390: 5d 20 61 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20  ] and before.** 
e3a0: 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77  [sqlite3_shutdow
e3b0: 6e 28 29 5d 20 74 68 65 6e 20 69 74 20 77 69 6c  n()] then it wil
e3c0: 6c 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  l return SQLITE_
e3d0: 4d 49 53 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c  MISUSE..** Note,
e3e0: 20 68 6f 77 65 76 65 72 2c 20 74 68 61 74 20 5e   however, that ^
e3f0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
e400: 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20 61   can be called a
e410: 73 20 70 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a  s part of the.**
e420: 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
e430: 6f 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  of an applicatio
e440: 6e 2d 64 65 66 69 6e 65 64 20 5b 73 71 6c 69 74  n-defined [sqlit
e450: 65 33 5f 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a  e3_os_init()]..*
e460: 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61  *.** The first a
e470: 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74  rgument to sqlit
e480: 65 33 5f 63 6f 6e 66 69 67 28 29 20 69 73 20 61  e3_config() is a
e490: 6e 20 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f  n integer.** [co
e4a0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
e4b0: 6f 6e 5d 20 74 68 61 74 20 64 65 74 65 72 6d 69  on] that determi
e4c0: 6e 65 73 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70  nes.** what prop
e4d0: 65 72 74 79 20 6f 66 20 53 51 4c 69 74 65 20 69  erty of SQLite i
e4e0: 73 20 74 6f 20 62 65 20 63 6f 6e 66 69 67 75 72  s to be configur
e4f0: 65 64 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  ed.  Subsequent 
e500: 61 72 67 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72  arguments.** var
e510: 79 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  y depending on t
e520: 68 65 20 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f  he [configuratio
e530: 6e 20 6f 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20  n option].** in 
e540: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e550: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  nt..**.** ^When 
e560: 61 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  a configuration 
e570: 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 2c 20 73  option is set, s
e580: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20  qlite3_config() 
e590: 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
e5a0: 4f 4b 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  OK]..** ^If the 
e5b0: 6f 70 74 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77  option is unknow
e5c0: 6e 20 6f 72 20 53 51 4c 69 74 65 20 69 73 20 75  n or SQLite is u
e5d0: 6e 61 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65  nable to set the
e5e0: 20 6f 70 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20   option.** then 
e5f0: 74 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  this routine ret
e600: 75 72 6e 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20  urns a non-zero 
e610: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f  [error code]..*/
e620: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e  .int sqlite3_con
e630: 66 69 67 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a  fig(int, ...);..
e640: 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
e650: 43 6f 6e 66 69 67 75 72 65 20 64 61 74 61 62 61  Configure databa
e660: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a  se connections.*
e670: 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33  *.** The sqlite3
e680: 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74  _db_config() int
e690: 65 72 66 61 63 65 20 69 73 20 75 73 65 64 20 74  erface is used t
e6a0: 6f 20 6d 61 6b 65 20 63 6f 6e 66 69 67 75 72 61  o make configura
e6b0: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
e6c0: 74 6f 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  to a [database c
e6d0: 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65  onnection].  The
e6e0: 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 73 69   interface is si
e6f0: 6d 69 6c 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c  milar to.** [sql
e700: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65  ite3_config()] e
e710: 78 63 65 70 74 20 74 68 61 74 20 74 68 65 20 63  xcept that the c
e720: 68 61 6e 67 65 73 20 61 70 70 6c 79 20 74 6f 20  hanges apply to 
e730: 61 20 73 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74  a single.** [dat
e740: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
e750: 5d 20 28 73 70 65 63 69 66 69 65 64 20 69 6e 20  ] (specified in 
e760: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
e770: 6e 74 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73  nt)..**.** The s
e780: 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
e790: 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e  o sqlite3_db_con
e7a0: 66 69 67 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73  fig(D,V,...)  is
e7b0: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
e7c0: 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49  DBCONFIG_LOOKASI
e7d0: 44 45 20 7c 20 63 6f 6e 66 69 67 75 72 61 74 69  DE | configurati
e7e0: 6f 6e 20 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e  on verb] - an in
e7f0: 74 65 67 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74  teger code .** t
e800: 68 61 74 20 69 6e 64 69 63 61 74 65 73 20 77 68  hat indicates wh
e810: 61 74 20 61 73 70 65 63 74 20 6f 66 20 74 68 65  at aspect of the
e820: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
e830: 63 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20  ction] is being 
e840: 63 6f 6e 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53  configured..** S
e850: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
e860: 6e 74 73 20 76 61 72 79 20 64 65 70 65 6e 64 69  nts vary dependi
e870: 6e 67 20 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67  ng on the config
e880: 75 72 61 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a  uration verb..**
e890: 0a 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71  .** ^Calls to sq
e8a0: 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28  lite3_db_config(
e8b0: 29 20 72 65 74 75 72 6e 20 53 51 4c 49 54 45 5f  ) return SQLITE_
e8c0: 4f 4b 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69  OK if and only i
e8d0: 66 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 69 73  f.** the call is
e8e0: 20 63 6f 6e 73 69 64 65 72 65 64 20 73 75 63 63   considered succ
e8f0: 65 73 73 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73  essful..*/.int s
e900: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
e910: 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f  (sqlite3*, int o
e920: 70 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20  p, ...);../*.** 
e930: 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
e940: 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74   Allocation Rout
e950: 69 6e 65 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ines.**.** An in
e960: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
e970: 62 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68  bject defines th
e980: 65 20 69 6e 74 65 72 66 61 63 65 20 62 65 74 77  e interface betw
e990: 65 65 6e 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e  een SQLite.** an
e9a0: 64 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  d low-level memo
e9b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
e9c0: 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  utines..**.** Th
e9d0: 69 73 20 6f 62 6a 65 63 74 20 69 73 20 75 73 65  is object is use
e9e0: 64 20 69 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c  d in only one pl
e9f0: 61 63 65 20 69 6e 20 74 68 65 20 53 51 4c 69 74  ace in the SQLit
ea00: 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20  e interface..** 
ea10: 41 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20  A pointer to an 
ea20: 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
ea30: 20 6f 62 6a 65 63 74 20 69 73 20 74 68 65 20 61   object is the a
ea40: 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73  rgument to.** [s
ea50: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
ea60: 20 77 68 65 6e 20 74 68 65 20 63 6f 6e 66 69 67   when the config
ea70: 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69  uration option i
ea80: 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  s.** [SQLITE_CON
ea90: 46 49 47 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b  FIG_MALLOC] or [
eaa0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
eab0: 54 4d 41 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42  TMALLOC].  .** B
eac0: 79 20 63 72 65 61 74 69 6e 67 20 61 6e 20 69 6e  y creating an in
ead0: 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f  stance of this o
eae0: 62 6a 65 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73  bject.** and pas
eaf0: 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69  sing it to [sqli
eb00: 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
eb10: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
eb20: 43 5d 29 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f  C]).** during co
eb30: 6e 66 69 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20  nfiguration, an 
eb40: 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20  application can 
eb50: 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65 72  specify an alter
eb60: 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79  native.** memory
eb70: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
eb80: 79 73 74 65 6d 20 66 6f 72 20 53 51 4c 69 74 65  ystem for SQLite
eb90: 20 74 6f 20 75 73 65 20 66 6f 72 20 61 6c 6c 20   to use for all 
eba0: 6f 66 20 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69  of its.** dynami
ebb0: 63 20 6d 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a  c memory needs..
ebc0: 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
ebd0: 53 51 4c 69 74 65 20 63 6f 6d 65 73 20 77 69 74  SQLite comes wit
ebe0: 68 20 73 65 76 65 72 61 6c 20 5b 62 75 69 6c 74  h several [built
ebf0: 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
ec00: 61 74 6f 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61  ators].** that a
ec10: 72 65 20 70 65 72 66 65 63 74 6c 79 20 61 64 65  re perfectly ade
ec20: 71 75 61 74 65 20 66 6f 72 20 74 68 65 20 6f 76  quate for the ov
ec30: 65 72 77 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72  erwhelming major
ec40: 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74 69  ity of applicati
ec50: 6f 6e 73 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20  ons.** and that 
ec60: 74 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 6f  this object is o
ec70: 6e 6c 79 20 75 73 65 66 75 6c 20 74 6f 20 61 20  nly useful to a 
ec80: 74 69 6e 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66  tiny minority of
ec90: 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
eca0: 20 77 69 74 68 20 73 70 65 63 69 61 6c 69 7a 65   with specialize
ecb0: 64 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  d memory allocat
ecc0: 69 6f 6e 20 72 65 71 75 69 72 65 6d 65 6e 74 73  ion requirements
ecd0: 2e 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  .  This object i
ece0: 73 0a 2a 2a 20 61 6c 73 6f 20 75 73 65 64 20 64  s.** also used d
ecf0: 75 72 69 6e 67 20 74 65 73 74 69 6e 67 20 6f 66  uring testing of
ed00: 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64 65 72   SQLite in order
ed10: 20 74 6f 20 73 70 65 63 69 66 79 20 61 6e 20 61   to specify an a
ed20: 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65  lternative.** me
ed30: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74  mory allocator t
ed40: 68 61 74 20 73 69 6d 75 6c 61 74 65 73 20 6d 65  hat simulates me
ed50: 6d 6f 72 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f  mory out-of-memo
ed60: 72 79 20 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e  ry conditions in
ed70: 0a 2a 2a 20 6f 72 64 65 72 20 74 6f 20 76 65 72  .** order to ver
ed80: 69 66 79 20 74 68 61 74 20 53 51 4c 69 74 65 20  ify that SQLite 
ed90: 72 65 63 6f 76 65 72 73 20 67 72 61 63 65 66 75  recovers gracefu
eda0: 6c 6c 79 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a  lly from such.**
edb0: 20 63 6f 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a   conditions..**.
edc0: 2a 2a 20 54 68 65 20 78 4d 61 6c 6c 6f 63 2c 20  ** The xMalloc, 
edd0: 78 52 65 61 6c 6c 6f 63 2c 20 61 6e 64 20 78 46  xRealloc, and xF
ede0: 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75 73 74  ree methods must
edf0: 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65 0a 2a   work like the.*
ee00: 2a 20 6d 61 6c 6c 6f 63 28 29 2c 20 72 65 61 6c  * malloc(), real
ee10: 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
ee20: 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d 20   functions from 
ee30: 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
ee40: 69 62 72 61 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  ibrary..** ^SQLi
ee50: 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  te guarantees th
ee60: 61 74 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  at the second ar
ee70: 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65  gument to.** xRe
ee80: 61 6c 6c 6f 63 20 69 73 20 61 6c 77 61 79 73 20  alloc is always 
ee90: 61 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  a value returned
eea0: 20 62 79 20 61 20 70 72 69 6f 72 20 63 61 6c 6c   by a prior call
eeb0: 20 74 6f 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a   to xRoundup..**
eec0: 0a 2a 2a 20 78 53 69 7a 65 20 73 68 6f 75 6c 64  .** xSize should
eed0: 20 72 65 74 75 72 6e 20 74 68 65 20 61 6c 6c 6f   return the allo
eee0: 63 61 74 65 64 20 73 69 7a 65 20 6f 66 20 61 20  cated size of a 
eef0: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
ef00: 6e 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  n.** previously 
ef10: 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 78 4d  obtained from xM
ef20: 61 6c 6c 6f 63 20 6f 72 20 78 52 65 61 6c 6c 6f  alloc or xReallo
ef30: 63 2e 20 20 54 68 65 20 61 6c 6c 6f 63 61 74 65  c.  The allocate
ef40: 64 20 73 69 7a 65 0a 2a 2a 20 69 73 20 61 6c 77  d size.** is alw
ef50: 61 79 73 20 61 74 20 6c 65 61 73 74 20 61 73 20  ays at least as 
ef60: 62 69 67 20 61 73 20 74 68 65 20 72 65 71 75 65  big as the reque
ef70: 73 74 65 64 20 73 69 7a 65 20 62 75 74 20 6d 61  sted size but ma
ef80: 79 20 62 65 20 6c 61 72 67 65 72 2e 0a 2a 2a 0a  y be larger..**.
ef90: 2a 2a 20 54 68 65 20 78 52 6f 75 6e 64 75 70 20  ** The xRoundup 
efa0: 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 77  method returns w
efb0: 68 61 74 20 77 6f 75 6c 64 20 62 65 20 74 68 65  hat would be the
efc0: 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20   allocated size 
efd0: 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f 72 79 20 61  of.** a memory a
efe0: 6c 6c 6f 63 61 74 69 6f 6e 20 67 69 76 65 6e 20  llocation given 
eff0: 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 65 71  a particular req
f000: 75 65 73 74 65 64 20 73 69 7a 65 2e 20 20 4d 6f  uested size.  Mo
f010: 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c  st memory.** all
f020: 6f 63 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70  ocators round up
f030: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f040: 6f 6e 73 20 61 74 20 6c 65 61 73 74 20 74 6f 20  ons at least to 
f050: 74 68 65 20 6e 65 78 74 20 6d 75 6c 74 69 70 6c  the next multipl
f060: 65 0a 2a 2a 20 6f 66 20 38 2e 20 20 53 6f 6d 65  e.** of 8.  Some
f070: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
f080: 64 20 75 70 20 74 6f 20 61 20 6c 61 72 67 65 72  d up to a larger
f090: 20 6d 75 6c 74 69 70 6c 65 20 6f 72 20 74 6f 20   multiple or to 
f0a0: 61 20 70 6f 77 65 72 20 6f 66 20 32 2e 0a 2a 2a  a power of 2..**
f0b0: 20 45 76 65 72 79 20 6d 65 6d 6f 72 79 20 61 6c   Every memory al
f0c0: 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 65 73 74  location request
f0d0: 20 63 6f 6d 69 6e 67 20 69 6e 20 74 68 72 6f 75   coming in throu
f0e0: 67 68 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  gh [sqlite3_mall
f0f0: 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20 5b 73 71 6c  oc()].** or [sql
f100: 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20  ite3_realloc()] 
f110: 66 69 72 73 74 20 63 61 6c 6c 73 20 78 52 6f 75  first calls xRou
f120: 6e 64 75 70 2e 20 20 49 66 20 78 52 6f 75 6e 64  ndup.  If xRound
f130: 75 70 20 72 65 74 75 72 6e 73 20 30 2c 20 0a 2a  up returns 0, .*
f140: 2a 20 74 68 61 74 20 63 61 75 73 65 73 20 74 68  * that causes th
f150: 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
f160: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f170: 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a  n to fail..**.**
f180: 20 54 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f   The xInit metho
f190: 64 20 69 6e 69 74 69 61 6c 69 7a 65 73 20 74 68  d initializes th
f1a0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
f1b0: 6f 72 2e 20 20 28 46 6f 72 20 65 78 61 6d 70 6c  or.  (For exampl
f1c0: 65 2c 0a 2a 2a 20 69 74 20 6d 69 67 68 74 20 61  e,.** it might a
f1d0: 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65 71 75  llocate any requ
f1e0: 69 72 65 20 6d 75 74 65 78 65 73 20 6f 72 20 69  ire mutexes or i
f1f0: 6e 69 74 69 61 6c 69 7a 65 20 69 6e 74 65 72 6e  nitialize intern
f200: 61 6c 20 64 61 74 61 0a 2a 2a 20 73 74 72 75 63  al data.** struc
f210: 74 75 72 65 73 2e 20 20 54 68 65 20 78 53 68 75  tures.  The xShu
f220: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f230: 69 6e 76 6f 6b 65 64 20 28 69 6e 64 69 72 65 63  invoked (indirec
f240: 74 6c 79 29 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  tly) by.** [sqli
f250: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
f260: 61 6e 64 20 73 68 6f 75 6c 64 20 64 65 61 6c 6c  and should deall
f270: 6f 63 61 74 65 20 61 6e 79 20 72 65 73 6f 75 72  ocate any resour
f280: 63 65 73 20 61 63 71 75 69 72 65 64 0a 2a 2a 20  ces acquired.** 
f290: 62 79 20 78 49 6e 69 74 2e 20 20 54 68 65 20 70  by xInit.  The p
f2a0: 41 70 70 44 61 74 61 20 70 6f 69 6e 74 65 72 20  AppData pointer 
f2b0: 69 73 20 75 73 65 64 20 61 73 20 74 68 65 20 6f  is used as the o
f2c0: 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f  nly parameter to
f2d0: 0a 2a 2a 20 78 49 6e 69 74 20 61 6e 64 20 78 53  .** xInit and xS
f2e0: 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a 2a 2a 20 53  hutdown..**.** S
f2f0: 51 4c 69 74 65 20 68 6f 6c 64 73 20 74 68 65 20  QLite holds the 
f300: 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f 53 54  [SQLITE_MUTEX_ST
f310: 41 54 49 43 5f 4d 41 53 54 45 52 5d 20 6d 75 74  ATIC_MASTER] mut
f320: 65 78 20 77 68 65 6e 20 69 74 20 69 6e 76 6f 6b  ex when it invok
f330: 65 73 0a 2a 2a 20 74 68 65 20 78 49 6e 69 74 20  es.** the xInit 
f340: 6d 65 74 68 6f 64 2c 20 73 6f 20 74 68 65 20 78  method, so the x
f350: 49 6e 69 74 20 6d 65 74 68 6f 64 20 6e 65 65 64  Init method need
f360: 20 6e 6f 74 20 62 65 20 74 68 72 65 61 64 73 61   not be threadsa
f370: 66 65 2e 20 20 54 68 65 0a 2a 2a 20 78 53 68 75  fe.  The.** xShu
f380: 74 64 6f 77 6e 20 6d 65 74 68 6f 64 20 69 73 20  tdown method is 
f390: 6f 6e 6c 79 20 63 61 6c 6c 65 64 20 66 72 6f 6d  only called from
f3a0: 20 5b 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f   [sqlite3_shutdo
f3b0: 77 6e 28 29 5d 20 73 6f 20 69 74 20 64 6f 65 73  wn()] so it does
f3c0: 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20  .** not need to 
f3d0: 62 65 20 74 68 72 65 61 64 73 61 66 65 20 65 69  be threadsafe ei
f3e0: 74 68 65 72 2e 20 20 46 6f 72 20 61 6c 6c 20 6f  ther.  For all o
f3f0: 74 68 65 72 20 6d 65 74 68 6f 64 73 2c 20 53 51  ther methods, SQ
f400: 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64 73 20 74 68  Lite.** holds th
f410: 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45 58 5f  e [SQLITE_MUTEX_
f420: 53 54 41 54 49 43 5f 4d 45 4d 5d 20 6d 75 74 65  STATIC_MEM] mute
f430: 78 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  x as long as the
f440: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  .** [SQLITE_CONF
f450: 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20 63 6f  IG_MEMSTATUS] co
f460: 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
f470: 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 6e 20  on is turned on 
f480: 28 77 68 69 63 68 0a 2a 2a 20 69 74 20 69 73 20  (which.** it is 
f490: 62 79 20 64 65 66 61 75 6c 74 29 20 61 6e 64 20  by default) and 
f4a0: 73 6f 20 74 68 65 20 6d 65 74 68 6f 64 73 20 61  so the methods a
f4b0: 72 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  re automatically
f4c0: 20 73 65 72 69 61 6c 69 7a 65 64 2e 0a 2a 2a 20   serialized..** 
f4d0: 48 6f 77 65 76 65 72 2c 20 69 66 20 5b 53 51 4c  However, if [SQL
f4e0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
f4f0: 41 54 55 53 5d 20 69 73 20 64 69 73 61 62 6c 65  ATUS] is disable
f500: 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 74 68 65  d, then the othe
f510: 72 0a 2a 2a 20 6d 65 74 68 6f 64 73 20 6d 75 73  r.** methods mus
f520: 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65 20  t be threadsafe 
f530: 6f 72 20 65 6c 73 65 20 6d 61 6b 65 20 74 68 65  or else make the
f540: 69 72 20 6f 77 6e 20 61 72 72 61 6e 67 65 6d 65  ir own arrangeme
f550: 6e 74 73 20 66 6f 72 0a 2a 2a 20 73 65 72 69 61  nts for.** seria
f560: 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  lization..**.** 
f570: 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76 65  SQLite will neve
f580: 72 20 69 6e 76 6f 6b 65 20 78 49 6e 69 74 28 29  r invoke xInit()
f590: 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63 65 20   more than once 
f5a0: 77 69 74 68 6f 75 74 20 61 6e 20 69 6e 74 65 72  without an inter
f5b0: 76 65 6e 69 6e 67 0a 2a 2a 20 63 61 6c 6c 20 74  vening.** call t
f5c0: 6f 20 78 53 68 75 74 64 6f 77 6e 28 29 2e 0a 2a  o xShutdown()..*
f5d0: 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74  /.typedef struct
f5e0: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f5f0: 68 6f 64 73 20 73 71 6c 69 74 65 33 5f 6d 65 6d  hods sqlite3_mem
f600: 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75 63 74  _methods;.struct
f610: 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74   sqlite3_mem_met
f620: 68 6f 64 73 20 7b 0a 20 20 76 6f 69 64 20 2a 28  hods {.  void *(
f630: 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e 74 29 3b 20  *xMalloc)(int); 
f640: 20 20 20 20 20 20 20 20 2f 2a 20 4d 65 6d 6f 72          /* Memor
f650: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 75 6e  y allocation fun
f660: 63 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20  ction */.  void 
f670: 28 2a 78 46 72 65 65 29 28 76 6f 69 64 2a 29 3b  (*xFree)(void*);
f680: 20 20 20 20 20 20 20 20 20 20 2f 2a 20 46 72 65            /* Fre
f690: 65 20 61 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61  e a prior alloca
f6a0: 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f 69 64 20 2a  tion */.  void *
f6b0: 28 2a 78 52 65 61 6c 6c 6f 63 29 28 76 6f 69 64  (*xRealloc)(void
f6c0: 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20 52 65 73 69  *,int);  /* Resi
f6d0: 7a 65 20 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e  ze an allocation
f6e0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 69 7a   */.  int (*xSiz
f6f0: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
f700: 20 20 20 20 20 2f 2a 20 52 65 74 75 72 6e 20 74       /* Return t
f710: 68 65 20 73 69 7a 65 20 6f 66 20 61 6e 20 61 6c  he size of an al
f720: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e  location */.  in
f730: 74 20 28 2a 78 52 6f 75 6e 64 75 70 29 28 69 6e  t (*xRoundup)(in
f740: 74 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a 20  t);          /* 
f750: 52 6f 75 6e 64 20 75 70 20 72 65 71 75 65 73 74  Round up request
f760: 20 73 69 7a 65 20 74 6f 20 61 6c 6c 6f 63 61 74   size to allocat
f770: 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a 20 20 69 6e  ion size */.  in
f780: 74 20 28 2a 78 49 6e 69 74 29 28 76 6f 69 64 2a  t (*xInit)(void*
f790: 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20  );           /* 
f7a0: 49 6e 69 74 69 61 6c 69 7a 65 20 74 68 65 20 6d  Initialize the m
f7b0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
f7c0: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 53 68 75  */.  void (*xShu
f7d0: 74 64 6f 77 6e 29 28 76 6f 69 64 2a 29 3b 20 20  tdown)(void*);  
f7e0: 20 20 20 20 2f 2a 20 44 65 69 6e 69 74 69 61 6c      /* Deinitial
f7f0: 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  ize the memory a
f800: 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76 6f  llocator */.  vo
f810: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
f820: 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
f830: 41 72 67 75 6d 65 6e 74 20 74 6f 20 78 49 6e 69  Argument to xIni
f840: 74 28 29 20 61 6e 64 20 78 53 68 75 74 64 6f 77  t() and xShutdow
f850: 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a  n() */.};../*.**
f860: 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66 69   CAPI3REF: Confi
f870: 67 75 72 61 74 69 6f 6e 20 4f 70 74 69 6f 6e 73  guration Options
f880: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 63  .** KEYWORDS: {c
f890: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
f8a0: 69 6f 6e 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ion}.**.** These
f8b0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
f8c0: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
f8d0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
f8e0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
f8f0: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
f900: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
f910: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
f920: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
f930: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
f940: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
f950: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
f960: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
f970: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
f980: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
f990: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
f9a0: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
f9b0: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
f9c0: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
f9d0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
f9e0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
f9f0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
fa00: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
fa10: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
fa20: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
fa30: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
fa40: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
fa50: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
fa60: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
fa70: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
fa80: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
fa90: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
faa0: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
fab0: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
fac0: 3c 64 6c 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  <dl>.** [[SQLITE
fad0: 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48  _CONFIG_SINGLETH
fae0: 52 45 41 44 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  READ]] <dt>SQLIT
faf0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
fb00: 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  HREAD</dt>.** <d
fb10: 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61  d>There are no a
fb20: 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73  rguments to this
fb30: 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20   option.  ^This 
fb40: 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a  option sets the.
fb50: 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ** [threading mo
fb60: 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74 68  de] to Single-th
fb70: 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72 20  read.  In other 
fb80: 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62 6c  words, it disabl
fb90: 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78 69  es.** all mutexi
fba0: 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c 69  ng and puts SQLi
fbb0: 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20 77  te into a mode w
fbc0: 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c 79  here it can only
fbd0: 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20 61   be used.** by a
fbe0: 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e 20   single thread. 
fbf0: 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20    ^If SQLite is 
fc00: 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a  compiled with.**
fc10: 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52   the [SQLITE_THR
fc20: 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45  EADSAFE | SQLITE
fc30: 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63  _THREADSAFE=0] c
fc40: 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69  ompile-time opti
fc50: 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73  on then.** it is
fc60: 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f   not possible to
fc70: 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68 72   change the [thr
fc80: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72 6f  eading mode] fro
fc90: 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a 2a  m its default.**
fca0: 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c 65   value of Single
fcb0: 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20 5b  -thread and so [
fcc0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
fcd0: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a 2a  ] will return .*
fce0: 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  * [SQLITE_ERROR]
fcf0: 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20   if called with 
fd00: 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
fd10: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a 2a  G_SINGLETHREAD.*
fd20: 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  * configuration 
fd30: 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a  option.</dd>.**.
fd40: 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
fd50: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 5d  IG_MULTITHREAD]]
fd60: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
fd70: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 3c 2f  IG_MULTITHREAD</
fd80: 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65  dt>.** <dd>There
fd90: 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74   are no argument
fda0: 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e  s to this option
fdb0: 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  .  ^This option 
fdc0: 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72  sets the.** [thr
fdd0: 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20  eading mode] to 
fde0: 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e 20 20 49  Multi-thread.  I
fdf0: 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 69  n other words, i
fe00: 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20 6d 75  t disables.** mu
fe10: 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61 74 61 62  texing on [datab
fe20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
fe30: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
fe40: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
fe50: 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  ..** The applica
fe60: 74 69 6f 6e 20 69 73 20 72 65 73 70 6f 6e 73 69  tion is responsi
fe70: 62 6c 65 20 66 6f 72 20 73 65 72 69 61 6c 69 7a  ble for serializ
fe80: 69 6e 67 20 61 63 63 65 73 73 20 74 6f 0a 2a 2a  ing access to.**
fe90: 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
fea0: 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65  ctions] and [pre
feb0: 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73  pared statements
fec0: 5d 2e 20 20 42 75 74 20 6f 74 68 65 72 20 6d 75  ].  But other mu
fed0: 74 65 78 65 73 0a 2a 2a 20 61 72 65 20 65 6e 61  texes.** are ena
fee0: 62 6c 65 64 20 73 6f 20 74 68 61 74 20 53 51 4c  bled so that SQL
fef0: 69 74 65 20 77 69 6c 6c 20 62 65 20 73 61 66 65  ite will be safe
ff00: 20 74 6f 20 75 73 65 20 69 6e 20 61 20 6d 75 6c   to use in a mul
ff10: 74 69 2d 74 68 72 65 61 64 65 64 0a 2a 2a 20 65  ti-threaded.** e
ff20: 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73 20 6c 6f  nvironment as lo
ff30: 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20 74 68 72  ng as no two thr
ff40: 65 61 64 73 20 61 74 74 65 6d 70 74 20 74 6f 20  eads attempt to 
ff50: 75 73 65 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20  use the same.** 
ff60: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
ff70: 74 69 6f 6e 5d 20 61 74 20 74 68 65 20 73 61 6d  tion] at the sam
ff80: 65 20 74 69 6d 65 2e 20 20 5e 49 66 20 53 51 4c  e time.  ^If SQL
ff90: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
ffa0: 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
ffb0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
ffc0: 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
ffd0: 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
ffe0: 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
fff0: 2a 20 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73  * it is not poss
10000 69 62 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20  ible to set the 
10010 4d 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68  Multi-thread [th
10020 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 6e  reading mode] an
10030 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d.** [sqlite3_co
10040 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72 65 74  nfig()] will ret
10050 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  urn [SQLITE_ERRO
10060 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74  R] if called wit
10070 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f  h the.** SQLITE_
10080 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45  CONFIG_MULTITHRE
10090 41 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  AD configuration
100a0 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
100b0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
100c0 46 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 5d 5d  FIG_SERIALIZED]]
100d0 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
100e0 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 3c 2f 64  IG_SERIALIZED</d
100f0 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72 65 20  t>.** <dd>There 
10100 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73  are no arguments
10110 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f 6e 2e   to this option.
10120 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73    ^This option s
10130 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68 72 65  ets the.** [thre
10140 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f 20 53  ading mode] to S
10150 65 72 69 61 6c 69 7a 65 64 2e 20 49 6e 20 6f 74  erialized. In ot
10160 68 65 72 20 77 6f 72 64 73 2c 20 74 68 69 73 20  her words, this 
10170 6f 70 74 69 6f 6e 20 65 6e 61 62 6c 65 73 0a 2a  option enables.*
10180 2a 20 61 6c 6c 20 6d 75 74 65 78 65 73 20 69 6e  * all mutexes in
10190 63 6c 75 64 69 6e 67 20 74 68 65 20 72 65 63 75  cluding the recu
101a0 72 73 69 76 65 0a 2a 2a 20 6d 75 74 65 78 65 73  rsive.** mutexes
101b0 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
101c0 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
101d0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
101e0 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 49  t] objects..** I
101f0 6e 20 74 68 69 73 20 6d 6f 64 65 20 28 77 68 69  n this mode (whi
10200 63 68 20 69 73 20 74 68 65 20 64 65 66 61 75 6c  ch is the defaul
10210 74 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73  t when SQLite is
10220 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
10230 2a 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44  * [SQLITE_THREAD
10240 53 41 46 45 3d 31 5d 29 20 74 68 65 20 53 51 4c  SAFE=1]) the SQL
10250 69 74 65 20 6c 69 62 72 61 72 79 20 77 69 6c 6c  ite library will
10260 20 69 74 73 65 6c 66 20 73 65 72 69 61 6c 69 7a   itself serializ
10270 65 20 61 63 63 65 73 73 0a 2a 2a 20 74 6f 20 5b  e access.** to [
10280 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
10290 69 6f 6e 73 5d 20 61 6e 64 20 5b 70 72 65 70 61  ions] and [prepa
102a0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d 20  red statements] 
102b0 73 6f 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 61  so that the.** a
102c0 70 70 6c 69 63 61 74 69 6f 6e 20 69 73 20 66 72  pplication is fr
102d0 65 65 20 74 6f 20 75 73 65 20 74 68 65 20 73 61  ee to use the sa
102e0 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  me [database con
102f0 6e 65 63 74 69 6f 6e 5d 20 6f 72 20 74 68 65 0a  nection] or the.
10300 2a 2a 20 73 61 6d 65 20 5b 70 72 65 70 61 72 65  ** same [prepare
10310 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20  d statement] in 
10320 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61 64  different thread
10330 73 20 61 74 20 74 68 65 20 73 61 6d 65 20 74 69  s at the same ti
10340 6d 65 2e 0a 2a 2a 20 5e 49 66 20 53 51 4c 69 74  me..** ^If SQLit
10350 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69  e is compiled wi
10360 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54  th.** the [SQLIT
10370 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53  E_THREADSAFE | S
10380 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
10390 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  =0] compile-time
103a0 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20   option then.** 
103b0 69 74 20 69 73 20 6e 6f 74 20 70 6f 73 73 69 62  it is not possib
103c0 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 53 65  le to set the Se
103d0 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61 64  rialized [thread
103e0 69 6e 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a  ing mode] and.**
103f0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
10400 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20  ()] will return 
10410 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69  [SQLITE_ERROR] i
10420 66 20 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68  f called with th
10430 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46  e.** SQLITE_CONF
10440 49 47 5f 53 45 52 49 41 4c 49 5a 45 44 20 63 6f  IG_SERIALIZED co
10450 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
10460 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  on.</dd>.**.** [
10470 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
10480 41 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49  ALLOC]] <dt>SQLI
10490 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43  TE_CONFIG_MALLOC
104a0 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
104b0 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
104c0 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
104d0 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
104e0 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20  ointer to an.** 
104f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20  instance of the 
10500 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74  [sqlite3_mem_met
10510 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e  hods] structure.
10520 20 20 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73    The argument s
10530 70 65 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65  pecifies.** alte
10540 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65  rnative low-leve
10550 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
10560 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20 74 6f 20  ion routines to 
10570 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61 63 65  be used in place
10580 20 6f 66 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72   of.** the memor
10590 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75  y allocation rou
105a0 74 69 6e 65 73 20 62 75 69 6c 74 20 69 6e 74 6f  tines built into
105b0 20 53 51 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69   SQLite.)^ ^SQLi
105c0 74 65 20 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20  te makes.** its 
105d0 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
105e0 20 6f 66 20 74 68 65 20 63 6f 6e 74 65 6e 74 20   of the content 
105f0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10600 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72  mem_methods] str
10610 75 63 74 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65  ucture.** before
10620 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f   the [sqlite3_co
10630 6e 66 69 67 28 29 5d 20 63 61 6c 6c 20 72 65 74  nfig()] call ret
10640 75 72 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  urns.</dd>.**.**
10650 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
10660 5f 47 45 54 4d 41 4c 4c 4f 43 5d 5d 20 3c 64 74  _GETMALLOC]] <dt
10670 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47  >SQLITE_CONFIG_G
10680 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a 2a  ETMALLOC</dt>.**
10690 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74   <dd> ^(This opt
106a0 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67  ion takes a sing
106b0 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63  le argument whic
106c0 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  h is a pointer t
106d0 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65  o an.** instance
106e0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
106f0 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73 74  _mem_methods] st
10700 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b 73  ructure.  The [s
10710 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
10720 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
10730 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
10740 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
10750 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c 6c  fined memory all
10760 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73  ocation routines
10770 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74 69  .)^.** This opti
10780 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  on can be used t
10790 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20 64  o overload the d
107a0 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c  efault memory al
107b0 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75 74  location.** rout
107c0 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61 70  ines with a wrap
107d0 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61 74  per that simulat
107e0 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  ions memory allo
107f0 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20 6f  cation failure o
10800 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d 6f  r.** tracks memo
10810 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65 78  ry usage, for ex
10820 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a  ample. </dd>.**.
10830 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
10840 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 5d 20 3c  IG_MEMSTATUS]] <
10850 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10860 5f 4d 45 4d 53 54 41 54 55 53 3c 2f 64 74 3e 0a  _MEMSTATUS</dt>.
10870 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
10880 74 69 6f 6e 20 74 61 6b 65 73 20 73 69 6e 67 6c  tion takes singl
10890 65 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 79  e argument of ty
108a0 70 65 20 69 6e 74 2c 20 69 6e 74 65 72 70 72 65  pe int, interpre
108b0 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 62 6f 6f  ted as a .** boo
108c0 6c 65 61 6e 2c 20 77 68 69 63 68 20 65 6e 61 62  lean, which enab
108d0 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20  les or disables 
108e0 74 68 65 20 63 6f 6c 6c 65 63 74 69 6f 6e 20 6f  the collection o
108f0 66 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  f memory allocat
10900 69 6f 6e 20 0a 2a 2a 20 73 74 61 74 69 73 74 69  ion .** statisti
10910 63 73 2e 20 5e 28 57 68 65 6e 20 6d 65 6d 6f 72  cs. ^(When memor
10920 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10930 74 69 73 74 69 63 73 20 61 72 65 20 64 69 73 61  tistics are disa
10940 62 6c 65 64 2c 20 74 68 65 20 0a 2a 2a 20 66 6f  bled, the .** fo
10950 6c 6c 6f 77 69 6e 67 20 53 51 4c 69 74 65 20 69  llowing SQLite i
10960 6e 74 65 72 66 61 63 65 73 20 62 65 63 6f 6d 65  nterfaces become
10970 20 6e 6f 6e 2d 6f 70 65 72 61 74 69 6f 6e 61 6c   non-operational
10980 3a 0a 2a 2a 20 20 20 3c 75 6c 3e 0a 2a 2a 20 20  :.**   <ul>.**  
10990 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 6d   <li> [sqlite3_m
109a0 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 0a 2a 2a  emory_used()].**
109b0 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33     <li> [sqlite3
109c0 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65  _memory_highwate
109d0 72 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b  r()].**   <li> [
109e0 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
109f0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
10a00 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f    <li> [sqlite3_
10a10 73 74 61 74 75 73 28 29 5d 0a 2a 2a 20 20 20 3c  status()].**   <
10a20 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 4d 65 6d 6f 72  /ul>)^.** ^Memor
10a30 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61  y allocation sta
10a40 74 69 73 74 69 63 73 20 61 72 65 20 65 6e 61 62  tistics are enab
10a50 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 75  led by default u
10a60 6e 6c 65 73 73 20 53 51 4c 69 74 65 20 69 73 0a  nless SQLite is.
10a70 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ** compiled with
10a80 20 5b 53 51 4c 49 54 45 5f 44 45 46 41 55 4c 54   [SQLITE_DEFAULT
10a90 5f 4d 45 4d 53 54 41 54 55 53 5d 3d 30 20 69 6e  _MEMSTATUS]=0 in
10aa0 20 77 68 69 63 68 20 63 61 73 65 20 6d 65 6d 6f   which case memo
10ab0 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e  ry.** allocation
10ac0 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65 20   statistics are 
10ad0 64 69 73 61 62 6c 65 64 20 62 79 20 64 65 66 61  disabled by defa
10ae0 75 6c 74 2e 0a 2a 2a 20 3c 2f 64 64 3e 0a 2a 2a  ult..** </dd>.**
10af0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e  .** [[SQLITE_CON
10b00 46 49 47 5f 53 43 52 41 54 43 48 5d 5d 20 3c 64  FIG_SCRATCH]] <d
10b10 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10b20 53 43 52 41 54 43 48 3c 2f 64 74 3e 0a 2a 2a 20  SCRATCH</dt>.** 
10b30 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
10b40 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73 74  n specifies a st
10b50 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66 66  atic memory buff
10b60 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20 63  er that SQLite c
10b70 61 6e 20 75 73 65 20 66 6f 72 0a 2a 2a 20 73 63  an use for.** sc
10b80 72 61 74 63 68 20 6d 65 6d 6f 72 79 2e 20 20 54  ratch memory.  T
10b90 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
10ba0 72 67 75 6d 65 6e 74 73 3a 20 20 41 20 70 6f 69  rguments:  A poi
10bb0 6e 74 65 72 20 61 6e 20 38 2d 62 79 74 65 0a 2a  nter an 8-byte.*
10bc0 2a 20 61 6c 69 67 6e 65 64 20 6d 65 6d 6f 72 79  * aligned memory
10bd0 20 62 75 66 66 65 72 20 66 72 6f 6d 20 77 68 69   buffer from whi
10be0 63 68 20 74 68 65 20 73 63 72 61 74 63 68 20 61  ch the scratch a
10bf0 6c 6c 6f 63 61 74 69 6f 6e 73 20 77 69 6c 6c 20  llocations will 
10c00 62 65 0a 2a 2a 20 64 72 61 77 6e 2c 20 74 68 65  be.** drawn, the
10c10 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 73 63   size of each sc
10c20 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
10c30 20 28 73 7a 29 2c 0a 2a 2a 20 61 6e 64 20 74 68   (sz),.** and th
10c40 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
10c50 20 6f 66 20 73 63 72 61 74 63 68 20 61 6c 6c 6f   of scratch allo
10c60 63 61 74 69 6f 6e 73 20 28 4e 29 2e 20 20 54 68  cations (N).  Th
10c70 65 20 73 7a 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  e sz.** argument
10c80 20 6d 75 73 74 20 62 65 20 61 20 6d 75 6c 74 69   must be a multi
10c90 70 6c 65 20 6f 66 20 31 36 2e 0a 2a 2a 20 54 68  ple of 16..** Th
10ca0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
10cb0 20 6d 75 73 74 20 62 65 20 61 20 70 6f 69 6e 74   must be a point
10cc0 65 72 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 20  er to an 8-byte 
10cd0 61 6c 69 67 6e 65 64 20 62 75 66 66 65 72 0a 2a  aligned buffer.*
10ce0 2a 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73 7a  * of at least sz
10cf0 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f  *N bytes of memo
10d00 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 77  ry..** ^SQLite w
10d10 69 6c 6c 20 75 73 65 20 6e 6f 20 6d 6f 72 65 20  ill use no more 
10d20 74 68 61 6e 20 74 77 6f 20 73 63 72 61 74 63 68  than two scratch
10d30 20 62 75 66 66 65 72 73 20 70 65 72 20 74 68 72   buffers per thr
10d40 65 61 64 2e 20 20 53 6f 0a 2a 2a 20 4e 20 73 68  ead.  So.** N sh
10d50 6f 75 6c 64 20 62 65 20 73 65 74 20 74 6f 20 74  ould be set to t
10d60 77 69 63 65 20 74 68 65 20 65 78 70 65 63 74 65  wice the expecte
10d70 64 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  d maximum number
10d80 20 6f 66 20 74 68 72 65 61 64 73 2e 0a 2a 2a 20   of threads..** 
10d90 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 6e 65 76  ^SQLite will nev
10da0 65 72 20 72 65 71 75 69 72 65 20 61 20 73 63 72  er require a scr
10db0 61 74 63 68 20 62 75 66 66 65 72 20 74 68 61 74  atch buffer that
10dc0 20 69 73 20 6d 6f 72 65 20 74 68 61 6e 20 36 0a   is more than 6.
10dd0 2a 2a 20 74 69 6d 65 73 20 74 68 65 20 64 61 74  ** times the dat
10de0 61 62 61 73 65 20 70 61 67 65 20 73 69 7a 65 2e  abase page size.
10df0 20 5e 49 66 20 53 51 4c 69 74 65 20 6e 65 65 64   ^If SQLite need
10e00 73 20 6e 65 65 64 73 20 61 64 64 69 74 69 6f 6e  s needs addition
10e10 61 6c 0a 2a 2a 20 73 63 72 61 74 63 68 20 6d 65  al.** scratch me
10e20 6d 6f 72 79 20 62 65 79 6f 6e 64 20 77 68 61 74  mory beyond what
10e30 20 69 73 20 70 72 6f 76 69 64 65 64 20 62 79 20   is provided by 
10e40 74 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74 69  this configurati
10e50 6f 6e 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20  on option, then 
10e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
10e70 6c 6f 63 28 29 5d 20 77 69 6c 6c 20 62 65 20 75  loc()] will be u
10e80 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 20 74 68  sed to obtain th
10e90 65 20 6d 65 6d 6f 72 79 20 6e 65 65 64 65 64 2e  e memory needed.
10ea0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
10eb0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45  LITE_CONFIG_PAGE
10ec0 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10ed0 54 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41  TE_CONFIG_PAGECA
10ee0 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  CHE</dt>.** <dd>
10ef0 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70   ^This option sp
10f00 65 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63  ecifies a static
10f10 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74   memory buffer t
10f20 68 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75  hat SQLite can u
10f30 73 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61  se for.** the da
10f40 74 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68  tabase page cach
10f50 65 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75  e with the defau
10f60 6c 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  lt page cache im
10f70 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20 0a  plementation.  .
10f80 2a 2a 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72  ** This configur
10f90 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74  ation should not
10fa0 20 62 65 20 75 73 65 64 20 69 66 20 61 6e 20 61   be used if an a
10fb0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
10fc0 65 20 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20  e page.** cache 
10fd0 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69  implementation i
10fe0 73 20 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74  s loaded using t
10ff0 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  he SQLITE_CONFIG
11000 5f 50 43 41 43 48 45 32 20 6f 70 74 69 6f 6e 2e  _PCACHE2 option.
11010 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 68  .** There are th
11020 72 65 65 20 61 72 67 75 6d 65 6e 74 73 20 74 6f  ree arguments to
11030 20 74 68 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20   this option: A 
11040 70 6f 69 6e 74 65 72 20 74 6f 20 38 2d 62 79 74  pointer to 8-byt
11050 65 20 61 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d  e aligned.** mem
11060 6f 72 79 2c 20 74 68 65 20 73 69 7a 65 20 6f 66  ory, the size of
11070 20 65 61 63 68 20 70 61 67 65 20 62 75 66 66 65   each page buffe
11080 72 20 28 73 7a 29 2c 20 61 6e 64 20 74 68 65 20  r (sz), and the 
11090 6e 75 6d 62 65 72 20 6f 66 20 70 61 67 65 73 20  number of pages 
110a0 28 4e 29 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61  (N)..** The sz a
110b0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62  rgument should b
110c0 65 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74 68  e the size of th
110d0 65 20 6c 61 72 67 65 73 74 20 64 61 74 61 62 61  e largest databa
110e0 73 65 20 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f  se page.** (a po
110f0 77 65 72 20 6f 66 20 74 77 6f 20 62 65 74 77 65  wer of two betwe
11100 65 6e 20 35 31 32 20 61 6e 64 20 33 32 37 36 38  en 512 and 32768
11110 29 20 70 6c 75 73 20 61 20 6c 69 74 74 6c 65 20  ) plus a little 
11120 65 78 74 72 61 20 66 6f 72 20 65 61 63 68 0a 2a  extra for each.*
11130 2a 20 70 61 67 65 20 68 65 61 64 65 72 2e 20 20  * page header.  
11140 5e 54 68 65 20 70 61 67 65 20 68 65 61 64 65 72  ^The page header
11150 20 73 69 7a 65 20 69 73 20 32 30 20 74 6f 20 34   size is 20 to 4
11160 30 20 62 79 74 65 73 20 64 65 70 65 6e 64 69 6e  0 bytes dependin
11170 67 20 6f 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74  g on.** the host
11180 20 61 72 63 68 69 74 65 63 74 75 72 65 2e 20 20   architecture.  
11190 5e 49 74 20 69 73 20 68 61 72 6d 6c 65 73 73 2c  ^It is harmless,
111a0 20 61 70 61 72 74 20 66 72 6f 6d 20 74 68 65 20   apart from the 
111b0 77 61 73 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a  wasted memory,.*
111c0 2a 20 74 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c  * to make sz a l
111d0 69 74 74 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e  ittle too large.
111e0 20 20 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 61    The first.** a
111f0 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70  rgument should p
11200 6f 69 6e 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63  oint to an alloc
11210 61 74 69 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73  ation of at leas
11220 74 20 73 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20  t sz*N bytes of 
11230 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69  memory..** ^SQLi
11240 74 65 20 77 69 6c 6c 20 75 73 65 20 74 68 65 20  te will use the 
11250 6d 65 6d 6f 72 79 20 70 72 6f 76 69 64 65 64 20  memory provided 
11260 62 79 20 74 68 65 20 66 69 72 73 74 20 61 72 67  by the first arg
11270 75 6d 65 6e 74 20 74 6f 20 73 61 74 69 73 66 79  ument to satisfy
11280 20 69 74 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e   its.** memory n
11290 65 65 64 73 20 66 6f 72 20 74 68 65 20 66 69 72  eeds for the fir
112a0 73 74 20 4e 20 70 61 67 65 73 20 74 68 61 74 20  st N pages that 
112b0 69 74 20 61 64 64 73 20 74 6f 20 63 61 63 68 65  it adds to cache
112c0 2e 20 20 5e 49 66 20 61 64 64 69 74 69 6f 6e 61  .  ^If additiona
112d0 6c 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65 20  l.** page cache 
112e0 6d 65 6d 6f 72 79 20 69 73 20 6e 65 65 64 65 64  memory is needed
112f0 20 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20   beyond what is 
11300 70 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73  provided by this
11310 20 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a   option, then.**
11320 20 53 51 4c 69 74 65 20 67 6f 65 73 20 74 6f 20   SQLite goes to 
11330 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
11340 29 5d 20 66 6f 72 20 74 68 65 20 61 64 64 69 74  )] for the addit
11350 69 6f 6e 61 6c 20 73 74 6f 72 61 67 65 20 73 70  ional storage sp
11360 61 63 65 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e  ace..** The poin
11370 74 65 72 20 69 6e 20 74 68 65 20 66 69 72 73 74  ter in the first
11380 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a   argument must.*
11390 2a 20 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20  * be aligned to 
113a0 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e 64 61  an 8-byte bounda
113b0 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e 74  ry or subsequent
113c0 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51 4c   behavior of SQL
113d0 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75  ite.** will be u
113e0 6e 64 65 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a  ndefined.</dd>.*
113f0 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f  *.** [[SQLITE_CO
11400 4e 46 49 47 5f 48 45 41 50 5d 5d 20 3c 64 74 3e  NFIG_HEAP]] <dt>
11410 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45  SQLITE_CONFIG_HE
11420 41 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  AP</dt>.** <dd> 
11430 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
11440 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
11450 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
11460 61 74 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  at SQLite will u
11470 73 65 0a 2a 2a 20 66 6f 72 20 61 6c 6c 20 6f 66  se.** for all of
11480 20 69 74 73 20 64 79 6e 61 6d 69 63 20 6d 65 6d   its dynamic mem
11490 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e  ory allocation n
114a0 65 65 64 73 20 62 65 79 6f 6e 64 20 74 68 6f 73  eeds beyond thos
114b0 65 20 70 72 6f 76 69 64 65 64 0a 2a 2a 20 66 6f  e provided.** fo
114c0 72 20 62 79 20 5b 53 51 4c 49 54 45 5f 43 4f 4e  r by [SQLITE_CON
114d0 46 49 47 5f 53 43 52 41 54 43 48 5d 20 61 6e 64  FIG_SCRATCH] and
114e0 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f   [SQLITE_CONFIG_
114f0 50 41 47 45 43 41 43 48 45 5d 2e 0a 2a 2a 20 54  PAGECACHE]..** T
11500 68 65 72 65 20 61 72 65 20 74 68 72 65 65 20 61  here are three a
11510 72 67 75 6d 65 6e 74 73 3a 20 41 6e 20 38 2d 62  rguments: An 8-b
11520 79 74 65 20 61 6c 69 67 6e 65 64 20 70 6f 69 6e  yte aligned poin
11530 74 65 72 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ter to the memor
11540 79 2c 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  y,.** the number
11550 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 65   of bytes in the
11560 20 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 2c 20   memory buffer, 
11570 61 6e 64 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  and the minimum 
11580 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 2e  allocation size.
11590 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 72 73  .** ^If the firs
115a0 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65 20 6d  t pointer (the m
115b0 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29 20 69  emory pointer) i
115c0 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 53 51 4c  s NULL, then SQL
115d0 69 74 65 20 72 65 76 65 72 74 73 0a 2a 2a 20 74  ite reverts.** t
115e0 6f 20 75 73 69 6e 67 20 69 74 73 20 64 65 66 61  o using its defa
115f0 75 6c 74 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ult memory alloc
11600 61 74 6f 72 20 28 74 68 65 20 73 79 73 74 65 6d  ator (the system
11610 20 6d 61 6c 6c 6f 63 28 29 20 69 6d 70 6c 65 6d   malloc() implem
11620 65 6e 74 61 74 69 6f 6e 29 2c 0a 2a 2a 20 75 6e  entation),.** un
11630 64 6f 69 6e 67 20 61 6e 79 20 70 72 69 6f 72 20  doing any prior 
11640 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 53  invocation of [S
11650 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c  QLITE_CONFIG_MAL
11660 4c 4f 43 5d 2e 20 20 5e 49 66 20 74 68 65 0a 2a  LOC].  ^If the.*
11670 2a 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72  * memory pointer
11680 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 61 6e 64   is not NULL and
11690 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
116a0 45 4e 41 42 4c 45 5f 4d 45 4d 53 59 53 33 5d 20  ENABLE_MEMSYS3] 
116b0 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  or.** [SQLITE_EN
116c0 41 42 4c 45 5f 4d 45 4d 53 59 53 35 5d 20 61 72  ABLE_MEMSYS5] ar
116d0 65 20 64 65 66 69 6e 65 64 2c 20 74 68 65 6e 20  e defined, then 
116e0 74 68 65 20 61 6c 74 65 72 6e 61 74 69 76 65 20  the alternative 
116f0 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61  memory.** alloca
11700 74 6f 72 20 69 73 20 65 6e 67 61 67 65 64 20 74  tor is engaged t
11710 6f 20 68 61 6e 64 6c 65 20 61 6c 6c 20 6f 66 20  o handle all of 
11720 53 51 4c 69 74 65 73 20 6d 65 6d 6f 72 79 20 61  SQLites memory a
11730 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
11740 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70 6f  .** The first po
11750 69 6e 74 65 72 20 28 74 68 65 20 6d 65 6d 6f 72  inter (the memor
11760 79 20 70 6f 69 6e 74 65 72 29 20 6d 75 73 74 20  y pointer) must 
11770 62 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e  be aligned to an
11780 20 38 2d 62 79 74 65 0a 2a 2a 20 62 6f 75 6e 64   8-byte.** bound
11790 61 72 79 20 6f 72 20 73 75 62 73 65 71 75 65 6e  ary or subsequen
117a0 74 20 62 65 68 61 76 69 6f 72 20 6f 66 20 53 51  t behavior of SQ
117b0 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 75 6e 64  Lite will be und
117c0 65 66 69 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 6d  efined..** The m
117d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
117e0 6e 20 73 69 7a 65 20 69 73 20 63 61 70 70 65 64  n size is capped
117f0 20 61 74 20 32 2a 2a 31 32 2e 20 52 65 61 73 6f   at 2**12. Reaso
11800 6e 61 62 6c 65 20 76 61 6c 75 65 73 0a 2a 2a 20  nable values.** 
11810 66 6f 72 20 74 68 65 20 6d 69 6e 69 6d 75 6d 20  for the minimum 
11820 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20  allocation size 
11830 61 72 65 20 32 2a 2a 35 20 74 68 72 6f 75 67 68  are 2**5 through
11840 20 32 2a 2a 38 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a   2**8.</dd>.**.*
11850 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11860 47 5f 4d 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51  G_MUTEX]] <dt>SQ
11870 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
11880 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
11890 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
118a0 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
118b0 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
118c0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
118d0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
118e0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
118f0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11900 72 65 2e 20 20 54 68 65 20 61 72 67 75 6d 65 6e  re.  The argumen
11910 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 61  t specifies.** a
11920 6c 74 65 72 6e 61 74 69 76 65 20 6c 6f 77 2d 6c  lternative low-l
11930 65 76 65 6c 20 6d 75 74 65 78 20 72 6f 75 74 69  evel mutex routi
11940 6e 65 73 20 74 6f 20 62 65 20 75 73 65 64 20 69  nes to be used i
11950 6e 20 70 6c 61 63 65 0a 2a 2a 20 74 68 65 20 6d  n place.** the m
11960 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 62 75  utex routines bu
11970 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 2e  ilt into SQLite.
11980 29 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65  )^  ^SQLite make
11990 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a  s a copy of the.
119a0 2a 2a 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  ** content of th
119b0 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  e [sqlite3_mutex
119c0 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
119d0 75 72 65 20 62 65 66 6f 72 65 20 74 68 65 20 63  ure before the c
119e0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
119f0 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 72 65 74  e3_config()] ret
11a00 75 72 6e 73 2e 20 5e 49 66 20 53 51 4c 69 74 65  urns. ^If SQLite
11a10 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74   is compiled wit
11a20 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c 49 54 45  h.** the [SQLITE
11a30 5f 54 48 52 45 41 44 53 41 46 45 20 7c 20 53 51  _THREADSAFE | SQ
11a40 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d  LITE_THREADSAFE=
11a50 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  0] compile-time 
11a60 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 74  option then.** t
11a70 68 65 20 65 6e 74 69 72 65 20 6d 75 74 65 78 69  he entire mutexi
11a80 6e 67 20 73 75 62 73 79 73 74 65 6d 20 69 73 20  ng subsystem is 
11a90 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65  omitted from the
11aa0 20 62 75 69 6c 64 20 61 6e 64 20 68 65 6e 63 65   build and hence
11ab0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
11ac0 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
11ad0 77 69 74 68 20 74 68 65 20 53 51 4c 49 54 45 5f  with the SQLITE_
11ae0 43 4f 4e 46 49 47 5f 4d 55 54 45 58 20 63 6f 6e  CONFIG_MUTEX con
11af0 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
11b00 6e 20 77 69 6c 6c 0a 2a 2a 20 72 65 74 75 72 6e  n will.** return
11b10 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 2e   [SQLITE_ERROR].
11b20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  </dd>.**.** [[SQ
11b30 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d  LITE_CONFIG_GETM
11b40 55 54 45 58 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  UTEX]] <dt>SQLIT
11b50 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
11b60 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
11b70 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
11b80 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
11b90 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
11ba0 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
11bb0 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
11bc0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
11bd0 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
11be0 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
11bf0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
11c00 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
11c10 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
11c20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
11c30 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
11c40 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
11c50 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
11c60 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
11c70 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
11c80 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
11c90 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
11ca0 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
11cb0 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
11cc0 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
11cd0 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
11ce0 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
11cf0 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
11d00 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
11d10 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
11d20 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
11d30 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
11d40 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
11d50 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
11d60 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
11d70 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
11d80 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
11d90 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
11da0 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
11db0 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
11dc0 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
11dd0 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
11de0 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
11df0 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
11e00 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
11e10 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
11e20 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
11e30 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 5d 20 3c 64  G_LOOKASIDE]] <d
11e40 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
11e50 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a  LOOKASIDE</dt>.*
11e60 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
11e70 74 69 6f 6e 20 74 61 6b 65 73 20 74 77 6f 20 61  tion takes two a
11e80 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 64 65  rguments that de
11e90 74 65 72 6d 69 6e 65 20 74 68 65 20 64 65 66 61  termine the defa
11ea0 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ult.** memory al
11eb0 6c 6f 63 61 74 69 6f 6e 20 66 6f 72 20 74 68 65  location for the
11ec0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11ed0 79 20 61 6c 6c 6f 63 61 74 6f 72 20 6f 6e 20 65  y allocator on e
11ee0 61 63 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65  ach.** [database
11ef0 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 54   connection].  T
11f00 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
11f10 74 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65  t is the.** size
11f20 20 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69   of each lookasi
11f30 64 65 20 62 75 66 66 65 72 20 73 6c 6f 74 20 61  de buffer slot a
11f40 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20 69 73  nd the second is
11f50 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
11f60 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f 63 61 74 65  * slots allocate
11f70 64 20 74 6f 20 65 61 63 68 20 64 61 74 61 62 61  d to each databa
11f80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 29 5e  se connection.)^
11f90 20 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20    ^(This option 
11fa0 73 65 74 73 20 74 68 65 0a 2a 2a 20 3c 69 3e 64  sets the.** <i>d
11fb0 65 66 61 75 6c 74 3c 2f 69 3e 20 6c 6f 6f 6b 61  efault</i> looka
11fc0 73 69 64 65 20 73 69 7a 65 2e 20 54 68 65 20 5b  side size. The [
11fd0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
11fe0 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a 2a 20 76 65  LOOKASIDE].** ve
11ff0 72 62 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64  rb to [sqlite3_d
12000 62 5f 63 6f 6e 66 69 67 28 29 5d 20 63 61 6e 20  b_config()] can 
12010 62 65 20 75 73 65 64 20 74 6f 20 63 68 61 6e 67  be used to chang
12020 65 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 0a  e the lookaside.
12030 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
12040 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20 63   on individual c
12050 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29 5e 20 3c 2f  onnections.)^ </
12060 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
12070 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12080 32 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  2]] <dt>SQLITE_C
12090 4f 4e 46 49 47 5f 50 43 41 43 48 45 32 3c 2f 64  ONFIG_PCACHE2</d
120a0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
120b0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
120c0 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
120d0 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
120e0 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20 5b 73 71  ter to.** an [sq
120f0 6c 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74  lite3_pcache_met
12100 68 6f 64 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20  hods2] object.  
12110 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70 65 63  This object spec
12120 69 66 69 65 73 20 74 68 65 20 69 6e 74 65 72 66  ifies the interf
12130 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75 73 74  ace.** to a cust
12140 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  om page cache im
12150 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29 5e 20  plementation.)^ 
12160 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61   ^SQLite makes a
12170 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20   copy of the.** 
12180 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65 73 20  object and uses 
12190 69 74 20 66 6f 72 20 70 61 67 65 20 63 61 63 68  it for page cach
121a0 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
121b0 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ions.</dd>.**.**
121c0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
121d0 5f 47 45 54 50 43 41 43 48 45 32 5d 5d 20 3c 64  _GETPCACHE2]] <d
121e0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
121f0 47 45 54 50 43 41 43 48 45 32 3c 2f 64 74 3e 0a  GETPCACHE2</dt>.
12200 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
12210 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
12220 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
12230 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
12240 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
12250 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
12260 73 32 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c  s2] object.  SQL
12270 69 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68  ite copies of th
12280 65 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67  e current.** pag
12290 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
122a0 74 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74  tation into that
122b0 20 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e   object.)^ </dd>
122c0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
122d0 43 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74  CONFIG_LOG]] <dt
122e0 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c  >SQLITE_CONFIG_L
122f0 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OG</dt>.** <dd> 
12300 5e 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  ^The SQLITE_CONF
12310 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61  IG_LOG option ta
12320 6b 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74  kes two argument
12330 73 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  s: a pointer to 
12340 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69  a.** function wi
12350 74 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74  th a call signat
12360 75 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76  ure of void(*)(v
12370 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63  oid*,int,const c
12380 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61  har*), .** and a
12390 20 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64   pointer to void
123a0 2e 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69  . ^If the functi
123b0 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f  on pointer is no
123c0 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a  t NULL, it is.**
123d0 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c   invoked by [sql
123e0 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70  ite3_log()] to p
123f0 72 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67  rocess each logg
12400 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20  ing event.  ^If 
12410 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  the.** function 
12420 70 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c  pointer is NULL,
12430 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f   the [sqlite3_lo
12440 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62  g()] interface b
12450 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a  ecomes a no-op..
12460 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69  ** ^The void poi
12470 6e 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65  nter that is the
12480 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
12490 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49   to SQLITE_CONFI
124a0 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73  G_LOG is.** pass
124b0 65 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68  ed through as th
124c0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
124d0 72 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61  r to the applica
124e0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67  tion-defined log
124f0 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ger.** function 
12500 77 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75  whenever that fu
12510 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65  nction is invoke
12520 64 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  d.  ^The second 
12530 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20  parameter to.** 
12540 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74  the logger funct
12550 69 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66  ion is a copy of
12560 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
12570 65 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72  eter to the corr
12580 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71  esponding.** [sq
12590 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c  lite3_log()] cal
125a0 6c 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65  l and is intende
125b0 64 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c  d to be a [resul
125c0 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a  t code] or an.**
125d0 20 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c   [extended resul
125e0 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74  t code].  ^The t
125f0 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70  hird parameter p
12600 61 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67  assed to the log
12610 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65  ger is.** log me
12620 73 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d  ssage after form
12630 61 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69  atting via [sqli
12640 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e  te3_snprintf()].
12650 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c  .** The SQLite l
12660 6f 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65  ogging interface
12670 20 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e   is not reentran
12680 74 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  t; the logger fu
12690 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69  nction.** suppli
126a0 65 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ed by the applic
126b0 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69  ation must not i
126c0 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65  nvoke any SQLite
126d0 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49   interface..** I
126e0 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  n a multi-thread
126f0 65 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20  ed application, 
12700 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d  the application-
12710 64 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a  defined logger.*
12720 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20  * function must 
12730 62 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c  be threadsafe. <
12740 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
12750 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d  ITE_CONFIG_URI]]
12760 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
12770 49 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54  IG_URI.** <dd> T
12780 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73  his option takes
12790 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65   a single argume
127a0 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20  nt of type int. 
127b0 49 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  If non-zero, the
127c0 6e 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e  n.** URI handlin
127d0 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e  g is globally en
127e0 61 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61  abled. If the pa
127f0 72 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c  rameter is zero,
12800 20 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69   then URI handli
12810 6e 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c  ng.** is globall
12820 79 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55  y disabled. If U
12830 52 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67  RI handling is g
12840 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c  lobally enabled,
12850 20 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a   all filenames.*
12860 2a 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c  * passed to [sql
12870 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73  ite3_open()], [s
12880 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
12890 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ], [sqlite3_open
128a0 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63  16()] or.** spec
128b0 69 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66  ified as part of
128c0 20 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e   [ATTACH] comman
128d0 64 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74  ds are interpret
128e0 65 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61  ed as URIs, rega
128f0 72 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65  rdless.** of whe
12900 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
12910 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49  [SQLITE_OPEN_URI
12920 5d 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68  ] flag is set wh
12930 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  en the database.
12940 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  ** connection is
12950 20 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69   opened. If it i
12960 73 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62  s globally disab
12970 6c 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61  led, filenames a
12980 72 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72  re.** only inter
12990 70 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69  preted as URIs i
129a0 66 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45  f the SQLITE_OPE
129b0 4e 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65  N_URI flag is se
129c0 74 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61  t when the.** da
129d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
129e0 6e 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20  n is opened. By 
129f0 64 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e  default, URI han
12a00 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c  dling is globall
12a10 79 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54  y.** disabled. T
12a20 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65  he default value
12a30 20 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20   may be changed 
12a40 62 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74  by compiling wit
12a50 68 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  h the.** [SQLITE
12a60 5f 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c  _USE_URI] symbol
12a70 20 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20   defined..**.** 
12a80 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  [[SQLITE_CONFIG_
12a90 50 43 41 43 48 45 5d 5d 20 5b 5b 53 51 4c 49 54  PCACHE]] [[SQLIT
12aa0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12ab0 48 45 5d 5d 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  HE]].** <dt>SQLI
12ac0 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
12ad0 20 61 6e 64 20 53 51 4c 49 54 45 5f 43 4f 4e 46   and SQLITE_CONF
12ae0 49 47 5f 47 45 54 50 43 41 43 48 45 0a 2a 2a 20  IG_GETPCACHE.** 
12af0 3c 64 64 3e 20 54 68 65 73 65 20 6f 70 74 69 6f  <dd> These optio
12b00 6e 73 20 61 72 65 20 6f 62 73 6f 6c 65 74 65 20  ns are obsolete 
12b10 61 6e 64 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  and should not b
12b20 65 20 75 73 65 64 20 62 79 20 6e 65 77 20 63 6f  e used by new co
12b30 64 65 2e 0a 2a 2a 20 54 68 65 79 20 61 72 65 20  de..** They are 
12b40 72 65 74 61 69 6e 65 64 20 66 6f 72 20 62 61 63  retained for bac
12b50 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69  kwards compatibi
12b60 6c 69 74 79 20 62 75 74 20 61 72 65 20 6e 6f 77  lity but are now
12b70 20 6e 6f 2d 6f 70 73 2e 0a 2a 2a 20 3c 2f 64 6c   no-ops..** </dl
12b80 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
12b90 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
12ba0 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
12bb0 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
12bc0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
12bd0 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
12be0 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
12bf0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
12c00 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
12c10 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
12c20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
12c30 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
12c40 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
12c50 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
12c60 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
12c70 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
12c80 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
12c90 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
12ca0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12cb0 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
12cc0 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
12cd0 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
12ce0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
12cf0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
12d00 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
12d10 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
12d20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12d30 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
12d40 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
12d50 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
12d60 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
12d70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
12d80 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
12d90 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
12da0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12db0 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
12dc0 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
12dd0 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
12de0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
12df0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
12e00 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
12e10 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
12e20 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
12e30 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
12e40 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
12e50 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
12e60 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
12e70 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12e80 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
12e90 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
12ea0 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12eb0 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
12ec0 34 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a 2f 0a 23  4  /* no-op */.#
12ed0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
12ee0 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
12ef0 20 20 31 35 20 20 2f 2a 20 6e 6f 2d 6f 70 20 2a    15  /* no-op *
12f00 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
12f10 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20 20 20  _CONFIG_LOG     
12f20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46 75 6e       16  /* xFun
12f30 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64 65 66  c, void* */.#def
12f40 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
12f50 47 5f 55 52 49 20 20 20 20 20 20 20 20 20 20 31  G_URI          1
12f60 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 23 64 65  7  /* int */.#de
12f70 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46  fine SQLITE_CONF
12f80 49 47 5f 50 43 41 43 48 45 32 20 20 20 20 20 20  IG_PCACHE2      
12f90 31 38 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70  18  /* sqlite3_p
12fa0 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 32 2a 20  cache_methods2* 
12fb0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
12fc0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43  E_CONFIG_GETPCAC
12fd0 48 45 32 20 20 20 31 39 20 20 2f 2a 20 73 71 6c  HE2   19  /* sql
12fe0 69 74 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68  ite3_pcache_meth
12ff0 6f 64 73 32 2a 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  ods2* */../*.** 
13000 43 41 50 49 33 52 45 46 3a 20 44 61 74 61 62 61  CAPI3REF: Databa
13010 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 20 43 6f  se Connection Co
13020 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74 69  nfiguration Opti
13030 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ons.**.** These 
13040 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74 68  constants are th
13050 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74 65  e available inte
13060 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ger configuratio
13070 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a 2a  n options that.*
13080 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64 20  * can be passed 
13090 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  as the second ar
130a0 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
130b0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
130c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
130d0 2a 0a 2a 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75  *.** New configu
130e0 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d  ration options m
130f0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
13100 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f  uture releases o
13110 66 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69  f SQLite..** Exi
13120 73 74 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74  sting configurat
13130 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68  ion options migh
13140 74 20 62 65 20 64 69 73 63 6f 6e 74 69 6e 75 65  t be discontinue
13150 64 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e 73  d.  Applications
13160 0a 2a 2a 20 73 68 6f 75 6c 64 20 63 68 65 63 6b  .** should check
13170 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64 65   the return code
13180 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 64   from [sqlite3_d
13190 62 5f 63 6f 6e 66 69 67 28 29 5d 20 74 6f 20 6d  b_config()] to m
131a0 61 6b 65 20 73 75 72 65 20 74 68 61 74 0a 2a 2a  ake sure that.**
131b0 20 74 68 65 20 63 61 6c 6c 20 77 6f 72 6b 65 64   the call worked
131c0 2e 20 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  .  ^The [sqlite3
131d0 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  _db_config()] in
131e0 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
131f0 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
13200 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
13210 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
13220 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
13230 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
13240 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
13250 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
13260 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
13270 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c  ONFIG_LOOKASIDE<
13280 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
13290 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
132a0 74 68 72 65 65 20 61 64 64 69 74 69 6f 6e 61 6c  three additional
132b0 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20   arguments that 
132c0 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20 0a 2a  determine the .*
132d0 2a 20 5b 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  * [lookaside mem
132e0 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 5d 20 63  ory allocator] c
132f0 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72  onfiguration for
13300 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
13310 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 0a 2a 2a 20 5e  onnection]..** ^
13320 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
13330 6e 74 20 28 74 68 65 20 74 68 69 72 64 20 70 61  nt (the third pa
13340 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
13350 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
13360 20 69 73 20 61 0a 2a 2a 20 70 6f 69 6e 74 65 72   is a.** pointer
13370 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20 62 75 66   to a memory buf
13380 66 65 72 20 74 6f 20 75 73 65 20 66 6f 72 20 6c  fer to use for l
13390 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72 79 2e  ookaside memory.
133a0 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
133b0 72 67 75 6d 65 6e 74 20 61 66 74 65 72 20 74 68  rgument after th
133c0 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
133d0 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 76 65 72 62  G_LOOKASIDE verb
133e0 0a 2a 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 20  .** may be NULL 
133f0 69 6e 20 77 68 69 63 68 20 63 61 73 65 20 53 51  in which case SQ
13400 4c 69 74 65 20 77 69 6c 6c 20 61 6c 6c 6f 63 61  Lite will alloca
13410 74 65 20 74 68 65 0a 2a 2a 20 6c 6f 6f 6b 61 73  te the.** lookas
13420 69 64 65 20 62 75 66 66 65 72 20 69 74 73 65 6c  ide buffer itsel
13430 66 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  f using [sqlite3
13440 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 5e 54 68 65  _malloc()]. ^The
13450 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74   second argument
13460 20 69 73 20 74 68 65 0a 2a 2a 20 73 69 7a 65 20   is the.** size 
13470 6f 66 20 65 61 63 68 20 6c 6f 6f 6b 61 73 69 64  of each lookasid
13480 65 20 62 75 66 66 65 72 20 73 6c 6f 74 2e 20 20  e buffer slot.  
13490 5e 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  ^The third argum
134a0 65 6e 74 20 69 73 20 74 68 65 20 6e 75 6d 62 65  ent is the numbe
134b0 72 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 2e 20 20  r of.** slots.  
134c0 54 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20  The size of the 
134d0 62 75 66 66 65 72 20 69 6e 20 74 68 65 20 66 69  buffer in the fi
134e0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73  rst argument mus
134f0 74 20 62 65 20 67 72 65 61 74 65 72 20 74 68 61  t be greater tha
13500 6e 0a 2a 2a 20 6f 72 20 65 71 75 61 6c 20 74 6f  n.** or equal to
13510 20 74 68 65 20 70 72 6f 64 75 63 74 20 6f 66 20   the product of 
13520 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
13530 68 69 72 64 20 61 72 67 75 6d 65 6e 74 73 2e 20  hird arguments. 
13540 20 54 68 65 20 62 75 66 66 65 72 0a 2a 2a 20 6d   The buffer.** m
13550 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64 20 74  ust be aligned t
13560 6f 20 61 6e 20 38 2d 62 79 74 65 20 62 6f 75 6e  o an 8-byte boun
13570 64 61 72 79 2e 20 20 5e 49 66 20 74 68 65 20 73  dary.  ^If the s
13580 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
13590 6f 0a 2a 2a 20 53 51 4c 49 54 45 5f 44 42 43 4f  o.** SQLITE_DBCO
135a0 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 69  NFIG_LOOKASIDE i
135b0 73 20 6e 6f 74 20 61 20 6d 75 6c 74 69 70 6c 65  s not a multiple
135c0 20 6f 66 20 38 2c 20 69 74 20 69 73 20 69 6e 74   of 8, it is int
135d0 65 72 6e 61 6c 6c 79 0a 2a 2a 20 72 6f 75 6e 64  ernally.** round
135e0 65 64 20 64 6f 77 6e 20 74 6f 20 74 68 65 20 6e  ed down to the n
135f0 65 78 74 20 73 6d 61 6c 6c 65 72 20 6d 75 6c 74  ext smaller mult
13600 69 70 6c 65 20 6f 66 20 38 2e 20 20 5e 28 54 68  iple of 8.  ^(Th
13610 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f  e lookaside memo
13620 72 79 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74  ry.** configurat
13630 69 6f 6e 20 66 6f 72 20 61 20 64 61 74 61 62 61  ion for a databa
13640 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 61  se connection ca
13650 6e 20 6f 6e 6c 79 20 62 65 20 63 68 61 6e 67 65  n only be change
13660 64 20 77 68 65 6e 20 74 68 61 74 0a 2a 2a 20 63  d when that.** c
13670 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6e 6f 74  onnection is not
13680 20 63 75 72 72 65 6e 74 6c 79 20 75 73 69 6e 67   currently using
13690 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
136a0 79 2c 20 6f 72 20 69 6e 20 6f 74 68 65 72 20 77  y, or in other w
136b0 6f 72 64 73 0a 2a 2a 20 77 68 65 6e 20 74 68 65  ords.** when the
136c0 20 22 63 75 72 72 65 6e 74 20 76 61 6c 75 65 22   "current value"
136d0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
136e0 5b 73 71 6c 69 74 65 33 5f 64 62 5f 73 74 61 74  [sqlite3_db_stat
136f0 75 73 5d 28 44 2c 5b 53 51 4c 49 54 45 5f 43 4f  us](D,[SQLITE_CO
13700 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 2c  NFIG_LOOKASIDE],
13710 2e 2e 2e 29 20 69 73 20 7a 65 72 6f 2e 0a 2a 2a  ...) is zero..**
13720 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f 20   Any attempt to 
13730 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
13740 73 69 64 65 20 6d 65 6d 6f 72 79 20 63 6f 6e 66  side memory conf
13750 69 67 75 72 61 74 69 6f 6e 20 77 68 65 6e 20 6c  iguration when l
13760 6f 6f 6b 61 73 69 64 65 0a 2a 2a 20 6d 65 6d 6f  ookaside.** memo
13770 72 79 20 69 73 20 69 6e 20 75 73 65 20 6c 65 61  ry is in use lea
13780 76 65 73 20 74 68 65 20 63 6f 6e 66 69 67 75 72  ves the configur
13790 61 74 69 6f 6e 20 75 6e 63 68 61 6e 67 65 64 20  ation unchanged 
137a0 61 6e 64 20 72 65 74 75 72 6e 73 20 0a 2a 2a 20  and returns .** 
137b0 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 2e 29 5e  [SQLITE_BUSY].)^
137c0 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
137d0 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
137e0 45 4e 41 42 4c 45 5f 46 4b 45 59 3c 2f 64 74 3e  ENABLE_FKEY</dt>
137f0 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f  .** <dd> ^This o
13800 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74 6f  ption is used to
13810 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61 62   enable or disab
13820 6c 65 20 74 68 65 20 65 6e 66 6f 72 63 65 6d 65  le the enforceme
13830 6e 74 20 6f 66 0a 2a 2a 20 5b 66 6f 72 65 69 67  nt of.** [foreig
13840 6e 20 6b 65 79 20 63 6f 6e 73 74 72 61 69 6e 74  n key constraint
13850 73 5d 2e 20 20 54 68 65 72 65 20 73 68 6f 75 6c  s].  There shoul
13860 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f  d be two additio
13870 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a  nal arguments..*
13880 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
13890 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67  ment is an integ
138a0 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f  er which is 0 to
138b0 20 64 69 73 61 62 6c 65 20 46 4b 20 65 6e 66 6f   disable FK enfo
138c0 72 63 65 6d 65 6e 74 2c 0a 2a 2a 20 70 6f 73 69  rcement,.** posi
138d0 74 69 76 65 20 74 6f 20 65 6e 61 62 6c 65 20 46  tive to enable F
138e0 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 72  K enforcement or
138f0 20 6e 65 67 61 74 69 76 65 20 74 6f 20 6c 65 61   negative to lea
13900 76 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  ve FK enforcemen
13910 74 0a 2a 2a 20 75 6e 63 68 61 6e 67 65 64 2e 20  t.** unchanged. 
13920 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   The second para
13930 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74  meter is a point
13940 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  er to an integer
13950 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69   into which.** i
13960 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31  s written 0 or 1
13970 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65   to indicate whe
13980 74 68 65 72 20 46 4b 20 65 6e 66 6f 72 63 65 6d  ther FK enforcem
13990 65 6e 74 20 69 73 20 6f 66 66 20 6f 72 20 6f 6e  ent is off or on
139a0 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  .** following th
139b0 69 73 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65  is call.  The se
139c0 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d  cond parameter m
139d0 61 79 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69  ay be a NULL poi
139e0 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63  nter, in.** whic
139f0 68 20 63 61 73 65 20 74 68 65 20 46 4b 20 65 6e  h case the FK en
13a00 66 6f 72 63 65 6d 65 6e 74 20 73 65 74 74 69 6e  forcement settin
13a10 67 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65  g is not reporte
13a20 64 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a  d back. </dd>.**
13a30 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
13a40 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 54  BCONFIG_ENABLE_T
13a50 52 49 47 47 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c  RIGGER</dt>.** <
13a60 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  dd> ^This option
13a70 20 69 73 20 75 73 65 64 20 74 6f 20 65 6e 61 62   is used to enab
13a80 6c 65 20 6f 72 20 64 69 73 61 62 6c 65 20 5b 43  le or disable [C
13a90 52 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20  REATE TRIGGER | 
13aa0 74 72 69 67 67 65 72 73 5d 2e 0a 2a 2a 20 54 68  triggers]..** Th
13ab0 65 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77  ere should be tw
13ac0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67  o additional arg
13ad0 75 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66  uments..** The f
13ae0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73  irst argument is
13af0 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63   an integer whic
13b00 68 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c  h is 0 to disabl
13b10 65 20 74 72 69 67 67 65 72 73 2c 0a 2a 2a 20 70  e triggers,.** p
13b20 6f 73 69 74 69 76 65 20 74 6f 20 65 6e 61 62 6c  ositive to enabl
13b30 65 20 74 72 69 67 67 65 72 73 20 6f 72 20 6e 65  e triggers or ne
13b40 67 61 74 69 76 65 20 74 6f 20 6c 65 61 76 65 20  gative to leave 
13b50 74 68 65 20 73 65 74 74 69 6e 67 20 75 6e 63 68  the setting unch
13b60 61 6e 67 65 64 2e 0a 2a 2a 20 54 68 65 20 73 65  anged..** The se
13b70 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69  cond parameter i
13b80 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
13b90 6e 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77  n integer into w
13ba0 68 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74  hich.** is writt
13bb0 65 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64  en 0 or 1 to ind
13bc0 69 63 61 74 65 20 77 68 65 74 68 65 72 20 74 72  icate whether tr
13bd0 69 67 67 65 72 73 20 61 72 65 20 64 69 73 61 62  iggers are disab
13be0 6c 65 64 20 6f 72 20 65 6e 61 62 6c 65 64 0a 2a  led or enabled.*
13bf0 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 69 73  * following this
13c00 20 63 61 6c 6c 2e 20 20 54 68 65 20 73 65 63 6f   call.  The seco
13c10 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  nd parameter may
13c20 20 62 65 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   be a NULL point
13c30 65 72 2c 20 69 6e 0a 2a 2a 20 77 68 69 63 68 20  er, in.** which 
13c40 63 61 73 65 20 74 68 65 20 74 72 69 67 67 65 72  case the trigger
13c50 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20   setting is not 
13c60 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c  reported back. <
13c70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 2f 64 6c 3e  /dd>.**.** </dl>
13c80 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
13c90 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
13ca0 41 53 49 44 45 20 20 20 20 20 20 20 31 30 30 31  ASIDE       1001
13cb0 20 20 2f 2a 20 76 6f 69 64 2a 20 69 6e 74 20 69    /* void* int i
13cc0 6e 74 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  nt */.#define SQ
13cd0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
13ce0 41 42 4c 45 5f 46 4b 45 59 20 20 20 20 20 31 30  ABLE_FKEY     10
13cf0 30 32 20 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20  02  /* int int* 
13d00 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
13d10 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c  E_DBCONFIG_ENABL
13d20 45 5f 54 52 49 47 47 45 52 20 20 31 30 30 33 20  E_TRIGGER  1003 
13d30 20 2f 2a 20 69 6e 74 20 69 6e 74 2a 20 2a 2f 0a   /* int int* */.
13d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
13d50 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69 73 61  : Enable Or Disa
13d60 62 6c 65 20 45 78 74 65 6e 64 65 64 20 52 65 73  ble Extended Res
13d70 75 6c 74 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20  ult Codes.**.** 
13d80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
13d90 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64  ended_result_cod
13da0 65 73 28 29 20 72 6f 75 74 69 6e 65 20 65 6e 61  es() routine ena
13db0 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73  bles or disables
13dc0 20 74 68 65 0a 2a 2a 20 5b 65 78 74 65 6e 64 65   the.** [extende
13dd0 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 20  d result codes] 
13de0 66 65 61 74 75 72 65 20 6f 66 20 53 51 4c 69 74  feature of SQLit
13df0 65 2e 20 5e 54 68 65 20 65 78 74 65 6e 64 65 64  e. ^The extended
13e00 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 64 65 73   result.** codes
13e10 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
13e20 20 64 65 66 61 75 6c 74 20 66 6f 72 20 68 69 73   default for his
13e30 74 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62  torical compatib
13e40 69 6c 69 74 79 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ility..*/.int sq
13e50 6c 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72  lite3_extended_r
13e60 65 73 75 6c 74 5f 63 6f 64 65 73 28 73 71 6c 69  esult_codes(sqli
13e70 74 65 33 2a 2c 20 69 6e 74 20 6f 6e 6f 66 66 29  te3*, int onoff)
13e80 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
13e90 46 3a 20 4c 61 73 74 20 49 6e 73 65 72 74 20 52  F: Last Insert R
13ea0 6f 77 69 64 0a 2a 2a 0a 2a 2a 20 5e 45 61 63 68  owid.**.** ^Each
13eb0 20 65 6e 74 72 79 20 69 6e 20 61 6e 20 53 51 4c   entry in an SQL
13ec0 69 74 65 20 74 61 62 6c 65 20 68 61 73 20 61 20  ite table has a 
13ed0 75 6e 69 71 75 65 20 36 34 2d 62 69 74 20 73 69  unique 64-bit si
13ee0 67 6e 65 64 0a 2a 2a 20 69 6e 74 65 67 65 72 20  gned.** integer 
13ef0 6b 65 79 20 63 61 6c 6c 65 64 20 74 68 65 20 5b  key called the [
13f00 52 4f 57 49 44 20 7c 20 22 72 6f 77 69 64 22 5d  ROWID | "rowid"]
13f10 2e 20 5e 54 68 65 20 72 6f 77 69 64 20 69 73 20  . ^The rowid is 
13f20 61 6c 77 61 79 73 20 61 76 61 69 6c 61 62 6c 65  always available
13f30 0a 2a 2a 20 61 73 20 61 6e 20 75 6e 64 65 63 6c  .** as an undecl
13f40 61 72 65 64 20 63 6f 6c 75 6d 6e 20 6e 61 6d 65  ared column name
13f50 64 20 52 4f 57 49 44 2c 20 4f 49 44 2c 20 6f 72  d ROWID, OID, or
13f60 20 5f 52 4f 57 49 44 5f 20 61 73 20 6c 6f 6e 67   _ROWID_ as long
13f70 20 61 73 20 74 68 6f 73 65 0a 2a 2a 20 6e 61 6d   as those.** nam
13f80 65 73 20 61 72 65 20 6e 6f 74 20 61 6c 73 6f 20  es are not also 
13f90 75 73 65 64 20 62 79 20 65 78 70 6c 69 63 69 74  used by explicit
13fa0 6c 79 20 64 65 63 6c 61 72 65 64 20 63 6f 6c 75  ly declared colu
13fb0 6d 6e 73 2e 20 5e 49 66 0a 2a 2a 20 74 68 65 20  mns. ^If.** the 
13fc0 74 61 62 6c 65 20 68 61 73 20 61 20 63 6f 6c 75  table has a colu
13fd0 6d 6e 20 6f 66 20 74 79 70 65 20 5b 49 4e 54 45  mn of type [INTE
13fe0 47 45 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d  GER PRIMARY KEY]
13ff0 20 74 68 65 6e 20 74 68 61 74 20 63 6f 6c 75 6d   then that colum
14000 6e 0a 2a 2a 20 69 73 20 61 6e 6f 74 68 65 72 20  n.** is another 
14010 61 6c 69 61 73 20 66 6f 72 20 74 68 65 20 72 6f  alias for the ro
14020 77 69 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  wid..**.** ^This
14030 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
14040 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20   the [rowid] of 
14050 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 0a  the most recent.
14060 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49  ** successful [I
14070 4e 53 45 52 54 5d 20 69 6e 74 6f 20 74 68 65 20  NSERT] into the 
14080 64 61 74 61 62 61 73 65 20 66 72 6f 6d 20 74 68  database from th
14090 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
140a0 65 63 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68  ection].** in th
140b0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
140c0 2e 20 20 5e 41 73 20 6f 66 20 53 51 4c 69 74 65  .  ^As of SQLite
140d0 20 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20   version 3.7.7, 
140e0 74 68 69 73 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  this routines.**
140f0 20 72 65 63 6f 72 64 73 20 74 68 65 20 6c 61 73   records the las
14100 74 20 69 6e 73 65 72 74 20 72 6f 77 69 64 20 6f  t insert rowid o
14110 66 20 62 6f 74 68 20 6f 72 64 69 6e 61 72 79 20  f both ordinary 
14120 74 61 62 6c 65 73 20 61 6e 64 20 5b 76 69 72 74  tables and [virt
14130 75 61 6c 20 74 61 62 6c 65 73 5d 2e 0a 2a 2a 20  ual tables]..** 
14140 5e 49 66 20 6e 6f 20 73 75 63 63 65 73 73 66 75  ^If no successfu
14150 6c 20 5b 49 4e 53 45 52 54 5d 73 0a 2a 2a 20 68  l [INSERT]s.** h
14160 61 76 65 20 65 76 65 72 20 6f 63 63 75 72 72 65  ave ever occurre
14170 64 20 6f 6e 20 74 68 61 74 20 64 61 74 61 62 61  d on that databa
14180 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 7a  se connection, z
14190 65 72 6f 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ero is returned.
141a0 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61 6e 20 5b  .**.** ^(If an [
141b0 49 4e 53 45 52 54 5d 20 6f 63 63 75 72 73 20 77  INSERT] occurs w
141c0 69 74 68 69 6e 20 61 20 74 72 69 67 67 65 72 20  ithin a trigger 
141d0 6f 72 20 77 69 74 68 69 6e 20 61 20 5b 76 69 72  or within a [vir
141e0 74 75 61 6c 20 74 61 62 6c 65 5d 0a 2a 2a 20 6d  tual table].** m
141f0 65 74 68 6f 64 2c 20 74 68 65 6e 20 74 68 69 73  ethod, then this
14200 20 72 6f 75 74 69 6e 65 20 77 69 6c 6c 20 72 65   routine will re
14210 74 75 72 6e 20 74 68 65 20 5b 72 6f 77 69 64 5d  turn the [rowid]
14220 20 6f 66 20 74 68 65 20 69 6e 73 65 72 74 65 64   of the inserted
14230 0a 2a 2a 20 72 6f 77 20 61 73 20 6c 6f 6e 67 20  .** row as long 
14240 61 73 20 74 68 65 20 74 72 69 67 67 65 72 20 6f  as the trigger o
14250 72 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20  r virtual table 
14260 6d 65 74 68 6f 64 20 69 73 20 72 75 6e 6e 69 6e  method is runnin
14270 67 2e 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74  g..** But once t
14280 68 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69  he trigger or vi
14290 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 65 74 68  rtual table meth
142a0 6f 64 20 65 6e 64 73 2c 20 74 68 65 20 76 61 6c  od ends, the val
142b0 75 65 20 72 65 74 75 72 6e 65 64 20 0a 2a 2a 20  ue returned .** 
142c0 62 79 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  by this routine 
142d0 72 65 76 65 72 74 73 20 74 6f 20 77 68 61 74 20  reverts to what 
142e0 69 74 20 77 61 73 20 62 65 66 6f 72 65 20 74 68  it was before th
142f0 65 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 72  e trigger or vir
14300 74 75 61 6c 0a 2a 2a 20 74 61 62 6c 65 20 6d 65  tual.** table me
14310 74 68 6f 64 20 62 65 67 61 6e 2e 29 5e 0a 2a 2a  thod began.)^.**
14320 0a 2a 2a 20 5e 41 6e 20 5b 49 4e 53 45 52 54 5d  .** ^An [INSERT]
14330 20 74 68 61 74 20 66 61 69 6c 73 20 64 75 65 20   that fails due 
14340 74 6f 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  to a constraint 
14350 76 69 6f 6c 61 74 69 6f 6e 20 69 73 20 6e 6f 74  violation is not
14360 20 61 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c   a.** successful
14370 20 5b 49 4e 53 45 52 54 5d 20 61 6e 64 20 64 6f   [INSERT] and do
14380 65 73 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68  es not change th
14390 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64  e value returned
143a0 20 62 79 20 74 68 69 73 0a 2a 2a 20 72 6f 75 74   by this.** rout
143b0 69 6e 65 2e 20 20 5e 54 68 75 73 20 49 4e 53 45  ine.  ^Thus INSE
143c0 52 54 20 4f 52 20 46 41 49 4c 2c 20 49 4e 53 45  RT OR FAIL, INSE
143d0 52 54 20 4f 52 20 49 47 4e 4f 52 45 2c 20 49 4e  RT OR IGNORE, IN
143e0 53 45 52 54 20 4f 52 20 52 4f 4c 4c 42 41 43 4b  SERT OR ROLLBACK
143f0 2c 0a 2a 2a 20 61 6e 64 20 49 4e 53 45 52 54 20  ,.** and INSERT 
14400 4f 52 20 41 42 4f 52 54 20 6d 61 6b 65 20 6e 6f  OR ABORT make no
14410 20 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 20   changes to the 
14420 72 65 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20  return value of 
14430 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  this.** routine 
14440 77 68 65 6e 20 74 68 65 69 72 20 69 6e 73 65 72  when their inser
14450 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20 5e 28 57  tion fails.  ^(W
14460 68 65 6e 20 49 4e 53 45 52 54 20 4f 52 20 52 45  hen INSERT OR RE
14470 50 4c 41 43 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74  PLACE.** encount
14480 65 72 73 20 61 20 63 6f 6e 73 74 72 61 69 6e 74  ers a constraint
14490 20 76 69 6f 6c 61 74 69 6f 6e 2c 20 69 74 20 64   violation, it d
144a0 6f 65 73 20 6e 6f 74 20 66 61 69 6c 2e 20 20 54  oes not fail.  T
144b0 68 65 0a 2a 2a 20 49 4e 53 45 52 54 20 63 6f 6e  he.** INSERT con
144c0 74 69 6e 75 65 73 20 74 6f 20 63 6f 6d 70 6c 65  tinues to comple
144d0 74 69 6f 6e 20 61 66 74 65 72 20 64 65 6c 65 74  tion after delet
144e0 69 6e 67 20 72 6f 77 73 20 74 68 61 74 20 63 61  ing rows that ca
144f0 75 73 65 64 0a 2a 2a 20 74 68 65 20 63 6f 6e 73  used.** the cons
14500 74 72 61 69 6e 74 20 70 72 6f 62 6c 65 6d 20 73  traint problem s
14510 6f 20 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c  o INSERT OR REPL
14520 41 43 45 20 77 69 6c 6c 20 61 6c 77 61 79 73 20  ACE will always 
14530 63 68 61 6e 67 65 0a 2a 2a 20 74 68 65 20 72 65  change.** the re
14540 74 75 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68  turn value of th
14550 69 73 20 69 6e 74 65 72 66 61 63 65 2e 29 5e 0a  is interface.)^.
14560 2a 2a 0a 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70  **.** ^For the p
14570 75 72 70 6f 73 65 73 20 6f 66 20 74 68 69 73 20  urposes of this 
14580 72 6f 75 74 69 6e 65 2c 20 61 6e 20 5b 49 4e 53  routine, an [INS
14590 45 52 54 5d 20 69 73 20 63 6f 6e 73 69 64 65 72  ERT] is consider
145a0 65 64 20 74 6f 0a 2a 2a 20 62 65 20 73 75 63 63  ed to.** be succ
145b0 65 73 73 66 75 6c 20 65 76 65 6e 20 69 66 20 69  essful even if i
145c0 74 20 69 73 20 73 75 62 73 65 71 75 65 6e 74 6c  t is subsequentl
145d0 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a  y rolled back..*
145e0 2a 0a 2a 2a 20 54 68 69 73 20 66 75 6e 63 74 69  *.** This functi
145f0 6f 6e 20 69 73 20 61 63 63 65 73 73 69 62 6c 65  on is accessible
14600 20 74 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   to SQL statemen
14610 74 73 20 76 69 61 20 74 68 65 0a 2a 2a 20 5b 6c  ts via the.** [l
14620 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64  ast_insert_rowid
14630 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 5d  () SQL function]
14640 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73 65 70  ..**.** If a sep
14650 61 72 61 74 65 20 74 68 72 65 61 64 20 70 65 72  arate thread per
14660 66 6f 72 6d 73 20 61 20 6e 65 77 20 5b 49 4e 53  forms a new [INS
14670 45 52 54 5d 20 6f 6e 20 74 68 65 20 73 61 6d 65  ERT] on the same
14680 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e  .** database con
14690 6e 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68  nection while th
146a0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f  e [sqlite3_last_
146b0 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 5d 0a  insert_rowid()].
146c0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72  ** function is r
146d0 75 6e 6e 69 6e 67 20 61 6e 64 20 74 68 75 73 20  unning and thus 
146e0 63 68 61 6e 67 65 73 20 74 68 65 20 6c 61 73 74  changes the last
146f0 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2c   insert [rowid],
14700 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 76 61 6c  .** then the val
14710 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20 5b  ue returned by [
14720 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
14730 65 72 74 5f 72 6f 77 69 64 28 29 5d 20 69 73 0a  ert_rowid()] is.
14740 2a 2a 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65  ** unpredictable
14750 20 61 6e 64 20 6d 69 67 68 74 20 6e 6f 74 20 65   and might not e
14760 71 75 61 6c 20 65 69 74 68 65 72 20 74 68 65 20  qual either the 
14770 6f 6c 64 20 6f 72 20 74 68 65 20 6e 65 77 0a 2a  old or the new.*
14780 2a 20 6c 61 73 74 20 69 6e 73 65 72 74 20 5b 72  * last insert [r
14790 6f 77 69 64 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65  owid]..*/.sqlite
147a0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
147b0 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
147c0 64 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  d(sqlite3*);../*
147d0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
147e0 75 6e 74 20 54 68 65 20 4e 75 6d 62 65 72 20 4f  unt The Number O
147f0 66 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a  f Rows Modified.
14800 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63  **.** ^This func
14810 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65  tion returns the
14820 20 6e 75 6d 62 65 72 20 6f 66 20 64 61 74 61 62   number of datab
14830 61 73 65 20 72 6f 77 73 20 74 68 61 74 20 77 65  ase rows that we
14840 72 65 20 63 68 61 6e 67 65 64 0a 2a 2a 20 6f 72  re changed.** or
14850 20 69 6e 73 65 72 74 65 64 20 6f 72 20 64 65 6c   inserted or del
14860 65 74 65 64 20 62 79 20 74 68 65 20 6d 6f 73 74  eted by the most
14870 20 72 65 63 65 6e 74 6c 79 20 63 6f 6d 70 6c 65   recently comple
14880 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ted SQL statemen
14890 74 0a 2a 2a 20 6f 6e 20 74 68 65 20 5b 64 61 74  t.** on the [dat
148a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
148b0 5d 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74  ] specified by t
148c0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
148d0 65 72 2e 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68  er..** ^(Only ch
148e0 61 6e 67 65 73 20 74 68 61 74 20 61 72 65 20 64  anges that are d
148f0 69 72 65 63 74 6c 79 20 73 70 65 63 69 66 69 65  irectly specifie
14900 64 20 62 79 20 74 68 65 20 5b 49 4e 53 45 52 54  d by the [INSERT
14910 5d 2c 20 5b 55 50 44 41 54 45 5d 2c 0a 2a 2a 20  ], [UPDATE],.** 
14920 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74  or [DELETE] stat
14930 65 6d 65 6e 74 20 61 72 65 20 63 6f 75 6e 74 65  ement are counte
14940 64 2e 20 20 41 75 78 69 6c 69 61 72 79 20 63 68  d.  Auxiliary ch
14950 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 0a  anges caused by.
14960 2a 2a 20 74 72 69 67 67 65 72 73 20 6f 72 20 5b  ** triggers or [
14970 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69  foreign key acti
14980 6f 6e 73 5d 20 61 72 65 20 6e 6f 74 20 63 6f 75  ons] are not cou
14990 6e 74 65 64 2e 29 5e 20 55 73 65 20 74 68 65 0a  nted.)^ Use the.
149a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  ** [sqlite3_tota
149b0 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 66 75 6e  l_changes()] fun
149c0 63 74 69 6f 6e 20 74 6f 20 66 69 6e 64 20 74 68  ction to find th
149d0 65 20 74 6f 74 61 6c 20 6e 75 6d 62 65 72 20 6f  e total number o
149e0 66 20 63 68 61 6e 67 65 73 0a 2a 2a 20 69 6e 63  f changes.** inc
149f0 6c 75 64 69 6e 67 20 63 68 61 6e 67 65 73 20 63  luding changes c
14a00 61 75 73 65 64 20 62 79 20 74 72 69 67 67 65 72  aused by trigger
14a10 73 20 61 6e 64 20 66 6f 72 65 69 67 6e 20 6b 65  s and foreign ke
14a20 79 20 61 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  y actions..**.**
14a30 20 5e 43 68 61 6e 67 65 73 20 74 6f 20 61 20 76   ^Changes to a v
14a40 69 65 77 20 74 68 61 74 20 61 72 65 20 73 69 6d  iew that are sim
14a50 75 6c 61 74 65 64 20 62 79 20 61 6e 20 5b 49 4e  ulated by an [IN
14a60 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65 72  STEAD OF trigger
14a70 5d 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 63 6f 75  ].** are not cou
14a80 6e 74 65 64 2e 20 20 4f 6e 6c 79 20 72 65 61 6c  nted.  Only real
14a90 20 74 61 62 6c 65 20 63 68 61 6e 67 65 73 20 61   table changes a
14aa0 72 65 20 63 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a  re counted..**.*
14ab0 2a 20 5e 28 41 20 22 72 6f 77 20 63 68 61 6e 67  * ^(A "row chang
14ac0 65 22 20 69 73 20 61 20 63 68 61 6e 67 65 20 74  e" is a change t
14ad0 6f 20 61 20 73 69 6e 67 6c 65 20 72 6f 77 20 6f  o a single row o
14ae0 66 20 61 20 73 69 6e 67 6c 65 20 74 61 62 6c 65  f a single table
14af0 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 61 6e  .** caused by an
14b00 20 49 4e 53 45 52 54 2c 20 44 45 4c 45 54 45 2c   INSERT, DELETE,
14b10 20 6f 72 20 55 50 44 41 54 45 20 73 74 61 74 65   or UPDATE state
14b20 6d 65 6e 74 2e 20 20 52 6f 77 73 20 74 68 61 74  ment.  Rows that
14b30 0a 2a 2a 20 61 72 65 20 63 68 61 6e 67 65 64 20  .** are changed 
14b40 61 73 20 73 69 64 65 20 65 66 66 65 63 74 73 20  as side effects 
14b50 6f 66 20 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e  of [REPLACE] con
14b60 73 74 72 61 69 6e 74 20 72 65 73 6f 6c 75 74 69  straint resoluti
14b70 6f 6e 2c 0a 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c  on,.** rollback,
14b80 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69 6e   ABORT processin
14b90 67 2c 20 5b 44 52 4f 50 20 54 41 42 4c 45 5d 2c  g, [DROP TABLE],
14ba0 20 6f 72 20 62 79 20 61 6e 79 20 6f 74 68 65 72   or by any other
14bb0 0a 2a 2a 20 6d 65 63 68 61 6e 69 73 6d 73 20 64  .** mechanisms d
14bc0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 64  o not count as d
14bd0 69 72 65 63 74 20 72 6f 77 20 63 68 61 6e 67 65  irect row change
14be0 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72  s.)^.**.** A "tr
14bf0 69 67 67 65 72 20 63 6f 6e 74 65 78 74 22 20 69  igger context" i
14c00 73 20 61 20 73 63 6f 70 65 20 6f 66 20 65 78 65  s a scope of exe
14c10 63 75 74 69 6f 6e 20 74 68 61 74 20 62 65 67 69  cution that begi
14c20 6e 73 20 61 6e 64 0a 2a 2a 20 65 6e 64 73 20 77  ns and.** ends w
14c30 69 74 68 20 74 68 65 20 73 63 72 69 70 74 20 6f  ith the script o
14c40 66 20 61 20 5b 43 52 45 41 54 45 20 54 52 49 47  f a [CREATE TRIG
14c50 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 2e 20  GER | trigger]. 
14c60 0a 2a 2a 20 4d 6f 73 74 20 53 51 4c 20 73 74 61  .** Most SQL sta
14c70 74 65 6d 65 6e 74 73 20 61 72 65 0a 2a 2a 20 65  tements are.** e
14c80 76 61 6c 75 61 74 65 64 20 6f 75 74 73 69 64 65  valuated outside
14c90 20 6f 66 20 61 6e 79 20 74 72 69 67 67 65 72 2e   of any trigger.
14ca0 20 20 54 68 69 73 20 69 73 20 74 68 65 20 22 74    This is the "t
14cb0 6f 70 20 6c 65 76 65 6c 22 0a 2a 2a 20 74 72 69  op level".** tri
14cc0 67 67 65 72 20 63 6f 6e 74 65 78 74 2e 20 20 49  gger context.  I
14cd0 66 20 61 20 74 72 69 67 67 65 72 20 66 69 72 65  f a trigger fire
14ce0 73 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  s from the top l
14cf0 65 76 65 6c 2c 20 61 0a 2a 2a 20 6e 65 77 20 74  evel, a.** new t
14d00 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 20 69  rigger context i
14d10 73 20 65 6e 74 65 72 65 64 20 66 6f 72 20 74 68  s entered for th
14d20 65 20 64 75 72 61 74 69 6f 6e 20 6f 66 20 74 68  e duration of th
14d30 61 74 20 6f 6e 65 0a 2a 2a 20 74 72 69 67 67 65  at one.** trigge
14d40 72 2e 20 20 53 75 62 74 72 69 67 67 65 72 73 20  r.  Subtriggers 
14d50 63 72 65 61 74 65 20 73 75 62 63 6f 6e 74 65 78  create subcontex
14d60 74 73 20 66 6f 72 20 74 68 65 69 72 20 64 75 72  ts for their dur
14d70 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61  ation..**.** ^Ca
14d80 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 65  lling [sqlite3_e
14d90 78 65 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  xec()] or [sqlit
14da0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 63 75 72  e3_step()] recur
14db0 73 69 76 65 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e  sively does.** n
14dc0 6f 74 20 63 72 65 61 74 65 20 61 20 6e 65 77 20  ot create a new 
14dd0 74 72 69 67 67 65 72 20 63 6f 6e 74 65 78 74 2e  trigger context.
14de0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e  .**.** ^This fun
14df0 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68  ction returns th
14e00 65 20 6e 75 6d 62 65 72 20 6f 66 20 64 69 72 65  e number of dire
14e10 63 74 20 72 6f 77 20 63 68 61 6e 67 65 73 20 69  ct row changes i
14e20 6e 20 74 68 65 0a 2a 2a 20 6d 6f 73 74 20 72 65  n the.** most re
14e30 63 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44  cent INSERT, UPD
14e40 41 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 20 73  ATE, or DELETE s
14e50 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20  tatement within 
14e60 74 68 65 20 73 61 6d 65 0a 2a 2a 20 74 72 69 67  the same.** trig
14e70 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
14e80 2a 2a 20 5e 54 68 75 73 2c 20 77 68 65 6e 20 63  ** ^Thus, when c
14e90 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 74  alled from the t
14ea0 6f 70 20 6c 65 76 65 6c 2c 20 74 68 69 73 20 66  op level, this f
14eb0 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
14ec0 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66  the.** number of
14ed0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
14ee0 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53 45  most recent INSE
14ef0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
14f00 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20 61 6c  ELETE.** that al
14f10 73 6f 20 6f 63 63 75 72 72 65 64 20 61 74 20 74  so occurred at t
14f20 68 65 20 74 6f 70 20 6c 65 76 65 6c 2e 20 20 5e  he top level.  ^
14f30 28 57 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79  (Within the body
14f40 20 6f 66 20 61 20 74 72 69 67 67 65 72 2c 0a 2a   of a trigger,.*
14f50 2a 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63 68  * the sqlite3_ch
14f60 61 6e 67 65 73 28 29 20 69 6e 74 65 72 66 61 63  anges() interfac
14f70 65 20 63 61 6e 20 62 65 20 63 61 6c 6c 65 64 20  e can be called 
14f80 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d 62  to find the numb
14f90 65 72 20 6f 66 0a 2a 2a 20 63 68 61 6e 67 65 73  er of.** changes
14fa0 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
14fb0 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
14fc0 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20  INSERT, UPDATE, 
14fd0 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 73 74 61  or DELETE.** sta
14fe0 74 65 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68  tement within th
14ff0 65 20 62 6f 64 79 20 6f 66 20 74 68 65 20 73 61  e body of the sa
15000 6d 65 20 74 72 69 67 67 65 72 2e 0a 2a 2a 20 48  me trigger..** H
15010 6f 77 65 76 65 72 2c 20 74 68 65 20 6e 75 6d 62  owever, the numb
15020 65 72 20 72 65 74 75 72 6e 65 64 20 64 6f 65 73  er returned does
15030 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68 61   not include cha
15040 6e 67 65 73 0a 2a 2a 20 63 61 75 73 65 64 20 62  nges.** caused b
15050 79 20 73 75 62 74 72 69 67 67 65 72 73 20 73 69  y subtriggers si
15060 6e 63 65 20 74 68 6f 73 65 20 68 61 76 65 20 74  nce those have t
15070 68 65 69 72 20 6f 77 6e 20 63 6f 6e 74 65 78 74  heir own context
15080 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  .)^.**.** See al
15090 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  so the [sqlite3_
150a0 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d  total_changes()]
150b0 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65 0a   interface, the.
150c0 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67 65  ** [count_change
150d0 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20 74  s pragma], and t
150e0 68 65 20 5b 63 68 61 6e 67 65 73 28 29 20 53 51  he [changes() SQ
150f0 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a  L function]..**.
15100 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65  ** If a separate
15110 20 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68   thread makes ch
15120 61 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d  anges on the sam
15130 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
15140 63 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b  ction.** while [
15150 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28  sqlite3_changes(
15160 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74 68  )] is running th
15170 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72 65 74  en the value ret
15180 75 72 6e 65 64 0a 2a 2a 20 69 73 20 75 6e 70 72  urned.** is unpr
15190 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f  edictable and no
151a0 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f  t meaningful..*/
151b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 68 61  .int sqlite3_cha
151c0 6e 67 65 73 28 73 71 6c 69 74 65 33 2a 29 3b 0a  nges(sqlite3*);.
151d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
151e0 20 54 6f 74 61 6c 20 4e 75 6d 62 65 72 20 4f 66   Total Number Of
151f0 20 52 6f 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a   Rows Modified.*
15200 2a 0a 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74  *.** ^This funct
15210 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  ion returns the 
15220 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77 20 63 68  number of row ch
15230 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79 20  anges caused by 
15240 5b 49 4e 53 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50  [INSERT],.** [UP
15250 44 41 54 45 5d 20 6f 72 20 5b 44 45 4c 45 54 45  DATE] or [DELETE
15260 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 73 69 6e  ] statements sin
15270 63 65 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  ce the [database
15280 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 61 73   connection] was
15290 20 6f 70 65 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68   opened..** ^(Th
152a0 65 20 63 6f 75 6e 74 20 72 65 74 75 72 6e 65 64  e count returned
152b0 20 62 79 20 73 71 6c 69 74 65 33 5f 74 6f 74 61   by sqlite3_tota
152c0 6c 5f 63 68 61 6e 67 65 73 28 29 20 69 6e 63 6c  l_changes() incl
152d0 75 64 65 73 20 61 6c 6c 20 63 68 61 6e 67 65 73  udes all changes
152e0 0a 2a 2a 20 66 72 6f 6d 20 61 6c 6c 20 5b 43 52  .** from all [CR
152f0 45 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74  EATE TRIGGER | t
15300 72 69 67 67 65 72 5d 20 63 6f 6e 74 65 78 74 73  rigger] contexts
15310 20 61 6e 64 20 63 68 61 6e 67 65 73 20 6d 61 64   and changes mad
15320 65 20 62 79 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e  e by.** [foreign
15330 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d 2e 20 48   key actions]. H
15340 6f 77 65 76 65 72 2c 0a 2a 2a 20 74 68 65 20 63  owever,.** the c
15350 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e  ount does not in
15360 63 6c 75 64 65 20 63 68 61 6e 67 65 73 20 75 73  clude changes us
15370 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
15380 5b 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72  [REPLACE] constr
15390 61 69 6e 74 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c  aints,.** do rol
153a0 6c 62 61 63 6b 73 20 6f 72 20 41 42 4f 52 54 20  lbacks or ABORT 
153b0 70 72 6f 63 65 73 73 69 6e 67 2c 20 6f 72 20 5b  processing, or [
153c0 44 52 4f 50 20 54 41 42 4c 45 5d 20 70 72 6f 63  DROP TABLE] proc
153d0 65 73 73 69 6e 67 2e 20 20 54 68 65 0a 2a 2a 20  essing.  The.** 
153e0 63 6f 75 6e 74 20 64 6f 65 73 20 6e 6f 74 20 69  count does not i
153f0 6e 63 6c 75 64 65 20 72 6f 77 73 20 6f 66 20 76  nclude rows of v
15400 69 65 77 73 20 74 68 61 74 20 66 69 72 65 20 61  iews that fire a
15410 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46 20 74 72  n [INSTEAD OF tr
15420 69 67 67 65 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67  igger],.** thoug
15430 68 20 69 66 20 74 68 65 20 49 4e 53 54 45 41 44  h if the INSTEAD
15440 20 4f 46 20 74 72 69 67 67 65 72 20 6d 61 6b 65   OF trigger make
15450 73 20 63 68 61 6e 67 65 73 20 6f 66 20 69 74 73  s changes of its
15460 20 6f 77 6e 2c 20 74 68 6f 73 65 20 63 68 61 6e   own, those chan
15470 67 65 73 20 0a 2a 2a 20 61 72 65 20 63 6f 75 6e  ges .** are coun
15480 74 65 64 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 73  ted.)^.** ^The s
15490 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
154a0 6e 67 65 73 28 29 20 66 75 6e 63 74 69 6f 6e 20  nges() function 
154b0 63 6f 75 6e 74 73 20 74 68 65 20 63 68 61 6e 67  counts the chang
154c0 65 73 20 61 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a  es as soon as.**
154d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
154e0 68 61 74 20 6d 61 6b 65 73 20 74 68 65 6d 20 69  hat makes them i
154f0 73 20 63 6f 6d 70 6c 65 74 65 64 20 28 77 68 65  s completed (whe
15500 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
15510 68 61 6e 64 6c 65 0a 2a 2a 20 69 73 20 70 61 73  handle.** is pas
15520 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  sed to [sqlite3_
15530 72 65 73 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c  reset()] or [sql
15540 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
15550 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
15560 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63  o the [sqlite3_c
15570 68 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66  hanges()] interf
15580 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75  ace, the.** [cou
15590 6e 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d  nt_changes pragm
155a0 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b 74 6f 74  a], and the [tot
155b0 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 53 51 4c  al_changes() SQL
155c0 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a   function]..**.*
155d0 2a 20 49 66 20 61 20 73 65 70 61 72 61 74 65 20  * If a separate 
155e0 74 68 72 65 61 64 20 6d 61 6b 65 73 20 63 68 61  thread makes cha
155f0 6e 67 65 73 20 6f 6e 20 74 68 65 20 73 61 6d 65  nges on the same
15600 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
15610 74 69 6f 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73  tion.** while [s
15620 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61  qlite3_total_cha
15630 6e 67 65 73 28 29 5d 20 69 73 20 72 75 6e 6e 69  nges()] is runni
15640 6e 67 20 74 68 65 6e 20 74 68 65 20 76 61 6c 75  ng then the valu
15650 65 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 73  e.** returned is
15660 20 75 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61   unpredictable a
15670 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e 67 66 75  nd not meaningfu
15680 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  l..*/.int sqlite
15690 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28  3_total_changes(
156a0 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a  sqlite3*);../*.*
156b0 2a 20 43 41 50 49 33 52 45 46 3a 20 49 6e 74 65  * CAPI3REF: Inte
156c0 72 72 75 70 74 20 41 20 4c 6f 6e 67 2d 52 75 6e  rrupt A Long-Run
156d0 6e 69 6e 67 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a  ning Query.**.**
156e0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
156f0 63 61 75 73 65 73 20 61 6e 79 20 70 65 6e 64 69  causes any pendi
15700 6e 67 20 64 61 74 61 62 61 73 65 20 6f 70 65 72  ng database oper
15710 61 74 69 6f 6e 20 74 6f 20 61 62 6f 72 74 20 61  ation to abort a
15720 6e 64 0a 2a 2a 20 72 65 74 75 72 6e 20 61 74 20  nd.** return at 
15730 69 74 73 20 65 61 72 6c 69 65 73 74 20 6f 70 70  its earliest opp
15740 6f 72 74 75 6e 69 74 79 2e 20 54 68 69 73 20 72  ortunity. This r
15750 6f 75 74 69 6e 65 20 69 73 20 74 79 70 69 63 61  outine is typica
15760 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 69 6e  lly.** called in
15770 20 72 65 73 70 6f 6e 73 65 20 74 6f 20 61 20 75   response to a u
15780 73 65 72 20 61 63 74 69 6f 6e 20 73 75 63 68 20  ser action such 
15790 61 73 20 70 72 65 73 73 69 6e 67 20 22 43 61 6e  as pressing "Can
157a0 63 65 6c 22 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d  cel".** or Ctrl-
157b0 43 20 77 68 65 72 65 20 74 68 65 20 75 73 65 72  C where the user
157c0 20 77 61 6e 74 73 20 61 20 6c 6f 6e 67 20 71 75   wants a long qu
157d0 65 72 79 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ery operation to
157e0 20 68 61 6c 74 0a 2a 2a 20 69 6d 6d 65 64 69 61   halt.** immedia
157f0 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20  tely..**.** ^It 
15800 69 73 20 73 61 66 65 20 74 6f 20 63 61 6c 6c 20  is safe to call 
15810 74 68 69 73 20 72 6f 75 74 69 6e 65 20 66 72 6f  this routine fro
15820 6d 20 61 20 74 68 72 65 61 64 20 64 69 66 66 65  m a thread diffe
15830 72 65 6e 74 20 66 72 6f 6d 20 74 68 65 0a 2a 2a  rent from the.**
15840 20 74 68 72 65 61 64 20 74 68 61 74 20 69 73 20   thread that is 
15850 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e  currently runnin
15860 67 20 74 68 65 20 64 61 74 61 62 61 73 65 20 6f  g the database o
15870 70 65 72 61 74 69 6f 6e 2e 20 20 42 75 74 20 69  peration.  But i
15880 74 0a 2a 2a 20 69 73 20 6e 6f 74 20 73 61 66 65  t.** is not safe
15890 20 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f   to call this ro
158a0 75 74 69 6e 65 20 77 69 74 68 20 61 20 5b 64 61  utine with a [da
158b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
158c0 6e 5d 20 74 68 61 74 0a 2a 2a 20 69 73 20 63 6c  n] that.** is cl
158d0 6f 73 65 64 20 6f 72 20 6d 69 67 68 74 20 63 6c  osed or might cl
158e0 6f 73 65 20 62 65 66 6f 72 65 20 73 71 6c 69 74  ose before sqlit
158f0 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 72  e3_interrupt() r
15900 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49  eturns..**.** ^I
15910 66 20 61 6e 20 53 51 4c 20 6f 70 65 72 61 74 69  f an SQL operati
15920 6f 6e 20 69 73 20 76 65 72 79 20 6e 65 61 72 6c  on is very nearl
15930 79 20 66 69 6e 69 73 68 65 64 20 61 74 20 74 68  y finished at th
15940 65 20 74 69 6d 65 20 77 68 65 6e 0a 2a 2a 20 73  e time when.** s
15950 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
15960 28 29 20 69 73 20 63 61 6c 6c 65 64 2c 20 74 68  () is called, th
15970 65 6e 20 69 74 20 6d 69 67 68 74 20 6e 6f 74 20  en it might not 
15980 68 61 76 65 20 61 6e 20 6f 70 70 6f 72 74 75 6e  have an opportun
15990 69 74 79 0a 2a 2a 20 74 6f 20 62 65 20 69 6e 74  ity.** to be int
159a0 65 72 72 75 70 74 65 64 20 61 6e 64 20 6d 69 67  errupted and mig
159b0 68 74 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20 63  ht continue to c
159c0 6f 6d 70 6c 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  ompletion..**.**
159d0 20 5e 41 6e 20 53 51 4c 20 6f 70 65 72 61 74 69   ^An SQL operati
159e0 6f 6e 20 74 68 61 74 20 69 73 20 69 6e 74 65 72  on that is inter
159f0 72 75 70 74 65 64 20 77 69 6c 6c 20 72 65 74 75  rupted will retu
15a00 72 6e 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52  rn [SQLITE_INTER
15a10 52 55 50 54 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68  RUPT]..** ^If th
15a20 65 20 69 6e 74 65 72 72 75 70 74 65 64 20 53 51  e interrupted SQ
15a30 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61  L operation is a
15a40 6e 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45  n INSERT, UPDATE
15a50 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a 20 74  , or DELETE.** t
15a60 68 61 74 20 69 73 20 69 6e 73 69 64 65 20 61 6e  hat is inside an
15a70 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
15a80 63 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20  ction, then the 
15a90 65 6e 74 69 72 65 20 74 72 61 6e 73 61 63 74 69  entire transacti
15aa0 6f 6e 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 72 6f  on.** will be ro
15ab0 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
15ac0 74 69 63 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  tically..**.** ^
15ad0 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65  The sqlite3_inte
15ae0 72 72 75 70 74 28 44 29 20 63 61 6c 6c 20 69 73  rrupt(D) call is
15af0 20 69 6e 20 65 66 66 65 63 74 20 75 6e 74 69 6c   in effect until
15b00 20 61 6c 6c 20 63 75 72 72 65 6e 74 6c 79 20 72   all currently r
15b10 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74  unning.** SQL st
15b20 61 74 65 6d 65 6e 74 73 20 6f 6e 20 5b 64 61 74  atements on [dat
15b30 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15b40 5d 20 44 20 63 6f 6d 70 6c 65 74 65 2e 20 20 5e  ] D complete.  ^
15b50 41 6e 79 20 6e 65 77 20 53 51 4c 20 73 74 61 74  Any new SQL stat
15b60 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61  ements.** that a
15b70 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65 72  re started after
15b80 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
15b90 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20 61 6e  errupt() call an
15ba0 64 20 62 65 66 6f 72 65 20 74 68 65 20 0a 2a 2a  d before the .**
15bb0 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d 65   running stateme
15bc0 6e 74 73 20 72 65 61 63 68 65 73 20 7a 65 72 6f  nts reaches zero
15bd0 20 61 72 65 20 69 6e 74 65 72 72 75 70 74 65 64   are interrupted
15be0 20 61 73 20 69 66 20 74 68 65 79 20 68 61 64 20   as if they had 
15bf0 62 65 65 6e 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20  been.** running 
15c00 70 72 69 6f 72 20 74 6f 20 74 68 65 20 73 71 6c  prior to the sql
15c10 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
15c20 20 63 61 6c 6c 2e 20 20 5e 4e 65 77 20 53 51 4c   call.  ^New SQL
15c30 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74   statements.** t
15c40 68 61 74 20 61 72 65 20 73 74 61 72 74 65 64 20  hat are started 
15c50 61 66 74 65 72 20 74 68 65 20 72 75 6e 6e 69 6e  after the runnin
15c60 67 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 75 6e  g statement coun
15c70 74 20 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61  t reaches zero a
15c80 72 65 0a 2a 2a 20 6e 6f 74 20 65 66 66 65 63 74  re.** not effect
15c90 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74 65  ed by the sqlite
15ca0 33 5f 69 6e 74 65 72 72 75 70 74 28 29 2e 0a 2a  3_interrupt()..*
15cb0 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 73 71 6c  * ^A call to sql
15cc0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44  ite3_interrupt(D
15cd0 29 20 74 68 61 74 20 6f 63 63 75 72 73 20 77 68  ) that occurs wh
15ce0 65 6e 20 74 68 65 72 65 20 61 72 65 20 6e 6f 20  en there are no 
15cf0 72 75 6e 6e 69 6e 67 0a 2a 2a 20 53 51 4c 20 73  running.** SQL s
15d00 74 61 74 65 6d 65 6e 74 73 20 69 73 20 61 20 6e  tatements is a n
15d10 6f 2d 6f 70 20 61 6e 64 20 68 61 73 20 6e 6f 20  o-op and has no 
15d20 65 66 66 65 63 74 20 6f 6e 20 53 51 4c 20 73 74  effect on SQL st
15d30 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74  atements.** that
15d40 20 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74   are started aft
15d50 65 72 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69  er the sqlite3_i
15d60 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c 6c 20  nterrupt() call 
15d70 72 65 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49  returns..**.** I
15d80 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  f the database c
15d90 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73  onnection closes
15da0 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
15db0 69 6e 74 65 72 72 75 70 74 28 29 5d 0a 2a 2a 20  interrupt()].** 
15dc0 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
15dd0 62 61 64 20 74 68 69 6e 67 73 20 77 69 6c 6c 20  bad things will 
15de0 6c 69 6b 65 6c 79 20 68 61 70 70 65 6e 2e 0a 2a  likely happen..*
15df0 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 69  /.void sqlite3_i
15e00 6e 74 65 72 72 75 70 74 28 73 71 6c 69 74 65 33  nterrupt(sqlite3
15e10 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
15e20 52 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49  REF: Determine I
15e30 66 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65  f An SQL Stateme
15e40 6e 74 20 49 73 20 43 6f 6d 70 6c 65 74 65 0a 2a  nt Is Complete.*
15e50 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
15e60 6e 65 73 20 61 72 65 20 75 73 65 66 75 6c 20 64  nes are useful d
15e70 75 72 69 6e 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69  uring command-li
15e80 6e 65 20 69 6e 70 75 74 20 74 6f 20 64 65 74 65  ne input to dete
15e90 72 6d 69 6e 65 20 69 66 20 74 68 65 0a 2a 2a 20  rmine if the.** 
15ea0 63 75 72 72 65 6e 74 6c 79 20 65 6e 74 65 72 65  currently entere
15eb0 64 20 74 65 78 74 20 73 65 65 6d 73 20 74 6f 20  d text seems to 
15ec0 66 6f 72 6d 20 61 20 63 6f 6d 70 6c 65 74 65 20  form a complete 
15ed0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 6f 72  SQL statement or
15ee0 0a 2a 2a 20 69 66 20 61 64 64 69 74 69 6f 6e 61  .** if additiona
15ef0 6c 20 69 6e 70 75 74 20 69 73 20 6e 65 65 64 65  l input is neede
15f00 64 20 62 65 66 6f 72 65 20 73 65 6e 64 69 6e 67  d before sending
15f10 20 74 68 65 20 74 65 78 74 20 69 6e 74 6f 0a 2a   the text into.*
15f20 2a 20 53 51 4c 69 74 65 20 66 6f 72 20 70 61 72  * SQLite for par
15f30 73 69 6e 67 2e 20 20 5e 54 68 65 73 65 20 72 6f  sing.  ^These ro
15f40 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 31 20  utines return 1 
15f50 69 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  if the input str
15f60 69 6e 67 0a 2a 2a 20 61 70 70 65 61 72 73 20 74  ing.** appears t
15f70 6f 20 62 65 20 61 20 63 6f 6d 70 6c 65 74 65 20  o be a complete 
15f80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  SQL statement.  
15f90 5e 41 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  ^A statement is 
15fa0 6a 75 64 67 65 64 20 74 6f 20 62 65 0a 2a 2a 20  judged to be.** 
15fb0 63 6f 6d 70 6c 65 74 65 20 69 66 20 69 74 20 65  complete if it e
15fc0 6e 64 73 20 77 69 74 68 20 61 20 73 65 6d 69 63  nds with a semic
15fd0 6f 6c 6f 6e 20 74 6f 6b 65 6e 20 61 6e 64 20 69  olon token and i
15fe0 73 20 6e 6f 74 20 61 20 70 72 65 66 69 78 20 6f  s not a prefix o
15ff0 66 20 61 0a 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d  f a.** well-form
16000 65 64 20 43 52 45 41 54 45 20 54 52 49 47 47 45  ed CREATE TRIGGE
16010 52 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 53  R statement.  ^S
16020 65 6d 69 63 6f 6c 6f 6e 73 20 74 68 61 74 20 61  emicolons that a
16030 72 65 20 65 6d 62 65 64 64 65 64 20 77 69 74 68  re embedded with
16040 69 6e 0a 2a 2a 20 73 74 72 69 6e 67 20 6c 69 74  in.** string lit
16050 65 72 61 6c 73 20 6f 72 20 71 75 6f 74 65 64 20  erals or quoted 
16060 69 64 65 6e 74 69 66 69 65 72 20 6e 61 6d 65 73  identifier names
16070 20 6f 72 20 63 6f 6d 6d 65 6e 74 73 20 61 72 65   or comments are
16080 20 6e 6f 74 0a 2a 2a 20 69 6e 64 65 70 65 6e 64   not.** independ
16090 65 6e 74 20 74 6f 6b 65 6e 73 20 28 74 68 65 79  ent tokens (they
160a0 20 61 72 65 20 70 61 72 74 20 6f 66 20 74 68 65   are part of the
160b0 20 74 6f 6b 65 6e 20 69 6e 20 77 68 69 63 68 20   token in which 
160c0 74 68 65 79 20 61 72 65 0a 2a 2a 20 65 6d 62 65  they are.** embe
160d0 64 64 65 64 29 20 61 6e 64 20 74 68 75 73 20 64  dded) and thus d
160e0 6f 20 6e 6f 74 20 63 6f 75 6e 74 20 61 73 20 61  o not count as a
160f0 20 73 74 61 74 65 6d 65 6e 74 20 74 65 72 6d 69   statement termi
16100 6e 61 74 6f 72 2e 20 20 5e 57 68 69 74 65 73 70  nator.  ^Whitesp
16110 61 63 65 0a 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65  ace.** and comme
16120 6e 74 73 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  nts that follow 
16130 74 68 65 20 66 69 6e 61 6c 20 73 65 6d 69 63 6f  the final semico
16140 6c 6f 6e 20 61 72 65 20 69 67 6e 6f 72 65 64 2e  lon are ignored.
16150 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
16160 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 30 20  utines return 0 
16170 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74  if the statement
16180 20 69 73 20 69 6e 63 6f 6d 70 6c 65 74 65 2e 20   is incomplete. 
16190 20 5e 49 66 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79   ^If a.** memory
161a0 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c   allocation fail
161b0 73 2c 20 74 68 65 6e 20 53 51 4c 49 54 45 5f 4e  s, then SQLITE_N
161c0 4f 4d 45 4d 20 69 73 20 72 65 74 75 72 6e 65 64  OMEM is returned
161d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
161e0 6f 75 74 69 6e 65 73 20 64 6f 20 6e 6f 74 20 70  outines do not p
161f0 61 72 73 65 20 74 68 65 20 53 51 4c 20 73 74 61  arse the SQL sta
16200 74 65 6d 65 6e 74 73 20 74 68 75 73 0a 2a 2a 20  tements thus.** 
16210 77 69 6c 6c 20 6e 6f 74 20 64 65 74 65 63 74 20  will not detect 
16220 73 79 6e 74 61 63 74 69 63 61 6c 6c 79 20 69 6e  syntactically in
16230 63 6f 72 72 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a  correct SQL..**.
16240 2a 2a 20 5e 28 49 66 20 53 51 4c 69 74 65 20 68  ** ^(If SQLite h
16250 61 73 20 6e 6f 74 20 62 65 65 6e 20 69 6e 69 74  as not been init
16260 69 61 6c 69 7a 65 64 20 75 73 69 6e 67 20 5b 73  ialized using [s
16270 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
16280 65 28 29 5d 20 70 72 69 6f 72 20 0a 2a 2a 20 74  e()] prior .** t
16290 6f 20 69 6e 76 6f 6b 69 6e 67 20 73 71 6c 69 74  o invoking sqlit
162a0 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 20  e3_complete16() 
162b0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 69 6e 69  then sqlite3_ini
162c0 74 69 61 6c 69 7a 65 28 29 20 69 73 20 69 6e 76  tialize() is inv
162d0 6f 6b 65 64 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  oked.** automati
162e0 63 61 6c 6c 79 20 62 79 20 73 71 6c 69 74 65 33  cally by sqlite3
162f0 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29 2e 20 20  _complete16().  
16300 49 66 20 74 68 61 74 20 69 6e 69 74 69 61 6c 69  If that initiali
16310 7a 61 74 69 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a  zation fails,.**
16320 20 74 68 65 6e 20 74 68 65 20 72 65 74 75 72 6e   then the return
16330 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c 69   value from sqli
16340 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 29  te3_complete16()
16350 20 77 69 6c 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72   will be non-zer
16360 6f 0a 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20  o.** regardless 
16370 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f  of whether or no
16380 74 20 74 68 65 20 69 6e 70 75 74 20 53 51 4c 20  t the input SQL 
16390 69 73 20 63 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a  is complete.)^.*
163a0 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74  *.** The input t
163b0 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  o [sqlite3_compl
163c0 65 74 65 28 29 5d 20 6d 75 73 74 20 62 65 20 61  ete()] must be a
163d0 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
163e0 0a 2a 2a 20 55 54 46 2d 38 20 73 74 72 69 6e 67  .** UTF-8 string
163f0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 70 75  ..**.** The inpu
16400 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f  t to [sqlite3_co
16410 6d 70 6c 65 74 65 31 36 28 29 5d 20 6d 75 73 74  mplete16()] must
16420 20 62 65 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69   be a zero-termi
16430 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20  nated.** UTF-16 
16440 73 74 72 69 6e 67 20 69 6e 20 6e 61 74 69 76 65  string in native
16450 20 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a   byte order..*/.
16460 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  int sqlite3_comp
16470 6c 65 74 65 28 63 6f 6e 73 74 20 63 68 61 72 20  lete(const char 
16480 2a 73 71 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  *sql);.int sqlit
16490 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36 28 63 6f  e3_complete16(co
164a0 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 29 3b 0a  nst void *sql);.
164b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
164c0 20 52 65 67 69 73 74 65 72 20 41 20 43 61 6c 6c   Register A Call
164d0 62 61 63 6b 20 54 6f 20 48 61 6e 64 6c 65 20 53  back To Handle S
164e0 51 4c 49 54 45 5f 42 55 53 59 20 45 72 72 6f 72  QLITE_BUSY Error
164f0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f  s.**.** ^This ro
16500 75 74 69 6e 65 20 73 65 74 73 20 61 20 63 61 6c  utine sets a cal
16510 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 74  lback function t
16520 68 61 74 20 6d 69 67 68 74 20 62 65 20 69 6e 76  hat might be inv
16530 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 0a 2a 2a  oked whenever.**
16540 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 20 6d   an attempt is m
16550 61 64 65 20 74 6f 20 6f 70 65 6e 20 61 20 64 61  ade to open a da
16560 74 61 62 61 73 65 20 74 61 62 6c 65 20 74 68 61  tabase table tha
16570 74 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61 64  t another thread
16580 0a 2a 2a 20 6f 72 20 70 72 6f 63 65 73 73 20 68  .** or process h
16590 61 73 20 6c 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a  as locked..**.**
165a0 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
165b0 6c 6c 62 61 63 6b 20 69 73 20 4e 55 4c 4c 2c 20  llback is NULL, 
165c0 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  then [SQLITE_BUS
165d0 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f  Y] or [SQLITE_IO
165e0 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20  ERR_BLOCKED].** 
165f0 69 73 20 72 65 74 75 72 6e 65 64 20 69 6d 6d 65  is returned imme
16600 64 69 61 74 65 6c 79 20 75 70 6f 6e 20 65 6e 63  diately upon enc
16610 6f 75 6e 74 65 72 69 6e 67 20 74 68 65 20 6c 6f  ountering the lo
16620 63 6b 2e 20 20 5e 49 66 20 74 68 65 20 62 75 73  ck.  ^If the bus
16630 79 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73  y callback.** is
16640 20 6e 6f 74 20 4e 55 4c 4c 2c 20 74 68 65 6e 20   not NULL, then 
16650 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6d 69 67  the callback mig
16660 68 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 69  ht be invoked wi
16670 74 68 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  th two arguments
16680 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
16690 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
166a0 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  he busy handler 
166b0 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65  is a copy of the
166c0 20 76 6f 69 64 2a 20 70 6f 69 6e 74 65 72 20 77   void* pointer w
166d0 68 69 63 68 0a 2a 2a 20 69 73 20 74 68 65 20 74  hich.** is the t
166e0 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  hird argument to
166f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
16700 6e 64 6c 65 72 28 29 2e 20 20 5e 54 68 65 20 73  ndler().  ^The s
16710 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
16720 6f 0a 2a 2a 20 74 68 65 20 62 75 73 79 20 68 61  o.** the busy ha
16730 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  ndler callback i
16740 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
16750 74 69 6d 65 73 20 74 68 61 74 20 74 68 65 20 62  times that the b
16760 75 73 79 20 68 61 6e 64 6c 65 72 20 68 61 73 0a  usy handler has.
16770 2a 2a 20 62 65 65 6e 20 69 6e 76 6f 6b 65 64 20  ** been invoked 
16780 66 6f 72 20 74 68 69 73 20 6c 6f 63 6b 69 6e 67  for this locking
16790 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74 68 65   event.  ^If the
167a0 0a 2a 2a 20 62 75 73 79 20 63 61 6c 6c 62 61 63  .** busy callbac
167b0 6b 20 72 65 74 75 72 6e 73 20 30 2c 20 74 68 65  k returns 0, the
167c0 6e 20 6e 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20  n no additional 
167d0 61 74 74 65 6d 70 74 73 20 61 72 65 20 6d 61 64  attempts are mad
167e0 65 20 74 6f 0a 2a 2a 20 61 63 63 65 73 73 20 74  e to.** access t
167f0 68 65 20 64 61 74 61 62 61 73 65 20 61 6e 64 20  he database and 
16800 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72  [SQLITE_BUSY] or
16810 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
16820 4c 4f 43 4b 45 44 5d 20 69 73 20 72 65 74 75 72  LOCKED] is retur
16830 6e 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ned..** ^If the 
16840 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
16850 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20   non-zero, then 
16860 61 6e 6f 74 68 65 72 20 61 74 74 65 6d 70 74 0a  another attempt.
16870 2a 2a 20 69 73 20 6d 61 64 65 20 74 6f 20 6f 70  ** is made to op
16880 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
16890 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
168a0 74 68 65 20 63 79 63 6c 65 20 72 65 70 65 61 74  the cycle repeat
168b0 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 65  s..**.** The pre
168c0 73 65 6e 63 65 20 6f 66 20 61 20 62 75 73 79 20  sence of a busy 
168d0 68 61 6e 64 6c 65 72 20 64 6f 65 73 20 6e 6f 74  handler does not
168e0 20 67 75 61 72 61 6e 74 65 65 20 74 68 61 74 20   guarantee that 
168f0 69 74 20 77 69 6c 6c 20 62 65 20 69 6e 76 6f 6b  it will be invok
16900 65 64 0a 2a 2a 20 77 68 65 6e 20 74 68 65 72 65  ed.** when there
16910 20 69 73 20 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74   is lock content
16920 69 6f 6e 2e 20 5e 49 66 20 53 51 4c 69 74 65 20  ion. ^If SQLite 
16930 64 65 74 65 72 6d 69 6e 65 73 20 74 68 61 74 20  determines that 
16940 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20 62 75 73  invoking the bus
16950 79 0a 2a 2a 20 68 61 6e 64 6c 65 72 20 63 6f 75  y.** handler cou
16960 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 20 64  ld result in a d
16970 65 61 64 6c 6f 63 6b 2c 20 69 74 20 77 69 6c 6c  eadlock, it will
16980 20 67 6f 20 61 68 65 61 64 20 61 6e 64 20 72 65   go ahead and re
16990 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  turn [SQLITE_BUS
169a0 59 5d 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45  Y].** or [SQLITE
169b0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
169c0 69 6e 73 74 65 61 64 20 6f 66 20 69 6e 76 6f 6b  instead of invok
169d0 69 6e 67 20 74 68 65 20 62 75 73 79 20 68 61 6e  ing the busy han
169e0 64 6c 65 72 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65  dler..** Conside
169f0 72 20 61 20 73 63 65 6e 61 72 69 6f 20 77 68 65  r a scenario whe
16a00 72 65 20 6f 6e 65 20 70 72 6f 63 65 73 73 20 69  re one process i
16a10 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65 61 64  s holding a read
16a20 20 6c 6f 63 6b 20 74 68 61 74 0a 2a 2a 20 69 74   lock that.** it
16a30 20 69 73 20 74 72 79 69 6e 67 20 74 6f 20 70 72   is trying to pr
16a40 6f 6d 6f 74 65 20 74 6f 20 61 20 72 65 73 65 72  omote to a reser
16a50 76 65 64 20 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20  ved lock and.** 
16a60 61 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73 73  a second process
16a70 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 72 65   is holding a re
16a80 73 65 72 76 65 64 20 6c 6f 63 6b 20 74 68 61 74  served lock that
16a90 20 69 74 20 69 73 20 74 72 79 69 6e 67 0a 2a 2a   it is trying.**
16aa0 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f 20 61   to promote to a
16ab0 6e 20 65 78 63 6c 75 73 69 76 65 20 6c 6f 63 6b  n exclusive lock
16ac0 2e 20 20 54 68 65 20 66 69 72 73 74 20 70 72 6f  .  The first pro
16ad0 63 65 73 73 20 63 61 6e 6e 6f 74 20 70 72 6f 63  cess cannot proc
16ae0 65 65 64 0a 2a 2a 20 62 65 63 61 75 73 65 20 69  eed.** because i
16af0 74 20 69 73 20 62 6c 6f 63 6b 65 64 20 62 79 20  t is blocked by 
16b00 74 68 65 20 73 65 63 6f 6e 64 20 61 6e 64 20 74  the second and t
16b10 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
16b20 73 20 63 61 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63  s cannot.** proc
16b30 65 65 64 20 62 65 63 61 75 73 65 20 69 74 20 69  eed because it i
16b40 73 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65  s blocked by the
16b50 20 66 69 72 73 74 2e 20 20 49 66 20 62 6f 74 68   first.  If both
16b60 20 70 72 6f 63 65 73 73 65 73 0a 2a 2a 20 69 6e   processes.** in
16b70 76 6f 6b 65 20 74 68 65 20 62 75 73 79 20 68 61  voke the busy ha
16b80 6e 64 6c 65 72 73 2c 20 6e 65 69 74 68 65 72 20  ndlers, neither 
16b90 77 69 6c 6c 20 6d 61 6b 65 20 61 6e 79 20 70 72  will make any pr
16ba0 6f 67 72 65 73 73 2e 20 20 54 68 65 72 65 66 6f  ogress.  Therefo
16bb0 72 65 2c 0a 2a 2a 20 53 51 4c 69 74 65 20 72 65  re,.** SQLite re
16bc0 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 42 55  turns [SQLITE_BU
16bd0 53 59 5d 20 66 6f 72 20 74 68 65 20 66 69 72 73  SY] for the firs
16be0 74 20 70 72 6f 63 65 73 73 2c 20 68 6f 70 69 6e  t process, hopin
16bf0 67 20 74 68 61 74 20 74 68 69 73 0a 2a 2a 20 77  g that this.** w
16c00 69 6c 6c 20 69 6e 64 75 63 65 20 74 68 65 20 66  ill induce the f
16c10 69 72 73 74 20 70 72 6f 63 65 73 73 20 74 6f 20  irst process to 
16c20 72 65 6c 65 61 73 65 20 69 74 73 20 72 65 61 64  release its read
16c30 20 6c 6f 63 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a   lock and allow.
16c40 2a 2a 20 74 68 65 20 73 65 63 6f 6e 64 20 70 72  ** the second pr
16c50 6f 63 65 73 73 20 74 6f 20 70 72 6f 63 65 65 64  ocess to proceed
16c60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65 66  ..**.** ^The def
16c70 61 75 6c 74 20 62 75 73 79 20 63 61 6c 6c 62 61  ault busy callba
16c80 63 6b 20 69 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ck is NULL..**.*
16c90 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 42  * ^The [SQLITE_B
16ca0 55 53 59 5d 20 65 72 72 6f 72 20 69 73 20 63 6f  USY] error is co
16cb0 6e 76 65 72 74 65 64 20 74 6f 20 5b 53 51 4c 49  nverted to [SQLI
16cc0 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44  TE_IOERR_BLOCKED
16cd0 5d 0a 2a 2a 20 77 68 65 6e 20 53 51 4c 69 74 65  ].** when SQLite
16ce0 20 69 73 20 69 6e 20 74 68 65 20 6d 69 64 64 6c   is in the middl
16cf0 65 20 6f 66 20 61 20 6c 61 72 67 65 20 74 72 61  e of a large tra
16d00 6e 73 61 63 74 69 6f 6e 20 77 68 65 72 65 20 61  nsaction where a
16d10 6c 6c 20 74 68 65 0a 2a 2a 20 63 68 61 6e 67 65  ll the.** change
16d20 73 20 77 69 6c 6c 20 6e 6f 74 20 66 69 74 20 69  s will not fit i
16d30 6e 74 6f 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  nto the in-memor
16d40 79 20 63 61 63 68 65 2e 20 20 53 51 4c 69 74 65  y cache.  SQLite
16d50 20 77 69 6c 6c 0a 2a 2a 20 61 6c 72 65 61 64 79   will.** already
16d60 20 68 6f 6c 64 20 61 20 52 45 53 45 52 56 45 44   hold a RESERVED
16d70 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 64 61 74   lock on the dat
16d80 61 62 61 73 65 20 66 69 6c 65 2c 20 62 75 74 20  abase file, but 
16d90 69 74 20 6e 65 65 64 73 0a 2a 2a 20 74 6f 20 70  it needs.** to p
16da0 72 6f 6d 6f 74 65 20 74 68 69 73 20 6c 6f 63 6b  romote this lock
16db0 20 74 6f 20 45 58 43 4c 55 53 49 56 45 20 73 6f   to EXCLUSIVE so
16dc0 20 74 68 61 74 20 69 74 20 63 61 6e 20 73 70 69   that it can spi
16dd0 6c 6c 20 63 61 63 68 65 0a 2a 2a 20 70 61 67 65  ll cache.** page
16de0 73 20 69 6e 74 6f 20 74 68 65 20 64 61 74 61 62  s into the datab
16df0 61 73 65 20 66 69 6c 65 20 77 69 74 68 6f 75 74  ase file without
16e00 20 68 61 72 6d 20 74 6f 20 63 6f 6e 63 75 72 72   harm to concurr
16e10 65 6e 74 0a 2a 2a 20 72 65 61 64 65 72 73 2e 20  ent.** readers. 
16e20 20 5e 49 66 20 69 74 20 69 73 20 75 6e 61 62 6c   ^If it is unabl
16e30 65 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 68 65  e to promote the
16e40 20 6c 6f 63 6b 2c 20 74 68 65 6e 20 74 68 65 20   lock, then the 
16e50 69 6e 2d 6d 65 6d 6f 72 79 0a 2a 2a 20 63 61 63  in-memory.** cac
16e60 68 65 20 77 69 6c 6c 20 62 65 20 6c 65 66 74 20  he will be left 
16e70 69 6e 20 61 6e 20 69 6e 63 6f 6e 73 69 73 74 65  in an inconsiste
16e80 6e 74 20 73 74 61 74 65 20 61 6e 64 20 73 6f 20  nt state and so 
16e90 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 63 6f 64  the error.** cod
16ea0 65 20 69 73 20 70 72 6f 6d 6f 74 65 64 20 66 72  e is promoted fr
16eb0 6f 6d 20 74 68 65 20 72 65 6c 61 74 69 76 65 6c  om the relativel
16ec0 79 20 62 65 6e 69 67 6e 20 5b 53 51 4c 49 54 45  y benign [SQLITE
16ed0 5f 42 55 53 59 5d 20 74 6f 0a 2a 2a 20 74 68 65  _BUSY] to.** the
16ee0 20 6d 6f 72 65 20 73 65 76 65 72 65 20 5b 53 51   more severe [SQ
16ef0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
16f00 45 44 5d 2e 20 20 5e 54 68 69 73 20 65 72 72 6f  ED].  ^This erro
16f10 72 20 63 6f 64 65 20 70 72 6f 6d 6f 74 69 6f 6e  r code promotion
16f20 0a 2a 2a 20 66 6f 72 63 65 73 20 61 6e 20 61 75  .** forces an au
16f30 74 6f 6d 61 74 69 63 20 72 6f 6c 6c 62 61 63 6b  tomatic rollback
16f40 20 6f 66 20 74 68 65 20 63 68 61 6e 67 65 73 2e   of the changes.
16f50 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 3c 61 20    See the.** <a 
16f60 68 72 65 66 3d 22 2f 63 76 73 74 72 61 63 2f 77  href="/cvstrac/w
16f70 69 6b 69 3f 70 3d 43 6f 72 72 75 70 74 69 6f 6e  iki?p=Corruption
16f80 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72  FollowingBusyErr
16f90 6f 72 22 3e 0a 2a 2a 20 43 6f 72 72 75 70 74 69  or">.** Corrupti
16fa0 6f 6e 46 6f 6c 6c 6f 77 69 6e 67 42 75 73 79 45  onFollowingBusyE
16fb0 72 72 6f 72 3c 2f 61 3e 20 77 69 6b 69 20 70 61  rror</a> wiki pa
16fc0 67 65 20 66 6f 72 20 61 20 64 69 73 63 75 73 73  ge for a discuss
16fd0 69 6f 6e 20 6f 66 20 77 68 79 0a 2a 2a 20 74 68  ion of why.** th
16fe0 69 73 20 69 73 20 69 6d 70 6f 72 74 61 6e 74 2e  is is important.
16ff0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72 65 20 63  .**.** ^(There c
17000 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20 73 69 6e  an only be a sin
17010 67 6c 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  gle busy handler
17020 20 64 65 66 69 6e 65 64 20 66 6f 72 20 65 61 63   defined for eac
17030 68 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63  h.** [database c
17040 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20 20 53 65 74  onnection].  Set
17050 74 69 6e 67 20 61 20 6e 65 77 20 62 75 73 79 20  ting a new busy 
17060 68 61 6e 64 6c 65 72 20 63 6c 65 61 72 73 20 61  handler clears a
17070 6e 79 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c 79  ny.** previously
17080 20 73 65 74 20 68 61 6e 64 6c 65 72 2e 29 5e 20   set handler.)^ 
17090 20 5e 4e 6f 74 65 20 74 68 61 74 20 63 61 6c 6c   ^Note that call
170a0 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
170b0 79 5f 74 69 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20  y_timeout()].** 
170c0 77 69 6c 6c 20 61 6c 73 6f 20 73 65 74 20 6f 72  will also set or
170d0 20 63 6c 65 61 72 20 74 68 65 20 62 75 73 79 20   clear the busy 
170e0 68 61 6e 64 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54  handler..**.** T
170f0 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b  he busy callback
17100 20 73 68 6f 75 6c 64 20 6e 6f 74 20 74 61 6b 65   should not take
17110 20 61 6e 79 20 61 63 74 69 6f 6e 73 20 77 68 69   any actions whi
17120 63 68 20 6d 6f 64 69 66 79 20 74 68 65 0a 2a 2a  ch modify the.**
17130 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
17140 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
17150 64 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c  d the busy handl
17160 65 72 2e 20 20 41 6e 79 20 73 75 63 68 20 61 63  er.  Any such ac
17170 74 69 6f 6e 73 0a 2a 2a 20 72 65 73 75 6c 74 20  tions.** result 
17180 69 6e 20 75 6e 64 65 66 69 6e 65 64 20 62 65 68  in undefined beh
17190 61 76 69 6f 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20  avior..** .** A 
171a0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 6d 75 73  busy handler mus
171b0 74 20 6e 6f 74 20 63 6c 6f 73 65 20 74 68 65 20  t not close the 
171c0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
171d0 69 6f 6e 0a 2a 2a 20 6f 72 20 5b 70 72 65 70 61  ion.** or [prepa
171e0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
171f0 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
17200 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f  busy handler..*/
17210 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
17220 79 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  y_handler(sqlite
17230 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a  3*, int(*)(void*
17240 2c 69 6e 74 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  ,int), void*);..
17250 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
17260 53 65 74 20 41 20 42 75 73 79 20 54 69 6d 65 6f  Set A Busy Timeo
17270 75 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72  ut.**.** ^This r
17280 6f 75 74 69 6e 65 20 73 65 74 73 20 61 20 5b 73  outine sets a [s
17290 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64  qlite3_busy_hand
172a0 6c 65 72 20 7c 20 62 75 73 79 20 68 61 6e 64 6c  ler | busy handl
172b0 65 72 5d 20 74 68 61 74 20 73 6c 65 65 70 73 0a  er] that sleeps.
172c0 2a 2a 20 66 6f 72 20 61 20 73 70 65 63 69 66 69  ** for a specifi
172d0 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 74 69 6d  ed amount of tim
172e0 65 20 77 68 65 6e 20 61 20 74 61 62 6c 65 20 69  e when a table i
172f0 73 20 6c 6f 63 6b 65 64 2e 20 20 5e 54 68 65 20  s locked.  ^The 
17300 68 61 6e 64 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20  handler.** will 
17310 73 6c 65 65 70 20 6d 75 6c 74 69 70 6c 65 20 74  sleep multiple t
17320 69 6d 65 73 20 75 6e 74 69 6c 20 61 74 20 6c 65  imes until at le
17330 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
17340 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
17350 67 0a 2a 2a 20 68 61 76 65 20 61 63 63 75 6d 75  g.** have accumu
17360 6c 61 74 65 64 2e 20 20 5e 41 66 74 65 72 20 61  lated.  ^After a
17370 74 20 6c 65 61 73 74 20 22 6d 73 22 20 6d 69 6c  t least "ms" mil
17380 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
17390 65 70 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 68 61  eping,.** the ha
173a0 6e 64 6c 65 72 20 72 65 74 75 72 6e 73 20 30 20  ndler returns 0 
173b0 77 68 69 63 68 20 63 61 75 73 65 73 20 5b 73 71  which causes [sq
173c0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 74 6f  lite3_step()] to
173d0 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49   return.** [SQLI
173e0 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c  TE_BUSY] or [SQL
173f0 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45  ITE_IOERR_BLOCKE
17400 44 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69  D]..**.** ^Calli
17410 6e 67 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  ng this routine 
17420 77 69 74 68 20 61 6e 20 61 72 67 75 6d 65 6e 74  with an argument
17430 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
17440 75 61 6c 20 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74  ual to zero.** t
17450 75 72 6e 73 20 6f 66 66 20 61 6c 6c 20 62 75 73  urns off all bus
17460 79 20 68 61 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a  y handlers..**.*
17470 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f 6e  * ^(There can on
17480 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20 62  ly be a single b
17490 75 73 79 20 68 61 6e 64 6c 65 72 20 66 6f 72 20  usy handler for 
174a0 61 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20  a particular.** 
174b0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
174c0 74 69 6f 6e 5d 20 61 6e 79 20 61 6e 79 20 67 69  tion] any any gi
174d0 76 65 6e 20 6d 6f 6d 65 6e 74 2e 20 20 49 66 20  ven moment.  If 
174e0 61 6e 6f 74 68 65 72 20 62 75 73 79 20 68 61 6e  another busy han
174f0 64 6c 65 72 0a 2a 2a 20 77 61 73 20 64 65 66 69  dler.** was defi
17500 6e 65 64 20 20 28 75 73 69 6e 67 20 5b 73 71 6c  ned  (using [sql
17510 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
17520 72 28 29 5d 29 20 70 72 69 6f 72 20 74 6f 20 63  r()]) prior to c
17530 61 6c 6c 69 6e 67 0a 2a 2a 20 74 68 69 73 20 72  alling.** this r
17540 6f 75 74 69 6e 65 2c 20 74 68 61 74 20 6f 74 68  outine, that oth
17550 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  er busy handler 
17560 69 73 20 63 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f  is cleared.)^.*/
17570 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 75 73  .int sqlite3_bus
17580 79 5f 74 69 6d 65 6f 75 74 28 73 71 6c 69 74 65  y_timeout(sqlite
17590 33 2a 2c 20 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a  3*, int ms);../*
175a0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
175b0 6e 76 65 6e 69 65 6e 63 65 20 52 6f 75 74 69 6e  nvenience Routin
175c0 65 73 20 46 6f 72 20 52 75 6e 6e 69 6e 67 20 51  es For Running Q
175d0 75 65 72 69 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69  ueries.**.** Thi
175e0 73 20 69 73 20 61 20 6c 65 67 61 63 79 20 69 6e  s is a legacy in
175f0 74 65 72 66 61 63 65 20 74 68 61 74 20 69 73 20  terface that is 
17600 70 72 65 73 65 72 76 65 64 20 66 6f 72 20 62 61  preserved for ba
17610 63 6b 77 61 72 64 73 20 63 6f 6d 70 61 74 69 62  ckwards compatib
17620 69 6c 69 74 79 2e 0a 2a 2a 20 55 73 65 20 6f 66  ility..** Use of
17630 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
17640 69 73 20 6e 6f 74 20 72 65 63 6f 6d 6d 65 6e 64  is not recommend
17650 65 64 2e 0a 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69  ed..**.** Defini
17660 74 69 6f 6e 3a 20 41 20 3c 62 3e 72 65 73 75 6c  tion: A <b>resul
17670 74 20 74 61 62 6c 65 3c 2f 62 3e 20 69 73 20 6d  t table</b> is m
17680 65 6d 6f 72 79 20 64 61 74 61 20 73 74 72 75 63  emory data struc
17690 74 75 72 65 20 63 72 65 61 74 65 64 20 62 79 20  ture created by 
176a0 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
176b0 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 69 6e 74  get_table()] int
176c0 65 72 66 61 63 65 2e 20 20 41 20 72 65 73 75 6c  erface.  A resul
176d0 74 20 74 61 62 6c 65 20 72 65 63 6f 72 64 73 20  t table records 
176e0 74 68 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65 20  the.** complete 
176f0 71 75 65 72 79 20 72 65 73 75 6c 74 73 20 66 72  query results fr
17700 6f 6d 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 71  om one or more q
17710 75 65 72 69 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ueries..**.** Th
17720 65 20 74 61 62 6c 65 20 63 6f 6e 63 65 70 74 75  e table conceptu
17730 61 6c 6c 79 20 68 61 73 20 61 20 6e 75 6d 62 65  ally has a numbe
17740 72 20 6f 66 20 72 6f 77 73 20 61 6e 64 20 63 6f  r of rows and co
17750 6c 75 6d 6e 73 2e 20 20 42 75 74 0a 2a 2a 20 74  lumns.  But.** t
17760 68 65 73 65 20 6e 75 6d 62 65 72 73 20 61 72 65  hese numbers are
17770 20 6e 6f 74 20 70 61 72 74 20 6f 66 20 74 68 65   not part of the
17780 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 74   result table it
17790 73 65 6c 66 2e 20 20 54 68 65 73 65 0a 2a 2a 20  self.  These.** 
177a0 6e 75 6d 62 65 72 73 20 61 72 65 20 6f 62 74 61  numbers are obta
177b0 69 6e 65 64 20 73 65 70 61 72 61 74 65 6c 79 2e  ined separately.
177c0 20 20 4c 65 74 20 4e 20 62 65 20 74 68 65 20 6e    Let N be the n
177d0 75 6d 62 65 72 20 6f 66 20 72 6f 77 73 0a 2a 2a  umber of rows.**
177e0 20 61 6e 64 20 4d 20 62 65 20 74 68 65 20 6e 75   and M be the nu
177f0 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e  mber of columns.
17800 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20  .**.** A result 
17810 74 61 62 6c 65 20 69 73 20 61 6e 20 61 72 72 61  table is an arra
17820 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20 74 6f  y of pointers to
17830 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17840 20 55 54 46 2d 38 20 73 74 72 69 6e 67 73 2e 0a   UTF-8 strings..
17850 2a 2a 20 54 68 65 72 65 20 61 72 65 20 28 4e 2b  ** There are (N+
17860 31 29 2a 4d 20 65 6c 65 6d 65 6e 74 73 20 69 6e  1)*M elements in
17870 20 74 68 65 20 61 72 72 61 79 2e 20 20 54 68 65   the array.  The
17880 20 66 69 72 73 74 20 4d 20 70 6f 69 6e 74 65 72   first M pointer
17890 73 20 70 6f 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65  s point.** to ze
178a0 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74  ro-terminated st
178b0 72 69 6e 67 73 20 74 68 61 74 20 20 63 6f 6e 74  rings that  cont
178c0 61 69 6e 20 74 68 65 20 6e 61 6d 65 73 20 6f 66  ain the names of
178d0 20 74 68 65 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a   the columns..**
178e0 20 54 68 65 20 72 65 6d 61 69 6e 69 6e 67 20 65   The remaining e
178f0 6e 74 72 69 65 73 20 61 6c 6c 20 70 6f 69 6e 74  ntries all point
17900 20 74 6f 20 71 75 65 72 79 20 72 65 73 75 6c 74   to query result
17910 73 2e 20 20 4e 55 4c 4c 20 76 61 6c 75 65 73 20  s.  NULL values 
17920 72 65 73 75 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c  result.** in NUL
17930 4c 20 70 6f 69 6e 74 65 72 73 2e 20 20 41 6c 6c  L pointers.  All
17940 20 6f 74 68 65 72 20 76 61 6c 75 65 73 20 61 72   other values ar
17950 65 20 69 6e 20 74 68 65 69 72 20 55 54 46 2d 38  e in their UTF-8
17960 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
17970 0a 2a 2a 20 73 74 72 69 6e 67 20 72 65 70 72 65  .** string repre
17980 73 65 6e 74 61 74 69 6f 6e 20 61 73 20 72 65 74  sentation as ret
17990 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65  urned by [sqlite
179a0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 5d  3_column_text()]
179b0 2e 0a 2a 2a 0a 2a 2a 20 41 20 72 65 73 75 6c 74  ..**.** A result
179c0 20 74 61 62 6c 65 20 6d 69 67 68 74 20 63 6f 6e   table might con
179d0 73 69 73 74 20 6f 66 20 6f 6e 65 20 6f 72 20 6d  sist of one or m
179e0 6f 72 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ore memory alloc
179f0 61 74 69 6f 6e 73 2e 0a 2a 2a 20 49 74 20 69 73  ations..** It is
17a00 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 70 61 73   not safe to pas
17a10 73 20 61 20 72 65 73 75 6c 74 20 74 61 62 6c 65  s a result table
17a20 20 64 69 72 65 63 74 6c 79 20 74 6f 20 5b 73 71   directly to [sq
17a30 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a  lite3_free()]..*
17a40 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65  * A result table
17a50 20 73 68 6f 75 6c 64 20 62 65 20 64 65 61 6c 6c   should be deall
17a60 6f 63 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ocated using [sq
17a70 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65  lite3_free_table
17a80 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20  ()]..**.** ^(As 
17a90 61 6e 20 65 78 61 6d 70 6c 65 20 6f 66 20 74 68  an example of th
17aa0 65 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 66  e result table f
17ab0 6f 72 6d 61 74 2c 20 73 75 70 70 6f 73 65 20 61  ormat, suppose a
17ac0 20 71 75 65 72 79 20 72 65 73 75 6c 74 0a 2a 2a   query result.**
17ad0 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a   is as follows:.
17ae0 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
17af0 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20  e><pre>.**      
17b00 20 20 4e 61 6d 65 20 20 20 20 20 20 20 20 7c 20    Name        | 
17b10 41 67 65 0a 2a 2a 20 20 20 20 20 20 20 20 2d 2d  Age.**        --
17b20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
17b30 2d 2d 2d 2d 2d 0a 2a 2a 20 20 20 20 20 20 20 20  -----.**        
17b40 41 6c 69 63 65 20 20 20 20 20 20 20 7c 20 34 33  Alice       | 43
17b50 0a 2a 2a 20 20 20 20 20 20 20 20 42 6f 62 20 20  .**        Bob  
17b60 20 20 20 20 20 20 20 7c 20 32 38 0a 2a 2a 20 20         | 28.**  
17b70 20 20 20 20 20 20 43 69 6e 64 79 20 20 20 20 20        Cindy     
17b80 20 20 7c 20 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e    | 21.** </pre>
17b90 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17ba0 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74 77  .** There are tw
17bb0 6f 20 63 6f 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20  o column (M==2) 
17bc0 61 6e 64 20 74 68 72 65 65 20 72 6f 77 73 20 28  and three rows (
17bd0 4e 3d 3d 33 29 2e 20 20 54 68 75 73 20 74 68 65  N==3).  Thus the
17be0 0a 2a 2a 20 72 65 73 75 6c 74 20 74 61 62 6c 65  .** result table
17bf0 20 68 61 73 20 38 20 65 6e 74 72 69 65 73 2e 20   has 8 entries. 
17c00 20 53 75 70 70 6f 73 65 20 74 68 65 20 72 65 73   Suppose the res
17c10 75 6c 74 20 74 61 62 6c 65 20 69 73 20 73 74 6f  ult table is sto
17c20 72 65 64 0a 2a 2a 20 69 6e 20 61 6e 20 61 72 72  red.** in an arr
17c30 61 79 20 6e 61 6d 65 73 20 61 7a 52 65 73 75 6c  ay names azResul
17c40 74 2e 20 20 54 68 65 6e 20 61 7a 52 65 73 75 6c  t.  Then azResul
17c50 74 20 68 6f 6c 64 73 20 74 68 69 73 20 63 6f 6e  t holds this con
17c60 74 65 6e 74 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  tent:.**.** <blo
17c70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17c80 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
17c90 26 23 39 31 3b 30 5d 20 3d 20 22 4e 61 6d 65 22  &#91;0] = "Name"
17ca0 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
17cb0 73 75 6c 74 26 23 39 31 3b 31 5d 20 3d 20 22 41  sult&#91;1] = "A
17cc0 67 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61  ge";.**        a
17cd0 7a 52 65 73 75 6c 74 26 23 39 31 3b 32 5d 20 3d  zResult&#91;2] =
17ce0 20 22 41 6c 69 63 65 22 3b 0a 2a 2a 20 20 20 20   "Alice";.**    
17cf0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
17d00 3b 33 5d 20 3d 20 22 34 33 22 3b 0a 2a 2a 20 20  ;3] = "43";.**  
17d10 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23        azResult&#
17d20 39 31 3b 34 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a  91;4] = "Bob";.*
17d30 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c  *        azResul
17d40 74 26 23 39 31 3b 35 5d 20 3d 20 22 32 38 22 3b  t&#91;5] = "28";
17d50 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
17d60 75 6c 74 26 23 39 31 3b 36 5d 20 3d 20 22 43 69  ult&#91;6] = "Ci
17d70 6e 64 79 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ndy";.**        
17d80 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 37 5d 20  azResult&#91;7] 
17d90 3d 20 22 32 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65  = "21";.** </pre
17da0 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
17db0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
17dc0 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20  te3_get_table() 
17dd0 66 75 6e 63 74 69 6f 6e 20 65 76 61 6c 75 61 74  function evaluat
17de0 65 73 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a  es one or more.*
17df0 2a 20 73 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61  * semicolon-sepa
17e00 72 61 74 65 64 20 53 51 4c 20 73 74 61 74 65 6d  rated SQL statem
17e10 65 6e 74 73 20 69 6e 20 74 68 65 20 7a 65 72 6f  ents in the zero
17e20 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46 2d  -terminated UTF-
17e30 38 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 66 20 69  8.** string of i
17e40 74 73 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  ts 2nd parameter
17e50 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 72   and returns a r
17e60 65 73 75 6c 74 20 74 61 62 6c 65 20 74 6f 20 74  esult table to t
17e70 68 65 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 67 69  he.** pointer gi
17e80 76 65 6e 20 69 6e 20 69 74 73 20 33 72 64 20 70  ven in its 3rd p
17e90 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20  arameter..**.** 
17ea0 41 66 74 65 72 20 74 68 65 20 61 70 70 6c 69 63  After the applic
17eb0 61 74 69 6f 6e 20 68 61 73 20 66 69 6e 69 73 68  ation has finish
17ec0 65 64 20 77 69 74 68 20 74 68 65 20 72 65 73 75  ed with the resu
17ed0 6c 74 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  lt from sqlite3_
17ee0 67 65 74 5f 74 61 62 6c 65 28 29 2c 0a 2a 2a 20  get_table(),.** 
17ef0 69 74 20 6d 75 73 74 20 70 61 73 73 20 74 68 65  it must pass the
17f00 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 70 6f   result table po
17f10 69 6e 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  inter to sqlite3
17f20 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 20 69 6e  _free_table() in
17f30 20 6f 72 64 65 72 20 74 6f 0a 2a 2a 20 72 65 6c   order to.** rel
17f40 65 61 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  ease the memory 
17f50 74 68 61 74 20 77 61 73 20 6d 61 6c 6c 6f 63 65  that was malloce
17f60 64 2e 20 20 42 65 63 61 75 73 65 20 6f 66 20 74  d.  Because of t
17f70 68 65 20 77 61 79 20 74 68 65 0a 2a 2a 20 5b 73  he way the.** [s
17f80 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
17f90 20 68 61 70 70 65 6e 73 20 77 69 74 68 69 6e 20   happens within 
17fa0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
17fb0 65 28 29 2c 20 74 68 65 20 63 61 6c 6c 69 6e 67  e(), the calling
17fc0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  .** function mus
17fd0 74 20 6e 6f 74 20 74 72 79 20 74 6f 20 63 61 6c  t not try to cal
17fe0 6c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  l [sqlite3_free(
17ff0 29 5d 20 64 69 72 65 63 74 6c 79 2e 20 20 4f 6e  )] directly.  On
18000 6c 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66  ly.** [sqlite3_f
18010 72 65 65 5f 74 61 62 6c 65 28 29 5d 20 69 73 20  ree_table()] is 
18020 61 62 6c 65 20 74 6f 20 72 65 6c 65 61 73 65 20  able to release 
18030 74 68 65 20 6d 65 6d 6f 72 79 20 70 72 6f 70 65  the memory prope
18040 72 6c 79 20 61 6e 64 20 73 61 66 65 6c 79 2e 0a  rly and safely..
18050 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
18060 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 20 69 6e  3_get_table() in
18070 74 65 72 66 61 63 65 20 69 73 20 69 6d 70 6c 65  terface is imple
18080 6d 65 6e 74 65 64 20 61 73 20 61 20 77 72 61 70  mented as a wrap
18090 70 65 72 20 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73  per around.** [s
180a0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2e 20  qlite3_exec()]. 
180b0 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74   The sqlite3_get
180c0 5f 74 61 62 6c 65 28 29 20 72 6f 75 74 69 6e 65  _table() routine
180d0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 61   does not have a
180e0 63 63 65 73 73 0a 2a 2a 20 74 6f 20 61 6e 79 20  ccess.** to any 
180f0 69 6e 74 65 72 6e 61 6c 20 64 61 74 61 20 73 74  internal data st
18100 72 75 63 74 75 72 65 73 20 6f 66 20 53 51 4c 69  ructures of SQLi
18110 74 65 2e 20 20 49 74 20 75 73 65 73 20 6f 6e 6c  te.  It uses onl
18120 79 20 74 68 65 20 70 75 62 6c 69 63 0a 2a 2a 20  y the public.** 
18130 69 6e 74 65 72 66 61 63 65 20 64 65 66 69 6e 65  interface define
18140 64 20 68 65 72 65 2e 20 20 41 73 20 61 20 63 6f  d here.  As a co
18150 6e 73 65 71 75 65 6e 63 65 2c 20 65 72 72 6f 72  nsequence, error
18160 73 20 74 68 61 74 20 6f 63 63 75 72 20 69 6e 20  s that occur in 
18170 74 68 65 0a 2a 2a 20 77 72 61 70 70 65 72 20 6c  the.** wrapper l
18180 61 79 65 72 20 6f 75 74 73 69 64 65 20 6f 66 20  ayer outside of 
18190 74 68 65 20 69 6e 74 65 72 6e 61 6c 20 5b 73 71  the internal [sq
181a0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 63 61  lite3_exec()] ca
181b0 6c 6c 20 61 72 65 20 6e 6f 74 0a 2a 2a 20 72 65  ll are not.** re
181c0 66 6c 65 63 74 65 64 20 69 6e 20 73 75 62 73 65  flected in subse
181d0 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 5b  quent calls to [
181e0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
181f0 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
18200 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a  3_errmsg()]..*/.
18210 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
18220 74 61 62 6c 65 28 0a 20 20 73 71 6c 69 74 65 33  table(.  sqlite3
18230 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f   *db,          /
18240 2a 20 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61  * An open databa
18250 73 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  se */.  const ch
18260 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 2f 2a  ar *zSql,     /*
18270 20 53 51 4c 20 74 6f 20 62 65 20 65 76 61 6c 75   SQL to be evalu
18280 61 74 65 64 20 2a 2f 0a 20 20 63 68 61 72 20 2a  ated */.  char *
18290 2a 2a 70 61 7a 52 65 73 75 6c 74 2c 20 20 20 20  **pazResult,    
182a0 2f 2a 20 52 65 73 75 6c 74 73 20 6f 66 20 74 68  /* Results of th
182b0 65 20 71 75 65 72 79 20 2a 2f 0a 20 20 69 6e 74  e query */.  int
182c0 20 2a 70 6e 52 6f 77 2c 20 20 20 20 20 20 20 20   *pnRow,        
182d0 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20     /* Number of 
182e0 72 65 73 75 6c 74 20 72 6f 77 73 20 77 72 69 74  result rows writ
182f0 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 69 6e  ten here */.  in
18300 74 20 2a 70 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20  t *pnColumn,    
18310 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72 20 6f 66      /* Number of
18320 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 73 20   result columns 
18330 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a  written here */.
18340 20 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 6d 73    char **pzErrms
18350 67 20 20 20 20 20 20 20 2f 2a 20 45 72 72 6f 72  g       /* Error
18360 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65 72   msg written her
18370 65 20 2a 2f 0a 29 3b 0a 76 6f 69 64 20 73 71 6c  e */.);.void sql
18380 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c 65 28  ite3_free_table(
18390 63 68 61 72 20 2a 2a 72 65 73 75 6c 74 29 3b 0a  char **result);.
183a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
183b0 20 46 6f 72 6d 61 74 74 65 64 20 53 74 72 69 6e   Formatted Strin
183c0 67 20 50 72 69 6e 74 69 6e 67 20 46 75 6e 63 74  g Printing Funct
183d0 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
183e0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 77 6f   routines are wo
183f0 72 6b 2d 61 6c 69 6b 65 73 20 6f 66 20 74 68 65  rk-alikes of the
18400 20 22 70 72 69 6e 74 66 28 29 22 20 66 61 6d 69   "printf()" fami
18410 6c 79 20 6f 66 20 66 75 6e 63 74 69 6f 6e 73 0a  ly of functions.
18420 2a 2a 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e  ** from the stan
18430 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a  dard C library..
18440 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
18450 65 33 5f 6d 70 72 69 6e 74 66 28 29 20 61 6e 64  e3_mprintf() and
18460 20 73 71 6c 69 74 65 33 5f 76 6d 70 72 69 6e 74   sqlite3_vmprint
18470 66 28 29 20 72 6f 75 74 69 6e 65 73 20 77 72 69  f() routines wri
18480 74 65 20 74 68 65 69 72 0a 2a 2a 20 72 65 73 75  te their.** resu
18490 6c 74 73 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20  lts into memory 
184a0 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73  obtained from [s
184b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
184c0 2e 0a 2a 2a 20 54 68 65 20 73 74 72 69 6e 67 73  ..** The strings
184d0 20 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 65   returned by the
184e0 73 65 20 74 77 6f 20 72 6f 75 74 69 6e 65 73 20  se two routines 
184f0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 72 65 6c  should be.** rel
18500 65 61 73 65 64 20 62 79 20 5b 73 71 6c 69 74 65  eased by [sqlite
18510 33 5f 66 72 65 65 28 29 5d 2e 20 20 5e 42 6f 74  3_free()].  ^Bot
18520 68 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  h routines retur
18530 6e 20 61 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e  n a.** NULL poin
18540 74 65 72 20 69 66 20 5b 73 71 6c 69 74 65 33 5f  ter if [sqlite3_
18550 6d 61 6c 6c 6f 63 28 29 5d 20 69 73 20 75 6e 61  malloc()] is una
18560 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
18570 65 6e 6f 75 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79  enough.** memory
18580 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 72 65 73   to hold the res
18590 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 2e 0a 2a  ulting string..*
185a0 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74  *.** ^(The sqlit
185b0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  e3_snprintf() ro
185c0 75 74 69 6e 65 20 69 73 20 73 69 6d 69 6c 61 72  utine is similar
185d0 20 74 6f 20 22 73 6e 70 72 69 6e 74 66 28 29 22   to "snprintf()"
185e0 20 66 72 6f 6d 0a 2a 2a 20 74 68 65 20 73 74 61   from.** the sta
185f0 6e 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e  ndard C library.
18600 20 20 54 68 65 20 72 65 73 75 6c 74 20 69 73 20    The result is 
18610 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74 68 65  written into the
18620 0a 2a 2a 20 62 75 66 66 65 72 20 73 75 70 70 6c  .** buffer suppl
18630 69 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  ied as the secon
18640 64 20 70 61 72 61 6d 65 74 65 72 20 77 68 6f 73  d parameter whos
18650 65 20 73 69 7a 65 20 69 73 20 67 69 76 65 6e 20  e size is given 
18660 62 79 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20  by.** the first 
18670 70 61 72 61 6d 65 74 65 72 2e 20 4e 6f 74 65 20  parameter. Note 
18680 74 68 61 74 20 74 68 65 20 6f 72 64 65 72 20 6f  that the order o
18690 66 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74  f the.** first t
186a0 77 6f 20 70 61 72 61 6d 65 74 65 72 73 20 69 73  wo parameters is
186b0 20 72 65 76 65 72 73 65 64 20 66 72 6f 6d 20 73   reversed from s
186c0 6e 70 72 69 6e 74 66 28 29 2e 29 5e 20 20 54 68  nprintf().)^  Th
186d0 69 73 20 69 73 20 61 6e 0a 2a 2a 20 68 69 73 74  is is an.** hist
186e0 6f 72 69 63 61 6c 20 61 63 63 69 64 65 6e 74 20  orical accident 
186f0 74 68 61 74 20 63 61 6e 6e 6f 74 20 62 65 20 66  that cannot be f
18700 69 78 65 64 20 77 69 74 68 6f 75 74 20 62 72 65  ixed without bre
18710 61 6b 69 6e 67 0a 2a 2a 20 62 61 63 6b 77 61 72  aking.** backwar
18720 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
18730 2e 20 20 5e 28 4e 6f 74 65 20 61 6c 73 6f 20 74  .  ^(Note also t
18740 68 61 74 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  hat sqlite3_snpr
18750 69 6e 74 66 28 29 0a 2a 2a 20 72 65 74 75 72 6e  intf().** return
18760 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 69  s a pointer to i
18770 74 73 20 62 75 66 66 65 72 20 69 6e 73 74 65 61  ts buffer instea
18780 64 20 6f 66 20 74 68 65 20 6e 75 6d 62 65 72 20  d of the number 
18790 6f 66 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  of.** characters
187a0 20 61 63 74 75 61 6c 6c 79 20 77 72 69 74 74 65   actually writte
187b0 6e 20 69 6e 74 6f 20 74 68 65 20 62 75 66 66 65  n into the buffe
187c0 72 2e 29 5e 20 20 57 65 20 61 64 6d 69 74 20 74  r.)^  We admit t
187d0 68 61 74 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65  hat.** the numbe
187e0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 20  r of characters 
187f0 77 72 69 74 74 65 6e 20 77 6f 75 6c 64 20 62 65  written would be
18800 20 61 20 6d 6f 72 65 20 75 73 65 66 75 6c 20 72   a more useful r
18810 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65 20 62  eturn.** value b
18820 75 74 20 77 65 20 63 61 6e 6e 6f 74 20 63 68 61  ut we cannot cha
18830 6e 67 65 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e  nge the implemen
18840 74 61 74 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  tation of sqlite
18850 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20  3_snprintf().** 
18860 6e 6f 77 20 77 69 74 68 6f 75 74 20 62 72 65 61  now without brea
18870 6b 69 6e 67 20 63 6f 6d 70 61 74 69 62 69 6c 69  king compatibili
18880 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f  ty..**.** ^As lo
18890 6e 67 20 61 73 20 74 68 65 20 62 75 66 66 65 72  ng as the buffer
188a0 20 73 69 7a 65 20 69 73 20 67 72 65 61 74 65 72   size is greater
188b0 20 74 68 61 6e 20 7a 65 72 6f 2c 20 73 71 6c 69   than zero, sqli
188c0 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
188d0 2a 20 67 75 61 72 61 6e 74 65 65 73 20 74 68 61  * guarantees tha
188e0 74 20 74 68 65 20 62 75 66 66 65 72 20 69 73 20  t the buffer is 
188f0 61 6c 77 61 79 73 20 7a 65 72 6f 2d 74 65 72 6d  always zero-term
18900 69 6e 61 74 65 64 2e 20 20 5e 54 68 65 20 66 69  inated.  ^The fi
18910 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  rst.** parameter
18920 20 22 6e 22 20 69 73 20 74 68 65 20 74 6f 74 61   "n" is the tota
18930 6c 20 73 69 7a 65 20 6f 66 20 74 68 65 20 62 75  l size of the bu
18940 66 66 65 72 2c 20 69 6e 63 6c 75 64 69 6e 67 20  ffer, including 
18950 73 70 61 63 65 20 66 6f 72 0a 2a 2a 20 74 68 65  space for.** the
18960 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72   zero terminator
18970 2e 20 20 53 6f 20 74 68 65 20 6c 6f 6e 67 65 73  .  So the longes
18980 74 20 73 74 72 69 6e 67 20 74 68 61 74 20 63 61  t string that ca
18990 6e 20 62 65 20 63 6f 6d 70 6c 65 74 65 6c 79 0a  n be completely.
189a0 2a 2a 20 77 72 69 74 74 65 6e 20 77 69 6c 6c 20  ** written will 
189b0 62 65 20 6e 2d 31 20 63 68 61 72 61 63 74 65 72  be n-1 character
189c0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  s..**.** ^The sq
189d0 6c 69 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28  lite3_vsnprintf(
189e0 29 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 76  ) routine is a v
189f0 61 72 61 72 67 73 20 76 65 72 73 69 6f 6e 20 6f  arargs version o
18a00 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
18a10 74 66 28 29 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tf()..**.** Thes
18a20 65 20 72 6f 75 74 69 6e 65 73 20 61 6c 6c 20 69  e routines all i
18a30 6d 70 6c 65 6d 65 6e 74 20 73 6f 6d 65 20 61 64  mplement some ad
18a40 64 69 74 69 6f 6e 61 6c 20 66 6f 72 6d 61 74 74  ditional formatt
18a50 69 6e 67 0a 2a 2a 20 6f 70 74 69 6f 6e 73 20 74  ing.** options t
18a60 68 61 74 20 61 72 65 20 75 73 65 66 75 6c 20 66  hat are useful f
18a70 6f 72 20 63 6f 6e 73 74 72 75 63 74 69 6e 67 20  or constructing 
18a80 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  SQL statements..
18a90 2a 2a 20 41 6c 6c 20 6f 66 20 74 68 65 20 75 73  ** All of the us
18aa0 75 61 6c 20 70 72 69 6e 74 66 28 29 20 66 6f 72  ual printf() for
18ab0 6d 61 74 74 69 6e 67 20 6f 70 74 69 6f 6e 73 20  matting options 
18ac0 61 70 70 6c 79 2e 20 20 49 6e 20 61 64 64 69 74  apply.  In addit
18ad0 69 6f 6e 2c 20 74 68 65 72 65 0a 2a 2a 20 69 73  ion, there.** is
18ae0 20 61 72 65 20 22 25 71 22 2c 20 22 25 51 22 2c   are "%q", "%Q",
18af0 20 61 6e 64 20 22 25 7a 22 20 6f 70 74 69 6f 6e   and "%z" option
18b00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  s..**.** ^(The %
18b10 71 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  q option works l
18b20 69 6b 65 20 25 73 20 69 6e 20 74 68 61 74 20 69  ike %s in that i
18b30 74 20 73 75 62 73 74 69 74 75 74 65 73 20 61 20  t substitutes a 
18b40 6e 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a  nul-terminated.*
18b50 2a 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 74 68  * string from th
18b60 65 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e  e argument list.
18b70 20 20 42 75 74 20 25 71 20 61 6c 73 6f 20 64 6f    But %q also do
18b80 75 62 6c 65 73 20 65 76 65 72 79 20 27 5c 27 27  ubles every '\''
18b90 20 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25   character..** %
18ba0 71 20 69 73 20 64 65 73 69 67 6e 65 64 20 66 6f  q is designed fo
18bb0 72 20 75 73 65 20 69 6e 73 69 64 65 20 61 20 73  r use inside a s
18bc0 74 72 69 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e  tring literal.)^
18bd0 20 20 42 79 20 64 6f 75 62 6c 69 6e 67 20 65 61    By doubling ea
18be0 63 68 20 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61  ch '\''.** chara
18bf0 63 74 65 72 20 69 74 20 65 73 63 61 70 65 73 20  cter it escapes 
18c00 74 68 61 74 20 63 68 61 72 61 63 74 65 72 20 61  that character a
18c10 6e 64 20 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20  nd allows it to 
18c20 62 65 20 69 6e 73 65 72 74 65 64 20 69 6e 74 6f  be inserted into
18c30 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67 2e 0a  .** the string..
18c40 2a 2a 0a 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c  **.** For exampl
18c50 65 2c 20 61 73 73 75 6d 65 20 74 68 65 20 73 74  e, assume the st
18c60 72 69 6e 67 20 76 61 72 69 61 62 6c 65 20 7a 54  ring variable zT
18c70 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 74 65 78  ext contains tex
18c80 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a  t as follows:.**
18c90 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
18ca0 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a  <pre>.**  char *
18cb0 7a 54 65 78 74 20 3d 20 22 49 74 27 73 20 61 20  zText = "It's a 
18cc0 68 61 70 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20  happy day!";.** 
18cd0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
18ce0 74 65 3e 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61  te>.**.** One ca
18cf0 6e 20 75 73 65 20 74 68 69 73 20 74 65 78 74 20  n use this text 
18d00 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d  in an SQL statem
18d10 65 6e 74 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a  ent as follows:.
18d20 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
18d30 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72  e><pre>.**  char
18d40 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65 33   *zSQL = sqlite3
18d50 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52 54  _mprintf("INSERT
18d60 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c 55   INTO table VALU
18d70 45 53 28 27 25 71 27 29 22 2c 20 7a 54 65 78 74  ES('%q')", zText
18d80 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65  );.**  sqlite3_e
18d90 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c  xec(db, zSQL, 0,
18da0 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69   0, 0);.**  sqli
18db0 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a  te3_free(zSQL);.
18dc0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
18dd0 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63  quote>.**.** Bec
18de0 61 75 73 65 20 74 68 65 20 25 71 20 66 6f 72 6d  ause the %q form
18df0 61 74 20 73 74 72 69 6e 67 20 69 73 20 75 73 65  at string is use
18e00 64 2c 20 74 68 65 20 27 5c 27 27 20 63 68 61 72  d, the '\'' char
18e10 61 63 74 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a  acter in zText.*
18e20 2a 20 69 73 20 65 73 63 61 70 65 64 20 61 6e 64  * is escaped and
18e30 20 74 68 65 20 53 51 4c 20 67 65 6e 65 72 61 74   the SQL generat
18e40 65 64 20 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73  ed is as follows
18e50 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
18e60 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e  ote><pre>.**  IN
18e70 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 31  SERT INTO table1
18e80 20 56 41 4c 55 45 53 28 27 49 74 27 27 73 20 61   VALUES('It''s a
18e90 20 68 61 70 70 79 20 64 61 79 21 27 29 0a 2a 2a   happy day!').**
18ea0 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75   </pre></blockqu
18eb0 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ote>.**.** This 
18ec0 69 73 20 63 6f 72 72 65 63 74 2e 20 20 48 61 64  is correct.  Had
18ed0 20 77 65 20 75 73 65 64 20 25 73 20 69 6e 73 74   we used %s inst
18ee0 65 61 64 20 6f 66 20 25 71 2c 20 74 68 65 20 67  ead of %q, the g
18ef0 65 6e 65 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20  enerated SQL.** 
18f00 77 6f 75 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65  would have looke
18f10 64 20 6c 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a  d like this:.**.
18f20 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
18f30 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20  pre>.**  INSERT 
18f40 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55  INTO table1 VALU
18f50 45 53 28 27 49 74 27 73 20 61 20 68 61 70 70 79  ES('It's a happy
18f60 20 64 61 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72   day!');.** </pr
18f70 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
18f80 2a 2a 0a 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e  **.** This secon
18f90 64 20 65 78 61 6d 70 6c 65 20 69 73 20 61 6e 20  d example is an 
18fa0 53 51 4c 20 73 79 6e 74 61 78 20 65 72 72 6f 72  SQL syntax error
18fb0 2e 20 20 41 73 20 61 20 67 65 6e 65 72 61 6c 20  .  As a general 
18fc0 72 75 6c 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a  rule you should.
18fd0 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 20 25 71  ** always use %q
18fe0 20 69 6e 73 74 65 61 64 20 6f 66 20 25 73 20 77   instead of %s w
18ff0 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 74 65  hen inserting te
19000 78 74 20 69 6e 74 6f 20 61 20 73 74 72 69 6e 67  xt into a string
19010 20 6c 69 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20   literal..**.** 
19020 5e 28 54 68 65 20 25 51 20 6f 70 74 69 6f 6e 20  ^(The %Q option 
19030 77 6f 72 6b 73 20 6c 69 6b 65 20 25 71 20 65 78  works like %q ex
19040 63 65 70 74 20 69 74 20 61 6c 73 6f 20 61 64 64  cept it also add
19050 73 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 20  s single quotes 
19060 61 72 6f 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75  around.** the ou
19070 74 73 69 64 65 20 6f 66 20 74 68 65 20 74 6f 74  tside of the tot
19080 61 6c 20 73 74 72 69 6e 67 2e 20 20 41 64 64 69  al string.  Addi
19090 74 69 6f 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65  tionally, if the
190a0 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
190b0 65 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69  e.** argument li
190c0 73 74 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  st is a NULL poi
190d0 6e 74 65 72 2c 20 25 51 20 73 75 62 73 74 69 74  nter, %Q substit
190e0 75 74 65 73 20 74 68 65 20 74 65 78 74 20 22 4e  utes the text "N
190f0 55 4c 4c 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a  ULL" (without.**
19100 20 73 69 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e   single quotes).
19110 29 5e 20 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d  )^  So, for exam
19120 70 6c 65 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73  ple, one could s
19130 61 79 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b  ay:.**.** <block
19140 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20  quote><pre>.**  
19150 63 68 61 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c  char *zSQL = sql
19160 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e  ite3_mprintf("IN
19170 53 45 52 54 20 49 4e 54 4f 20 74 61 62 6c 65 20  SERT INTO table 
19180 56 41 4c 55 45 53 28 25 51 29 22 2c 20 7a 54 65  VALUES(%Q)", zTe
19190 78 74 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33  xt);.**  sqlite3
191a0 5f 65 78 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20  _exec(db, zSQL, 
191b0 30 2c 20 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71  0, 0, 0);.**  sq
191c0 6c 69 74 65 33 5f 66 72 65 65 28 7a 53 51 4c 29  lite3_free(zSQL)
191d0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
191e0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
191f0 68 65 20 63 6f 64 65 20 61 62 6f 76 65 20 77 69  he code above wi
19200 6c 6c 20 72 65 6e 64 65 72 20 61 20 63 6f 72 72  ll render a corr
19210 65 63 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  ect SQL statemen
19220 74 20 69 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a  t in the zSQL.**
19230 20 76 61 72 69 61 62 6c 65 20 65 76 65 6e 20 69   variable even i
19240 66 20 74 68 65 20 7a 54 65 78 74 20 76 61 72 69  f the zText vari
19250 61 62 6c 65 20 69 73 20 61 20 4e 55 4c 4c 20 70  able is a NULL p
19260 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ointer..**.** ^(
19270 54 68 65 20 22 25 7a 22 20 66 6f 72 6d 61 74 74  The "%z" formatt
19280 69 6e 67 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73  ing option works
19290 20 6c 69 6b 65 20 22 25 73 22 20 62 75 74 20 77   like "%s" but w
192a0 69 74 68 20 74 68 65 0a 2a 2a 20 61 64 64 69 74  ith the.** addit
192b0 69 6f 6e 20 74 68 61 74 20 61 66 74 65 72 20 74  ion that after t
192c0 68 65 20 73 74 72 69 6e 67 20 68 61 73 20 62 65  he string has be
192d0 65 6e 20 72 65 61 64 20 61 6e 64 20 63 6f 70 69  en read and copi
192e0 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72  ed into.** the r
192f0 65 73 75 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f  esult, [sqlite3_
19300 66 72 65 65 28 29 5d 20 69 73 20 63 61 6c 6c 65  free()] is calle
19310 64 20 6f 6e 20 74 68 65 20 69 6e 70 75 74 20 73  d on the input s
19320 74 72 69 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72  tring.)^.*/.char
19330 20 2a 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74   *sqlite3_mprint
19340 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e  f(const char*,..
19350 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65  .);.char *sqlite
19360 33 5f 76 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  3_vmprintf(const
19370 20 63 68 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29   char*, va_list)
19380 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  ;.char *sqlite3_
19390 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61  snprintf(int,cha
193a0 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20  r*,const char*, 
193b0 2e 2e 2e 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69  ...);.char *sqli
193c0 74 65 33 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e  te3_vsnprintf(in
193d0 74 2c 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t,char*,const ch
193e0 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a  ar*, va_list);..
193f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
19400 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f  Memory Allocatio
19410 6e 20 53 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a  n Subsystem.**.*
19420 2a 20 54 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * The SQLite cor
19430 65 20 75 73 65 73 20 74 68 65 73 65 20 74 68 72  e uses these thr
19440 65 65 20 72 6f 75 74 69 6e 65 73 20 66 6f 72 20  ee routines for 
19450 61 6c 6c 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a  all of its own.*
19460 2a 20 69 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72  * internal memor
19470 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65  y allocation nee
19480 64 73 2e 20 22 43 6f 72 65 22 20 69 6e 20 74 68  ds. "Core" in th
19490 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e 74 65  e previous sente
194a0 6e 63 65 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20  nce.** does not 
194b0 69 6e 63 6c 75 64 65 20 6f 70 65 72 61 74 69 6e  include operatin
194c0 67 2d 73 79 73 74 65 6d 20 73 70 65 63 69 66 69  g-system specifi
194d0 63 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61  c VFS implementa
194e0 74 69 6f 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69  tion.  The.** Wi
194f0 6e 64 6f 77 73 20 56 46 53 20 75 73 65 73 20 6e  ndows VFS uses n
19500 61 74 69 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61  ative malloc() a
19510 6e 64 20 66 72 65 65 28 29 20 66 6f 72 20 73 6f  nd free() for so
19520 6d 65 20 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a  me operations..*
19530 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
19540 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69  3_malloc() routi
19550 6e 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69  ne returns a poi
19560 6e 74 65 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a  nter to a block.
19570 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20  ** of memory at 
19580 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
19590 20 6c 65 6e 67 74 68 2c 20 77 68 65 72 65 20 4e   length, where N
195a0 20 69 73 20 74 68 65 20 70 61 72 61 6d 65 74 65   is the paramete
195b0 72 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  r..** ^If sqlite
195c0 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e  3_malloc() is un
195d0 61 62 6c 65 20 74 6f 20 6f 62 74 61 69 6e 20 73  able to obtain s
195e0 75 66 66 69 63 69 65 6e 74 20 66 72 65 65 0a 2a  ufficient free.*
195f0 2a 20 6d 65 6d 6f 72 79 2c 20 69 74 20 72 65 74  * memory, it ret
19600 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  urns a NULL poin
19610 74 65 72 2e 20 20 5e 49 66 20 74 68 65 20 70 61  ter.  ^If the pa
19620 72 61 6d 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20  rameter N to.** 
19630 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19640 20 69 73 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61   is zero or nega
19650 74 69 76 65 20 74 68 65 6e 20 73 71 6c 69 74 65  tive then sqlite
19660 33 5f 6d 61 6c 6c 6f 63 28 29 20 72 65 74 75 72  3_malloc() retur
19670 6e 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  ns.** a NULL poi
19680 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c  nter..**.** ^Cal
19690 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72 65  ling sqlite3_fre
196a0 65 28 29 20 77 69 74 68 20 61 20 70 6f 69 6e 74  e() with a point
196b0 65 72 20 70 72 65 76 69 6f 75 73 6c 79 20 72 65  er previously re
196c0 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c  turned.** by sql
196d0 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72  ite3_malloc() or
196e0 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
196f0 28 29 20 72 65 6c 65 61 73 65 73 20 74 68 61 74  () releases that
19700 20 6d 65 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68   memory so.** th
19710 61 74 20 69 74 20 6d 69 67 68 74 20 62 65 20 72  at it might be r
19720 65 75 73 65 64 2e 20 20 5e 54 68 65 20 73 71 6c  eused.  ^The sql
19730 69 74 65 33 5f 66 72 65 65 28 29 20 72 6f 75 74  ite3_free() rout
19740 69 6e 65 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f  ine is.** a no-o
19750 70 20 69 66 20 69 73 20 63 61 6c 6c 65 64 20 77  p if is called w
19760 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  ith a NULL point
19770 65 72 2e 20 20 50 61 73 73 69 6e 67 20 61 20 4e  er.  Passing a N
19780 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74  ULL pointer.** t
19790 6f 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  o sqlite3_free()
197a0 20 69 73 20 68 61 72 6d 6c 65 73 73 2e 20 20 41   is harmless.  A
197b0 66 74 65 72 20 62 65 69 6e 67 20 66 72 65 65 64  fter being freed
197c0 2c 20 6d 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75  , memory.** shou
197d0 6c 64 20 6e 65 69 74 68 65 72 20 62 65 20 72 65  ld neither be re
197e0 61 64 20 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20  ad nor written. 
197f0 20 45 76 65 6e 20 72 65 61 64 69 6e 67 20 70 72   Even reading pr
19800 65 76 69 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a  eviously freed.*
19810 2a 20 6d 65 6d 6f 72 79 20 6d 69 67 68 74 20 72  * memory might r
19820 65 73 75 6c 74 20 69 6e 20 61 20 73 65 67 6d 65  esult in a segme
19830 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72  ntation fault or
19840 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
19850 72 6f 72 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63  ror..** Memory c
19860 6f 72 72 75 70 74 69 6f 6e 2c 20 61 20 73 65 67  orruption, a seg
19870 6d 65 6e 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c  mentation fault,
19880 20 6f 72 20 6f 74 68 65 72 20 73 65 76 65 72 65   or other severe
19890 20 65 72 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20   error.** might 
198a0 72 65 73 75 6c 74 20 69 66 20 73 71 6c 69 74 65  result if sqlite
198b0 33 5f 66 72 65 65 28 29 20 69 73 20 63 61 6c 6c  3_free() is call
198c0 65 64 20 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55  ed with a non-NU
198d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 61 74 0a  LL pointer that.
198e0 2a 2a 20 77 61 73 20 6e 6f 74 20 6f 62 74 61 69  ** was not obtai
198f0 6e 65 64 20 66 72 6f 6d 20 73 71 6c 69 74 65 33  ned from sqlite3
19900 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c  _malloc() or sql
19910 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a  ite3_realloc()..
19920 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69  **.** ^(The sqli
19930 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e  te3_realloc() in
19940 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
19950 20 74 6f 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20   to resize a.** 
19960 70 72 69 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c  prior memory all
19970 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 61 74  ocation to be at
19980 20 6c 65 61 73 74 20 4e 20 62 79 74 65 73 2c 20   least N bytes, 
19990 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
199a0 2a 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  * second paramet
199b0 65 72 2e 20 20 54 68 65 20 6d 65 6d 6f 72 79 20  er.  The memory 
199c0 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65  allocation to be
199d0 20 72 65 73 69 7a 65 64 20 69 73 20 74 68 65 20   resized is the 
199e0 66 69 72 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74  first.** paramet
199f0 65 72 2e 29 5e 20 5e 20 49 66 20 74 68 65 20 66  er.)^ ^ If the f
19a00 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74  irst parameter t
19a10 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f  o sqlite3_reallo
19a20 63 28 29 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c  c().** is a NULL
19a30 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 69 74   pointer then it
19a40 73 20 62 65 68 61 76 69 6f 72 20 69 73 20 69 64  s behavior is id
19a50 65 6e 74 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69  entical to calli
19a60 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61  ng.** sqlite3_ma
19a70 6c 6c 6f 63 28 4e 29 20 77 68 65 72 65 20 4e 20  lloc(N) where N 
19a80 69 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  is the second pa
19a90 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
19aa0 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a  e3_realloc()..**
19ab0 20 5e 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20   ^If the second 
19ac0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
19ad0 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69  ite3_realloc() i
19ae0 73 20 7a 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67  s zero or.** neg
19af0 61 74 69 76 65 20 74 68 65 6e 20 74 68 65 20 62  ative then the b
19b00 65 68 61 76 69 6f 72 20 69 73 20 65 78 61 63 74  ehavior is exact
19b10 6c 79 20 74 68 65 20 73 61 6d 65 20 61 73 20 63  ly the same as c
19b20 61 6c 6c 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65  alling.** sqlite
19b30 33 5f 66 72 65 65 28 50 29 20 77 68 65 72 65 20  3_free(P) where 
19b40 50 20 69 73 20 74 68 65 20 66 69 72 73 74 20 70  P is the first p
19b50 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
19b60 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a  te3_realloc()..*
19b70 2a 20 5e 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  * ^sqlite3_reall
19b80 6f 63 28 29 20 72 65 74 75 72 6e 73 20 61 20 70  oc() returns a p
19b90 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
19ba0 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a  ry allocation.**
19bb0 20 6f 66 20 61 74 20 6c 65 61 73 74 20 4e 20 62   of at least N b
19bc0 79 74 65 73 20 69 6e 20 73 69 7a 65 20 6f 72 20  ytes in size or 
19bd0 4e 55 4c 4c 20 69 66 20 73 75 66 66 69 63 69 65  NULL if sufficie
19be0 6e 74 20 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61  nt memory is una
19bf0 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66  vailable..** ^If
19c00 20 4d 20 69 73 20 74 68 65 20 73 69 7a 65 20 6f   M is the size o
19c10 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19c20 63 61 74 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e  cation, then min
19c30 28 4e 2c 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f  (N,M) bytes.** o
19c40 66 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f  f the prior allo
19c50 63 61 74 69 6f 6e 20 61 72 65 20 63 6f 70 69 65  cation are copie
19c60 64 20 69 6e 74 6f 20 74 68 65 20 62 65 67 69 6e  d into the begin
19c70 6e 69 6e 67 20 6f 66 20 62 75 66 66 65 72 20 72  ning of buffer r
19c80 65 74 75 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71  eturned.** by sq
19c90 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
19ca0 61 6e 64 20 74 68 65 20 70 72 69 6f 72 20 61 6c  and the prior al
19cb0 6c 6f 63 61 74 69 6f 6e 20 69 73 20 66 72 65 65  location is free
19cc0 64 2e 0a 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65  d..** ^If sqlite
19cd0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 74 75  3_realloc() retu
19ce0 72 6e 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74  rns NULL, then t
19cf0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
19d00 69 6f 6e 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72  ion.** is not fr
19d10 65 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  eed..**.** ^The 
19d20 6d 65 6d 6f 72 79 20 72 65 74 75 72 6e 65 64 20  memory returned 
19d30 62 79 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  by sqlite3_mallo
19d40 63 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  c() and sqlite3_
19d50 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20  realloc().** is 
19d60 61 6c 77 61 79 73 20 61 6c 69 67 6e 65 64 20 74  always aligned t
19d70 6f 20 61 74 20 6c 65 61 73 74 20 61 6e 20 38 20  o at least an 8 
19d80 62 79 74 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f  byte boundary, o
19d90 72 20 74 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65  r to a.** 4 byte
19da0 20 62 6f 75 6e 64 61 72 79 20 69 66 20 74 68 65   boundary if the
19db0 20 5b 53 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f   [SQLITE_4_BYTE_
19dc0 41 4c 49 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20  ALIGNED_MALLOC] 
19dd0 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20  compile-time.** 
19de0 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a  option is used..
19df0 2a 2a 0a 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20  **.** In SQLite 
19e00 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e  version 3.5.0 an
19e10 64 20 33 2e 35 2e 31 2c 20 69 74 20 77 61 73 20  d 3.5.1, it was 
19e20 70 6f 73 73 69 62 6c 65 20 74 6f 20 64 65 66 69  possible to defi
19e30 6e 65 0a 2a 2a 20 74 68 65 20 53 51 4c 49 54 45  ne.** the SQLITE
19e40 5f 4f 4d 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c  _OMIT_MEMORY_ALL
19e50 4f 43 41 54 49 4f 4e 20 77 68 69 63 68 20 77 6f  OCATION which wo
19e60 75 6c 64 20 63 61 75 73 65 20 74 68 65 20 62 75  uld cause the bu
19e70 69 6c 74 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d  ilt-in.** implem
19e80 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 73  entation of thes
19e90 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65  e routines to be
19ea0 20 6f 6d 69 74 74 65 64 2e 20 20 54 68 61 74 20   omitted.  That 
19eb0 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
19ec0 20 6e 6f 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69   no longer provi
19ed0 64 65 64 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74  ded.  Only built
19ee0 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  -in memory alloc
19ef0 61 74 6f 72 73 20 63 61 6e 20 62 65 20 75 73 65  ators can be use
19f00 64 2e 0a 2a 2a 0a 2a 2a 20 50 72 69 6f 72 20 74  d..**.** Prior t
19f10 6f 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  o SQLite version
19f20 20 33 2e 37 2e 31 30 2c 20 74 68 65 20 57 69 6e   3.7.10, the Win
19f30 64 6f 77 73 20 4f 53 20 69 6e 74 65 72 66 61 63  dows OS interfac
19f40 65 20 6c 61 79 65 72 20 63 61 6c 6c 65 64 0a 2a  e layer called.*
19f50 2a 20 74 68 65 20 73 79 73 74 65 6d 20 6d 61 6c  * the system mal
19f60 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28 29  loc() and free()
19f70 20 64 69 72 65 63 74 6c 79 20 77 68 65 6e 20 63   directly when c
19f80 6f 6e 76 65 72 74 69 6e 67 0a 2a 2a 20 66 69 6c  onverting.** fil
19f90 65 6e 61 6d 65 73 20 62 65 74 77 65 65 6e 20 74  enames between t
19fa0 68 65 20 55 54 46 2d 38 20 65 6e 63 6f 64 69 6e  he UTF-8 encodin
19fb0 67 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65  g used by SQLite
19fc0 0a 2a 2a 20 61 6e 64 20 77 68 61 74 65 76 65 72  .** and whatever
19fd0 20 66 69 6c 65 6e 61 6d 65 20 65 6e 63 6f 64 69   filename encodi
19fe0 6e 67 20 69 73 20 75 73 65 64 20 62 79 20 74 68  ng is used by th
19ff0 65 20 70 61 72 74 69 63 75 6c 61 72 20 57 69 6e  e particular Win
1a000 64 6f 77 73 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61  dows.** installa
1a010 74 69 6f 6e 2e 20 20 4d 65 6d 6f 72 79 20 61 6c  tion.  Memory al
1a020 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 73 20  location errors 
1a030 77 65 72 65 20 64 65 74 65 63 74 65 64 2c 20 62  were detected, b
1a040 75 74 0a 2a 2a 20 74 68 65 79 20 77 65 72 65 20  ut.** they were 
1a050 72 65 70 6f 72 74 65 64 20 62 61 63 6b 20 61 73  reported back as
1a060 20 5b 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45   [SQLITE_CANTOPE
1a070 4e 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  N] or.** [SQLITE
1a080 5f 49 4f 45 52 52 5d 20 72 61 74 68 65 72 20 74  _IOERR] rather t
1a090 68 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45  han [SQLITE_NOME
1a0a0 4d 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 70 6f  M]..**.** The po
1a0b0 69 6e 74 65 72 20 61 72 67 75 6d 65 6e 74 73 20  inter arguments 
1a0c0 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  to [sqlite3_free
1a0d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1a0e0 5f 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6d  _realloc()].** m
1a0f0 75 73 74 20 62 65 20 65 69 74 68 65 72 20 4e 55  ust be either NU
1a100 4c 4c 20 6f 72 20 65 6c 73 65 20 70 6f 69 6e 74  LL or else point
1a110 65 72 73 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ers obtained fro
1a120 6d 20 61 20 70 72 69 6f 72 0a 2a 2a 20 69 6e 76  m a prior.** inv
1a130 6f 63 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69  ocation of [sqli
1a140 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 6f 72  te3_malloc()] or
1a150 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
1a160 63 28 29 5d 20 74 68 61 74 20 68 61 76 65 0a 2a  c()] that have.*
1a170 2a 20 6e 6f 74 20 79 65 74 20 62 65 65 6e 20 72  * not yet been r
1a180 65 6c 65 61 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eleased..**.** T
1a190 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
1a1a0 75 73 74 20 6e 6f 74 20 72 65 61 64 20 6f 72 20  ust not read or 
1a1b0 77 72 69 74 65 20 61 6e 79 20 70 61 72 74 20 6f  write any part o
1a1c0 66 0a 2a 2a 20 61 20 62 6c 6f 63 6b 20 6f 66 20  f.** a block of 
1a1d0 6d 65 6d 6f 72 79 20 61 66 74 65 72 20 69 74 20  memory after it 
1a1e0 68 61 73 20 62 65 65 6e 20 72 65 6c 65 61 73 65  has been release
1a1f0 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  d using.** [sqli
1a200 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 72 20 5b  te3_free()] or [
1a210 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
1a220 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  )]..*/.void *sql
1a230 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 69 6e 74 29  ite3_malloc(int)
1a240 3b 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  ;.void *sqlite3_
1a250 72 65 61 6c 6c 6f 63 28 76 6f 69 64 2a 2c 20 69  realloc(void*, i
1a260 6e 74 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  nt);.void sqlite
1a270 33 5f 66 72 65 65 28 76 6f 69 64 2a 29 3b 0a 0a  3_free(void*);..
1a280 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1a290 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 6f 72  Memory Allocator
1a2a0 20 53 74 61 74 69 73 74 69 63 73 0a 2a 2a 0a 2a   Statistics.**.*
1a2b0 2a 20 53 51 4c 69 74 65 20 70 72 6f 76 69 64 65  * SQLite provide
1a2c0 73 20 74 68 65 73 65 20 74 77 6f 20 69 6e 74 65  s these two inte
1a2d0 72 66 61 63 65 73 20 66 6f 72 20 72 65 70 6f 72  rfaces for repor
1a2e0 74 69 6e 67 20 6f 6e 20 74 68 65 20 73 74 61 74  ting on the stat
1a2f0 75 73 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  us.** of the [sq
1a300 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c  lite3_malloc()],
1a310 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
1a320 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ], and [sqlite3_
1a330 72 65 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 72 6f  realloc()].** ro
1a340 75 74 69 6e 65 73 2c 20 77 68 69 63 68 20 66 6f  utines, which fo
1a350 72 6d 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 20  rm the built-in 
1a360 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
1a370 6e 20 73 75 62 73 79 73 74 65 6d 2e 0a 2a 2a 0a  n subsystem..**.
1a380 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65 33  ** ^The [sqlite3
1a390 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
1a3a0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
1a3b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
1a3c0 74 65 73 0a 2a 2a 20 6f 66 20 6d 65 6d 6f 72 79  tes.** of memory
1a3d0 20 63 75 72 72 65 6e 74 6c 79 20 6f 75 74 73 74   currently outst
1a3e0 61 6e 64 69 6e 67 20 28 6d 61 6c 6c 6f 63 65 64  anding (malloced
1a3f0 20 62 75 74 20 6e 6f 74 20 66 72 65 65 64 29 2e   but not freed).
1a400 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74 65  .** ^The [sqlite
1a410 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74  3_memory_highwat
1a420 65 72 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  er()] routine re
1a430 74 75 72 6e 73 20 74 68 65 20 6d 61 78 69 6d 75  turns the maximu
1a440 6d 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 5b 73  m.** value of [s
1a450 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
1a460 65 64 28 29 5d 20 73 69 6e 63 65 20 74 68 65 20  ed()] since the 
1a470 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b 0a  high-water mark.
1a480 2a 2a 20 77 61 73 20 6c 61 73 74 20 72 65 73 65  ** was last rese
1a490 74 2e 20 20 5e 54 68 65 20 76 61 6c 75 65 73 20  t.  ^The values 
1a4a0 72 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c  returned by [sql
1a4b0 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64  ite3_memory_used
1a4c0 28 29 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  ()] and.** [sqli
1a4d0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1a4e0 61 74 65 72 28 29 5d 20 69 6e 63 6c 75 64 65 20  ater()] include 
1a4f0 61 6e 79 20 6f 76 65 72 68 65 61 64 0a 2a 2a 20  any overhead.** 
1a500 61 64 64 65 64 20 62 79 20 53 51 4c 69 74 65 20  added by SQLite 
1a510 69 6e 20 69 74 73 20 69 6d 70 6c 65 6d 65 6e 74  in its implement
1a520 61 74 69 6f 6e 20 6f 66 20 5b 73 71 6c 69 74 65  ation of [sqlite
1a530 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2c 0a 2a 2a 20  3_malloc()],.** 
1a540 62 75 74 20 6e 6f 74 20 6f 76 65 72 68 65 61 64  but not overhead
1a550 20 61 64 64 65 64 20 62 79 20 74 68 65 20 61 6e   added by the an
1a560 79 20 75 6e 64 65 72 6c 79 69 6e 67 20 73 79 73  y underlying sys
1a570 74 65 6d 20 6c 69 62 72 61 72 79 0a 2a 2a 20 72  tem library.** r
1a580 6f 75 74 69 6e 65 73 20 74 68 61 74 20 5b 73 71  outines that [sq
1a590 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
1a5a0 6d 61 79 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  may call..**.** 
1a5b0 5e 54 68 65 20 6d 65 6d 6f 72 79 20 68 69 67 68  ^The memory high
1a5c0 2d 77 61 74 65 72 20 6d 61 72 6b 20 69 73 20 72  -water mark is r
1a5d0 65 73 65 74 20 74 6f 20 74 68 65 20 63 75 72 72  eset to the curr
1a5e0 65 6e 74 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20  ent value of.** 
1a5f0 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
1a600 75 73 65 64 28 29 5d 20 69 66 20 61 6e 64 20 6f  used()] if and o
1a610 6e 6c 79 20 69 66 20 74 68 65 20 70 61 72 61 6d  nly if the param
1a620 65 74 65 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  eter to.** [sqli
1a630 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
1a640 61 74 65 72 28 29 5d 20 69 73 20 74 72 75 65 2e  ater()] is true.
1a650 20 20 5e 54 68 65 20 76 61 6c 75 65 20 72 65 74    ^The value ret
1a660 75 72 6e 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  urned.** by [sql
1a670 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68  ite3_memory_high
1a680 77 61 74 65 72 28 31 29 5d 20 69 73 20 74 68 65  water(1)] is the
1a690 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72 6b   high-water mark
1a6a0 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20 74 68 65  .** prior to the
1a6b0 20 72 65 73 65 74 2e 0a 2a 2f 0a 73 71 6c 69 74   reset..*/.sqlit
1a6c0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
1a6d0 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 76 6f 69  _memory_used(voi
1a6e0 64 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36  d);.sqlite3_int6
1a6f0 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79  4 sqlite3_memory
1a700 5f 68 69 67 68 77 61 74 65 72 28 69 6e 74 20 72  _highwater(int r
1a710 65 73 65 74 46 6c 61 67 29 3b 0a 0a 2f 2a 0a 2a  esetFlag);../*.*
1a720 2a 20 43 41 50 49 33 52 45 46 3a 20 50 73 65 75  * CAPI3REF: Pseu
1a730 64 6f 2d 52 61 6e 64 6f 6d 20 4e 75 6d 62 65 72  do-Random Number
1a740 20 47 65 6e 65 72 61 74 6f 72 0a 2a 2a 0a 2a 2a   Generator.**.**
1a750 20 53 51 4c 69 74 65 20 63 6f 6e 74 61 69 6e 73   SQLite contains
1a760 20 61 20 68 69 67 68 2d 71 75 61 6c 69 74 79 20   a high-quality 
1a770 70 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 20 6e 75  pseudo-random nu
1a780 6d 62 65 72 20 67 65 6e 65 72 61 74 6f 72 20 28  mber generator (
1a790 50 52 4e 47 29 20 75 73 65 64 20 74 6f 0a 2a 2a  PRNG) used to.**
1a7a0 20 73 65 6c 65 63 74 20 72 61 6e 64 6f 6d 20 5b   select random [
1a7b0 52 4f 57 49 44 20 7c 20 52 4f 57 49 44 73 5d 20  ROWID | ROWIDs] 
1a7c0 77 68 65 6e 20 69 6e 73 65 72 74 69 6e 67 20 6e  when inserting n
1a7d0 65 77 20 72 65 63 6f 72 64 73 20 69 6e 74 6f 20  ew records into 
1a7e0 61 20 74 61 62 6c 65 20 74 68 61 74 0a 2a 2a 20  a table that.** 
1a7f0 61 6c 72 65 61 64 79 20 75 73 65 73 20 74 68 65  already uses the
1a800 20 6c 61 72 67 65 73 74 20 70 6f 73 73 69 62 6c   largest possibl
1a810 65 20 5b 52 4f 57 49 44 5d 2e 20 20 54 68 65 20  e [ROWID].  The 
1a820 50 52 4e 47 20 69 73 20 61 6c 73 6f 20 75 73 65  PRNG is also use
1a830 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 62 75 69  d for.** the bui
1a840 6c 64 2d 69 6e 20 72 61 6e 64 6f 6d 28 29 20 61  ld-in random() a
1a850 6e 64 20 72 61 6e 64 6f 6d 62 6c 6f 62 28 29 20  nd randomblob() 
1a860 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20  SQL functions.  
1a870 54 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61  This interface a
1a880 6c 6c 6f 77 73 0a 2a 2a 20 61 70 70 6c 69 63 61  llows.** applica
1a890 74 69 6f 6e 73 20 74 6f 20 61 63 63 65 73 73 20  tions to access 
1a8a0 74 68 65 20 73 61 6d 65 20 50 52 4e 47 20 66 6f  the same PRNG fo
1a8b0 72 20 6f 74 68 65 72 20 70 75 72 70 6f 73 65 73  r other purposes
1a8c0 2e 0a 2a 2a 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20  ..**.** ^A call 
1a8d0 74 6f 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  to this routine 
1a8e0 73 74 6f 72 65 73 20 4e 20 62 79 74 65 73 20 6f  stores N bytes o
1a8f0 66 20 72 61 6e 64 6f 6d 6e 65 73 73 20 69 6e 74  f randomness int
1a900 6f 20 62 75 66 66 65 72 20 50 2e 0a 2a 2a 0a 2a  o buffer P..**.*
1a910 2a 20 5e 54 68 65 20 66 69 72 73 74 20 74 69 6d  * ^The first tim
1a920 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 69  e this routine i
1a930 73 20 69 6e 76 6f 6b 65 64 20 28 65 69 74 68 65  s invoked (eithe
1a940 72 20 69 6e 74 65 72 6e 61 6c 6c 79 20 6f 72 20  r internally or 
1a950 62 79 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  by.** the applic
1a960 61 74 69 6f 6e 29 20 74 68 65 20 50 52 4e 47 20  ation) the PRNG 
1a970 69 73 20 73 65 65 64 65 64 20 75 73 69 6e 67 20  is seeded using 
1a980 72 61 6e 64 6f 6d 6e 65 73 73 20 6f 62 74 61 69  randomness obtai
1a990 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20  ned.** from the 
1a9a0 78 52 61 6e 64 6f 6d 6e 65 73 73 20 6d 65 74 68  xRandomness meth
1a9b0 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75 6c  od of the defaul
1a9c0 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  t [sqlite3_vfs] 
1a9d0 6f 62 6a 65 63 74 2e 0a 2a 2a 20 5e 4f 6e 20 61  object..** ^On a
1a9e0 6c 6c 20 73 75 62 73 65 71 75 65 6e 74 20 69 6e  ll subsequent in
1a9f0 76 6f 63 61 74 69 6f 6e 73 2c 20 74 68 65 20 70  vocations, the p
1aa00 73 65 75 64 6f 2d 72 61 6e 64 6f 6d 6e 65 73 73  seudo-randomness
1aa10 20 69 73 20 67 65 6e 65 72 61 74 65 64 0a 2a 2a   is generated.**
1aa20 20 69 6e 74 65 72 6e 61 6c 6c 79 20 61 6e 64 20   internally and 
1aa30 77 69 74 68 6f 75 74 20 72 65 63 6f 75 72 73 65  without recourse
1aa40 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
1aa50 5f 76 66 73 5d 20 78 52 61 6e 64 6f 6d 6e 65 73  _vfs] xRandomnes
1aa60 73 0a 2a 2a 20 6d 65 74 68 6f 64 2e 0a 2a 2f 0a  s.** method..*/.
1aa70 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 61 6e  void sqlite3_ran
1aa80 64 6f 6d 6e 65 73 73 28 69 6e 74 20 4e 2c 20 76  domness(int N, v
1aa90 6f 69 64 20 2a 50 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid *P);../*.** 
1aaa0 43 41 50 49 33 52 45 46 3a 20 43 6f 6d 70 69 6c  CAPI3REF: Compil
1aab0 65 2d 54 69 6d 65 20 41 75 74 68 6f 72 69 7a 61  e-Time Authoriza
1aac0 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a  tion Callbacks.*
1aad0 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
1aae0 6e 65 20 72 65 67 69 73 74 65 72 73 20 61 6e 20  ne registers an 
1aaf0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1ab00 61 63 6b 20 77 69 74 68 20 61 20 70 61 72 74 69  ack with a parti
1ab10 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61  cular.** [databa
1ab20 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2c 20  se connection], 
1ab30 73 75 70 70 6c 69 65 64 20 69 6e 20 74 68 65 20  supplied in the 
1ab40 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a  first argument..
1ab50 2a 2a 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a  ** ^The authoriz
1ab60 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69  er callback is i
1ab70 6e 76 6f 6b 65 64 20 61 73 20 53 51 4c 20 73 74  nvoked as SQL st
1ab80 61 74 65 6d 65 6e 74 73 20 61 72 65 20 62 65 69  atements are bei
1ab90 6e 67 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 62  ng compiled.** b
1aba0 79 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  y [sqlite3_prepa
1abb0 72 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72  re()] or its var
1abc0 69 61 6e 74 73 20 5b 73 71 6c 69 74 65 33 5f 70  iants [sqlite3_p
1abd0 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 0a 2a 2a  repare_v2()],.**
1abe0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1abf0 65 31 36 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  e16()] and [sqli
1ac00 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
1ac10 28 29 5d 2e 20 20 5e 41 74 20 76 61 72 69 6f 75  ()].  ^At variou
1ac20 73 0a 2a 2a 20 70 6f 69 6e 74 73 20 64 75 72 69  s.** points duri
1ac30 6e 67 20 74 68 65 20 63 6f 6d 70 69 6c 61 74 69  ng the compilati
1ac40 6f 6e 20 70 72 6f 63 65 73 73 2c 20 61 73 20 6c  on process, as l
1ac50 6f 67 69 63 20 69 73 20 62 65 69 6e 67 20 63 72  ogic is being cr
1ac60 65 61 74 65 64 0a 2a 2a 20 74 6f 20 70 65 72 66  eated.** to perf
1ac70 6f 72 6d 20 76 61 72 69 6f 75 73 20 61 63 74 69  orm various acti
1ac80 6f 6e 73 2c 20 74 68 65 20 61 75 74 68 6f 72 69  ons, the authori
1ac90 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  zer callback is 
1aca0 69 6e 76 6f 6b 65 64 20 74 6f 0a 2a 2a 20 73 65  invoked to.** se
1acb0 65 20 69 66 20 74 68 6f 73 65 20 61 63 74 69 6f  e if those actio
1acc0 6e 73 20 61 72 65 20 61 6c 6c 6f 77 65 64 2e 20  ns are allowed. 
1acd0 20 5e 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72   ^The authorizer
1ace0 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64   callback should
1acf0 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  .** return [SQLI
1ad00 54 45 5f 4f 4b 5d 20 74 6f 20 61 6c 6c 6f 77 20  TE_OK] to allow 
1ad10 74 68 65 20 61 63 74 69 6f 6e 2c 20 5b 53 51 4c  the action, [SQL
1ad20 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 6f 20 64  ITE_IGNORE] to d
1ad30 69 73 61 6c 6c 6f 77 20 74 68 65 0a 2a 2a 20 73  isallow the.** s
1ad40 70 65 63 69 66 69 63 20 61 63 74 69 6f 6e 20 62  pecific action b
1ad50 75 74 20 61 6c 6c 6f 77 20 74 68 65 20 53 51 4c  ut allow the SQL
1ad60 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20 63 6f   statement to co
1ad70 6e 74 69 6e 75 65 20 74 6f 20 62 65 0a 2a 2a 20  ntinue to be.** 
1ad80 63 6f 6d 70 69 6c 65 64 2c 20 6f 72 20 5b 53 51  compiled, or [SQ
1ad90 4c 49 54 45 5f 44 45 4e 59 5d 20 74 6f 20 63 61  LITE_DENY] to ca
1ada0 75 73 65 20 74 68 65 20 65 6e 74 69 72 65 20 53  use the entire S
1adb0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 6f 20  QL statement to 
1adc0 62 65 0a 2a 2a 20 72 65 6a 65 63 74 65 64 20 77  be.** rejected w
1add0 69 74 68 20 61 6e 20 65 72 72 6f 72 2e 20 20 5e  ith an error.  ^
1ade0 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  If the authorize
1adf0 72 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  r callback retur
1ae00 6e 73 0a 2a 2a 20 61 6e 79 20 76 61 6c 75 65 20  ns.** any value 
1ae10 6f 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49  other than [SQLI
1ae20 54 45 5f 49 47 4e 4f 52 45 5d 2c 20 5b 53 51 4c  TE_IGNORE], [SQL
1ae30 49 54 45 5f 4f 4b 5d 2c 20 6f 72 20 5b 53 51 4c  ITE_OK], or [SQL
1ae40 49 54 45 5f 44 45 4e 59 5d 0a 2a 2a 20 74 68 65  ITE_DENY].** the
1ae50 6e 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70  n the [sqlite3_p
1ae60 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
1ae70 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20  equivalent call 
1ae80 74 68 61 74 20 74 72 69 67 67 65 72 65 64 0a 2a  that triggered.*
1ae90 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72  * the authorizer
1aea0 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20   will fail with 
1aeb0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
1aec0 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68 65  ..**.** When the
1aed0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
1aee0 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 74  s [SQLITE_OK], t
1aef0 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 6f 70  hat means the op
1af00 65 72 61 74 69 6f 6e 0a 2a 2a 20 72 65 71 75 65  eration.** reque
1af10 73 74 65 64 20 69 73 20 6f 6b 2e 20 20 5e 57 68  sted is ok.  ^Wh
1af20 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
1af30 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
1af40 44 45 4e 59 5d 2c 20 74 68 65 0a 2a 2a 20 5b 73  DENY], the.** [s
1af50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
1af60 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65  2()] or equivale
1af70 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  nt call that tri
1af80 67 67 65 72 65 64 20 74 68 65 0a 2a 2a 20 61 75  ggered the.** au
1af90 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61  thorizer will fa
1afa0 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72  il with an error
1afb0 20 6d 65 73 73 61 67 65 20 65 78 70 6c 61 69 6e   message explain
1afc0 69 6e 67 20 74 68 61 74 0a 2a 2a 20 61 63 63 65  ing that.** acce
1afd0 73 73 20 69 73 20 64 65 6e 69 65 64 2e 20 0a 2a  ss is denied. .*
1afe0 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  *.** ^The first 
1aff0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
1b000 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
1b010 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
1b020 66 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 70  f the third.** p
1b030 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
1b040 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1b050 6f 72 69 7a 65 72 28 29 20 69 6e 74 65 72 66 61  orizer() interfa
1b060 63 65 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  ce. ^The second 
1b070 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20  parameter.** to 
1b080 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1b090 61 6e 20 69 6e 74 65 67 65 72 20 5b 53 51 4c 49  an integer [SQLI
1b0a0 54 45 5f 43 4f 50 59 20 7c 20 61 63 74 69 6f 6e  TE_COPY | action
1b0b0 20 63 6f 64 65 5d 20 74 68 61 74 20 73 70 65 63   code] that spec
1b0c0 69 66 69 65 73 0a 2a 2a 20 74 68 65 20 70 61 72  ifies.** the par
1b0d0 74 69 63 75 6c 61 72 20 61 63 74 69 6f 6e 20 74  ticular action t
1b0e0 6f 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e  o be authorized.
1b0f0 20 5e 54 68 65 20 74 68 69 72 64 20 74 68 72 6f   ^The third thro
1b100 75 67 68 20 73 69 78 74 68 20 70 61 72 61 6d 65  ugh sixth parame
1b110 74 65 72 73 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ters.** to the c
1b120 61 6c 6c 62 61 63 6b 20 61 72 65 20 7a 65 72 6f  allback are zero
1b130 2d 74 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69  -terminated stri
1b140 6e 67 73 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ngs that contain
1b150 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 64   additional.** d
1b160 65 74 61 69 6c 73 20 61 62 6f 75 74 20 74 68 65  etails about the
1b170 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 75   action to be au
1b180 74 68 6f 72 69 7a 65 64 2e 0a 2a 2a 0a 2a 2a 20  thorized..**.** 
1b190 5e 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63  ^If the action c
1b1a0 6f 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 52  ode is [SQLITE_R
1b1b0 45 41 44 5d 0a 2a 2a 20 61 6e 64 20 74 68 65 20  EAD].** and the 
1b1c0 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1b1d0 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
1b1e0 20 74 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 70 72   then the.** [pr
1b1f0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1b200 5d 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20 63  ] statement is c
1b210 6f 6e 73 74 72 75 63 74 65 64 20 74 6f 20 73 75  onstructed to su
1b220 62 73 74 69 74 75 74 65 0a 2a 2a 20 61 20 4e 55  bstitute.** a NU
1b230 4c 4c 20 76 61 6c 75 65 20 69 6e 20 70 6c 61 63  LL value in plac
1b240 65 20 6f 66 20 74 68 65 20 74 61 62 6c 65 20 63  e of the table c
1b250 6f 6c 75 6d 6e 20 74 68 61 74 20 77 6f 75 6c 64  olumn that would
1b260 20 68 61 76 65 0a 2a 2a 20 62 65 65 6e 20 72 65   have.** been re
1b270 61 64 20 69 66 20 5b 53 51 4c 49 54 45 5f 4f 4b  ad if [SQLITE_OK
1b280 5d 20 68 61 64 20 62 65 65 6e 20 72 65 74 75 72  ] had been retur
1b290 6e 65 64 2e 20 20 54 68 65 20 5b 53 51 4c 49 54  ned.  The [SQLIT
1b2a0 45 5f 49 47 4e 4f 52 45 5d 0a 2a 2a 20 72 65 74  E_IGNORE].** ret
1b2b0 75 72 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  urn can be used 
1b2c0 74 6f 20 64 65 6e 79 20 61 6e 20 75 6e 74 72 75  to deny an untru
1b2d0 73 74 65 64 20 75 73 65 72 20 61 63 63 65 73 73  sted user access
1b2e0 20 74 6f 20 69 6e 64 69 76 69 64 75 61 6c 0a 2a   to individual.*
1b2f0 2a 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 61 20 74  * columns of a t
1b300 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  able..** ^If the
1b310 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73 20   action code is 
1b320 5b 53 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 20  [SQLITE_DELETE] 
1b330 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  and the callback
1b340 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
1b350 49 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e  ITE_IGNORE] then
1b360 20 74 68 65 20 5b 44 45 4c 45 54 45 5d 20 6f 70   the [DELETE] op
1b370 65 72 61 74 69 6f 6e 20 70 72 6f 63 65 65 64 73  eration proceeds
1b380 20 62 75 74 20 74 68 65 0a 2a 2a 20 5b 74 72 75   but the.** [tru
1b390 6e 63 61 74 65 20 6f 70 74 69 6d 69 7a 61 74 69  ncate optimizati
1b3a0 6f 6e 5d 20 69 73 20 64 69 73 61 62 6c 65 64 20  on] is disabled 
1b3b0 61 6e 64 20 61 6c 6c 20 72 6f 77 73 20 61 72 65  and all rows are
1b3c0 20 64 65 6c 65 74 65 64 20 69 6e 64 69 76 69 64   deleted individ
1b3d0 75 61 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20  ually..**.** An 
1b3e0 61 75 74 68 6f 72 69 7a 65 72 20 69 73 20 75 73  authorizer is us
1b3f0 65 64 20 77 68 65 6e 20 5b 73 71 6c 69 74 65 33  ed when [sqlite3
1b400 5f 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61  _prepare | prepa
1b410 72 69 6e 67 5d 0a 2a 2a 20 53 51 4c 20 73 74 61  ring].** SQL sta
1b420 74 65 6d 65 6e 74 73 20 66 72 6f 6d 20 61 6e 20  tements from an 
1b430 75 6e 74 72 75 73 74 65 64 20 73 6f 75 72 63 65  untrusted source
1b440 2c 20 74 6f 20 65 6e 73 75 72 65 20 74 68 61 74  , to ensure that
1b450 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
1b460 6e 74 73 0a 2a 2a 20 64 6f 20 6e 6f 74 20 74 72  nts.** do not tr
1b470 79 20 74 6f 20 61 63 63 65 73 73 20 64 61 74 61  y to access data
1b480 20 74 68 65 79 20 61 72 65 20 6e 6f 74 20 61 6c   they are not al
1b490 6c 6f 77 65 64 20 74 6f 20 73 65 65 2c 20 6f 72  lowed to see, or
1b4a0 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e 6f   that they do no
1b4b0 74 0a 2a 2a 20 74 72 79 20 74 6f 20 65 78 65 63  t.** try to exec
1b4c0 75 74 65 20 6d 61 6c 69 63 69 6f 75 73 20 73 74  ute malicious st
1b4d0 61 74 65 6d 65 6e 74 73 20 74 68 61 74 20 64 61  atements that da
1b4e0 6d 61 67 65 20 74 68 65 20 64 61 74 61 62 61 73  mage the databas
1b4f0 65 2e 20 20 46 6f 72 0a 2a 2a 20 65 78 61 6d 70  e.  For.** examp
1b500 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  le, an applicati
1b510 6f 6e 20 6d 61 79 20 61 6c 6c 6f 77 20 61 20 75  on may allow a u
1b520 73 65 72 20 74 6f 20 65 6e 74 65 72 20 61 72 62  ser to enter arb
1b530 69 74 72 61 72 79 0a 2a 2a 20 53 51 4c 20 71 75  itrary.** SQL qu
1b540 65 72 69 65 73 20 66 6f 72 20 65 76 61 6c 75 61  eries for evalua
1b550 74 69 6f 6e 20 62 79 20 61 20 64 61 74 61 62 61  tion by a databa
1b560 73 65 2e 20 20 42 75 74 20 74 68 65 20 61 70 70  se.  But the app
1b570 6c 69 63 61 74 69 6f 6e 20 64 6f 65 73 0a 2a 2a  lication does.**
1b580 20 6e 6f 74 20 77 61 6e 74 20 74 68 65 20 75 73   not want the us
1b590 65 72 20 74 6f 20 62 65 20 61 62 6c 65 20 74 6f  er to be able to
1b5a0 20 6d 61 6b 65 20 61 72 62 69 74 72 61 72 79 20   make arbitrary 
1b5b0 63 68 61 6e 67 65 73 20 74 6f 20 74 68 65 0a 2a  changes to the.*
1b5c0 2a 20 64 61 74 61 62 61 73 65 2e 20 20 41 6e 20  * database.  An 
1b5d0 61 75 74 68 6f 72 69 7a 65 72 20 63 6f 75 6c 64  authorizer could
1b5e0 20 74 68 65 6e 20 62 65 20 70 75 74 20 69 6e 20   then be put in 
1b5f0 70 6c 61 63 65 20 77 68 69 6c 65 20 74 68 65 0a  place while the.
1b600 2a 2a 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ** user-entered 
1b610 53 51 4c 20 69 73 20 62 65 69 6e 67 20 5b 73 71  SQL is being [sq
1b620 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c 20  lite3_prepare | 
1b630 70 72 65 70 61 72 65 64 5d 20 74 68 61 74 0a 2a  prepared] that.*
1b640 2a 20 64 69 73 61 6c 6c 6f 77 73 20 65 76 65 72  * disallows ever
1b650 79 74 68 69 6e 67 20 65 78 63 65 70 74 20 5b 53  ything except [S
1b660 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
1b670 73 2e 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61  s..**.** Applica
1b680 74 69 6f 6e 73 20 74 68 61 74 20 6e 65 65 64 20  tions that need 
1b690 74 6f 20 70 72 6f 63 65 73 73 20 53 51 4c 20 66  to process SQL f
1b6a0 72 6f 6d 20 75 6e 74 72 75 73 74 65 64 20 73 6f  rom untrusted so
1b6b0 75 72 63 65 73 0a 2a 2a 20 6d 69 67 68 74 20 61  urces.** might a
1b6c0 6c 73 6f 20 63 6f 6e 73 69 64 65 72 20 6c 6f 77  lso consider low
1b6d0 65 72 69 6e 67 20 72 65 73 6f 75 72 63 65 20 6c  ering resource l
1b6e0 69 6d 69 74 73 20 75 73 69 6e 67 20 5b 73 71 6c  imits using [sql
1b6f0 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a 2a  ite3_limit()].**
1b700 20 61 6e 64 20 6c 69 6d 69 74 69 6e 67 20 64 61   and limiting da
1b710 74 61 62 61 73 65 20 73 69 7a 65 20 75 73 69 6e  tabase size usin
1b720 67 20 74 68 65 20 5b 6d 61 78 5f 70 61 67 65 5f  g the [max_page_
1b730 63 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 0a  count] [PRAGMA].
1b740 2a 2a 20 69 6e 20 61 64 64 69 74 69 6f 6e 20 74  ** in addition t
1b750 6f 20 75 73 69 6e 67 20 61 6e 20 61 75 74 68 6f  o using an autho
1b760 72 69 7a 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 4f  rizer..**.** ^(O
1b770 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 61 75 74  nly a single aut
1b780 68 6f 72 69 7a 65 72 20 63 61 6e 20 62 65 20 69  horizer can be i
1b790 6e 20 70 6c 61 63 65 20 6f 6e 20 61 20 64 61 74  n place on a dat
1b7a0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1b7b0 0a 2a 2a 20 61 74 20 61 20 74 69 6d 65 2e 20 20  .** at a time.  
1b7c0 45 61 63 68 20 63 61 6c 6c 20 74 6f 20 73 71 6c  Each call to sql
1b7d0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1b7e0 7a 65 72 20 6f 76 65 72 72 69 64 65 73 20 74 68  zer overrides th
1b7f0 65 0a 2a 2a 20 70 72 65 76 69 6f 75 73 20 63 61  e.** previous ca
1b800 6c 6c 2e 29 5e 20 20 5e 44 69 73 61 62 6c 65 20  ll.)^  ^Disable 
1b810 74 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 62  the authorizer b
1b820 79 20 69 6e 73 74 61 6c 6c 69 6e 67 20 61 20 4e  y installing a N
1b830 55 4c 4c 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a  ULL callback..**
1b840 20 54 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20   The authorizer 
1b850 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20 64  is disabled by d
1b860 65 66 61 75 6c 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  efault..**.** Th
1b870 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1b880 6c 62 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64  lback must not d
1b890 6f 20 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20  o anything that 
1b8a0 77 69 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74  will modify.** t
1b8b0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
1b8c0 65 63 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f  ection that invo
1b8d0 6b 65 64 20 74 68 65 20 61 75 74 68 6f 72 69 7a  ked the authoriz
1b8e0 65 72 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  er callback..** 
1b8f0 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74  Note that [sqlit
1b900 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
1b910 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74   and [sqlite3_st
1b920 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66  ep()] both modif
1b930 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62  y their.** datab
1b940 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20  ase connections 
1b950 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20  for the meaning 
1b960 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74  of "modify" in t
1b970 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a  his paragraph..*
1b980 2a 0a 2a 2a 20 5e 57 68 65 6e 20 5b 73 71 6c 69  *.** ^When [sqli
1b990 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1b9a0 5d 20 69 73 20 75 73 65 64 20 74 6f 20 70 72 65  ] is used to pre
1b9b0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1b9c0 2c 20 74 68 65 0a 2a 2a 20 73 74 61 74 65 6d 65  , the.** stateme
1b9d0 6e 74 20 6d 69 67 68 74 20 62 65 20 72 65 2d 70  nt might be re-p
1b9e0 72 65 70 61 72 65 64 20 64 75 72 69 6e 67 20 5b  repared during [
1b9f0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1ba00 64 75 65 20 74 6f 20 61 20 0a 2a 2a 20 73 63 68  due to a .** sch
1ba10 65 6d 61 20 63 68 61 6e 67 65 2e 20 20 48 65 6e  ema change.  Hen
1ba20 63 65 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74  ce, the applicat
1ba30 69 6f 6e 20 73 68 6f 75 6c 64 20 65 6e 73 75 72  ion should ensur
1ba40 65 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 63 6f  e that the.** co
1ba50 72 72 65 63 74 20 61 75 74 68 6f 72 69 7a 65 72  rrect authorizer
1ba60 20 63 61 6c 6c 62 61 63 6b 20 72 65 6d 61 69 6e   callback remain
1ba70 73 20 69 6e 20 70 6c 61 63 65 20 64 75 72 69 6e  s in place durin
1ba80 67 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  g the [sqlite3_s
1ba90 74 65 70 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 4e  tep()]..**.** ^N
1baa0 6f 74 65 20 74 68 61 74 20 74 68 65 20 61 75 74  ote that the aut
1bab0 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1bac0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 6c 79   is invoked only
1bad0 20 64 75 72 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69   during.** [sqli
1bae0 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
1baf0 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e 20  r its variants. 
1bb00 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 69   Authorization i
1bb10 73 20 6e 6f 74 0a 2a 2a 20 70 65 72 66 6f 72 6d  s not.** perform
1bb20 65 64 20 64 75 72 69 6e 67 20 73 74 61 74 65 6d  ed during statem
1bb30 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 69  ent evaluation i
1bb40 6e 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  n [sqlite3_step(
1bb50 29 5d 2c 20 75 6e 6c 65 73 73 0a 2a 2a 20 61 73  )], unless.** as
1bb60 20 73 74 61 74 65 64 20 69 6e 20 74 68 65 20 70   stated in the p
1bb70 72 65 76 69 6f 75 73 20 70 61 72 61 67 72 61 70  revious paragrap
1bb80 68 2c 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  h, sqlite3_step(
1bb90 29 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20 73 71 6c  ) invokes.** sql
1bba0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1bbb0 29 20 74 6f 20 72 65 70 72 65 70 61 72 65 20 61  ) to reprepare a
1bbc0 20 73 74 61 74 65 6d 65 6e 74 20 61 66 74 65 72   statement after
1bbd0 20 61 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65   a schema change
1bbe0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
1bbf0 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28  _set_authorizer(
1bc00 0a 20 20 73 71 6c 69 74 65 33 2a 2c 0a 20 20 69  .  sqlite3*,.  i
1bc10 6e 74 20 28 2a 78 41 75 74 68 29 28 76 6f 69 64  nt (*xAuth)(void
1bc20 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68 61 72  *,int,const char
1bc30 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f  *,const char*,co
1bc40 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20  nst char*,const 
1bc50 63 68 61 72 2a 29 2c 0a 20 20 76 6f 69 64 20 2a  char*),.  void *
1bc60 70 55 73 65 72 44 61 74 61 0a 29 3b 0a 0a 2f 2a  pUserData.);../*
1bc70 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75  .** CAPI3REF: Au
1bc80 74 68 6f 72 69 7a 65 72 20 52 65 74 75 72 6e 20  thorizer Return 
1bc90 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Codes.**.** The 
1bca0 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74  [sqlite3_set_aut
1bcb0 68 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72  horizer | author
1bcc0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  izer callback fu
1bcd0 6e 63 74 69 6f 6e 5d 20 6d 75 73 74 0a 2a 2a 20  nction] must.** 
1bce0 72 65 74 75 72 6e 20 65 69 74 68 65 72 20 5b 53  return either [S
1bcf0 51 4c 49 54 45 5f 4f 4b 5d 20 6f 72 20 6f 6e 65  QLITE_OK] or one
1bd00 20 6f 66 20 74 68 65 73 65 20 74 77 6f 20 63 6f   of these two co
1bd10 6e 73 74 61 6e 74 73 20 69 6e 20 6f 72 64 65 72  nstants in order
1bd20 0a 2a 2a 20 74 6f 20 73 69 67 6e 61 6c 20 53 51  .** to signal SQ
1bd30 4c 69 74 65 20 77 68 65 74 68 65 72 20 6f 72 20  Lite whether or 
1bd40 6e 6f 74 20 74 68 65 20 61 63 74 69 6f 6e 20 69  not the action i
1bd50 73 20 70 65 72 6d 69 74 74 65 64 2e 20 20 53 65  s permitted.  Se
1bd60 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  e the.** [sqlite
1bd70 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
1bd80 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 64 6f   | authorizer do
1bd90 63 75 6d 65 6e 74 61 74 69 6f 6e 5d 20 66 6f 72  cumentation] for
1bda0 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1bdb0 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1bdc0 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c 49  * Note that SQLI
1bdd0 54 45 5f 49 47 4e 4f 52 45 20 69 73 20 61 6c 73  TE_IGNORE is als
1bde0 6f 20 75 73 65 64 20 61 73 20 61 20 5b 53 51 4c  o used as a [SQL
1bdf0 49 54 45 5f 52 4f 4c 4c 42 41 43 4b 20 7c 20 72  ITE_ROLLBACK | r
1be00 65 74 75 72 6e 20 63 6f 64 65 5d 0a 2a 2a 20 66  eturn code].** f
1be10 72 6f 6d 20 74 68 65 20 5b 73 71 6c 69 74 65 33  rom the [sqlite3
1be20 5f 76 74 61 62 5f 6f 6e 5f 63 6f 6e 66 6c 69 63  _vtab_on_conflic
1be30 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  t()] interface..
1be40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1be50 45 5f 44 45 4e 59 20 20 20 31 20 20 20 2f 2a 20  E_DENY   1   /* 
1be60 41 62 6f 72 74 20 74 68 65 20 53 51 4c 20 73 74  Abort the SQL st
1be70 61 74 65 6d 65 6e 74 20 77 69 74 68 20 61 6e 20  atement with an 
1be80 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69 6e 65  error */.#define
1be90 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20 32   SQLITE_IGNORE 2
1bea0 20 20 20 2f 2a 20 44 6f 6e 27 74 20 61 6c 6c 6f     /* Don't allo
1beb0 77 20 61 63 63 65 73 73 2c 20 62 75 74 20 64 6f  w access, but do
1bec0 6e 27 74 20 67 65 6e 65 72 61 74 65 20 61 6e 20  n't generate an 
1bed0 65 72 72 6f 72 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20  error */../*.** 
1bee0 43 41 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72  CAPI3REF: Author
1bef0 69 7a 65 72 20 41 63 74 69 6f 6e 20 43 6f 64 65  izer Action Code
1bf00 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c  s.**.** The [sql
1bf10 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
1bf20 7a 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65  zer()] interface
1bf30 20 72 65 67 69 73 74 65 72 73 20 61 20 63 61 6c   registers a cal
1bf40 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a  lback function.*
1bf50 2a 20 74 68 61 74 20 69 73 20 69 6e 76 6f 6b 65  * that is invoke
1bf60 64 20 74 6f 20 61 75 74 68 6f 72 69 7a 65 20 63  d to authorize c
1bf70 65 72 74 61 69 6e 20 53 51 4c 20 73 74 61 74 65  ertain SQL state
1bf80 6d 65 6e 74 20 61 63 74 69 6f 6e 73 2e 20 20 54  ment actions.  T
1bf90 68 65 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72  he.** second par
1bfa0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63 61  ameter to the ca
1bfb0 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
1bfc0 65 67 65 72 20 63 6f 64 65 20 74 68 61 74 20 73  eger code that s
1bfd0 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 61 74  pecifies.** what
1bfe0 20 61 63 74 69 6f 6e 20 69 73 20 62 65 69 6e 67   action is being
1bff0 20 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68   authorized.  Th
1c000 65 73 65 20 61 72 65 20 74 68 65 20 69 6e 74 65  ese are the inte
1c010 67 65 72 20 61 63 74 69 6f 6e 20 63 6f 64 65 73  ger action codes
1c020 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 61 75 74   that.** the aut
1c030 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
1c040 20 6d 61 79 20 62 65 20 70 61 73 73 65 64 2e 0a   may be passed..
1c050 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 61 63 74 69  **.** These acti
1c060 6f 6e 20 63 6f 64 65 20 76 61 6c 75 65 73 20 73  on code values s
1c070 69 67 6e 69 66 79 20 77 68 61 74 20 6b 69 6e 64  ignify what kind
1c080 20 6f 66 20 6f 70 65 72 61 74 69 6f 6e 20 69 73   of operation is
1c090 20 74 6f 20 62 65 0a 2a 2a 20 61 75 74 68 6f 72   to be.** author
1c0a0 69 7a 65 64 2e 20 20 54 68 65 20 33 72 64 20 61  ized.  The 3rd a
1c0b0 6e 64 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  nd 4th parameter
1c0c0 73 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69  s to the authori
1c0d0 7a 61 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62 61  zation.** callba
1c0e0 63 6b 20 66 75 6e 63 74 69 6f 6e 20 77 69 6c 6c  ck function will
1c0f0 20 62 65 20 70 61 72 61 6d 65 74 65 72 73 20 6f   be parameters o
1c100 72 20 4e 55 4c 4c 20 64 65 70 65 6e 64 69 6e 67  r NULL depending
1c110 20 6f 6e 20 77 68 69 63 68 20 6f 66 20 74 68 65   on which of the
1c120 73 65 0a 2a 2a 20 63 6f 64 65 73 20 69 73 20 75  se.** codes is u
1c130 73 65 64 20 61 73 20 74 68 65 20 73 65 63 6f 6e  sed as the secon
1c140 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 28  d parameter.  ^(
1c150 54 68 65 20 35 74 68 20 70 61 72 61 6d 65 74 65  The 5th paramete
1c160 72 20 74 6f 20 74 68 65 0a 2a 2a 20 61 75 74 68  r to the.** auth
1c170 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1c180 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  is the name of t
1c190 68 65 20 64 61 74 61 62 61 73 65 20 28 22 6d 61  he database ("ma
1c1a0 69 6e 22 2c 20 22 74 65 6d 70 22 2c 0a 2a 2a 20  in", "temp",.** 
1c1b0 65 74 63 2e 29 20 69 66 20 61 70 70 6c 69 63 61  etc.) if applica
1c1c0 62 6c 65 2e 29 5e 20 20 5e 54 68 65 20 36 74 68  ble.)^  ^The 6th
1c1d0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
1c1e0 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
1c1f0 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 74 68 65 20  lback.** is the 
1c200 6e 61 6d 65 20 6f 66 20 74 68 65 20 69 6e 6e 65  name of the inne
1c210 72 2d 6d 6f 73 74 20 74 72 69 67 67 65 72 20 6f  r-most trigger o
1c220 72 20 76 69 65 77 20 74 68 61 74 20 69 73 20 72  r view that is r
1c230 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72 0a 2a  esponsible for.*
1c240 2a 20 74 68 65 20 61 63 63 65 73 73 20 61 74 74  * the access att
1c250 65 6d 70 74 20 6f 72 20 4e 55 4c 4c 20 69 66 20  empt or NULL if 
1c260 74 68 69 73 20 61 63 63 65 73 73 20 61 74 74 65  this access atte
1c270 6d 70 74 20 69 73 20 64 69 72 65 63 74 6c 79 20  mpt is directly 
1c280 66 72 6f 6d 0a 2a 2a 20 74 6f 70 2d 6c 65 76 65  from.** top-leve
1c290 6c 20 53 51 4c 20 63 6f 64 65 2e 0a 2a 2f 0a 2f  l SQL code..*/./
1c2a0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c2b0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1c2c0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 33 72 64 20  *********** 3rd 
1c2d0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 20 34 74 68  ************ 4th
1c2e0 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2f 0a 23 64   ***********/.#d
1c2f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1c300 41 54 45 5f 49 4e 44 45 58 20 20 20 20 20 20 20  ATE_INDEX       
1c310 20 20 20 31 20 20 20 2f 2a 20 49 6e 64 65 78 20     1   /* Index 
1c320 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20  Name      Table 
1c330 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1c340 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1c350 54 45 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20  TE_TABLE        
1c360 20 20 32 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e    2   /* Table N
1c370 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c380 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c390 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1c3a0 45 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20  E_TEMP_INDEX    
1c3b0 20 33 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61   3   /* Index Na
1c3c0 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61  me      Table Na
1c3d0 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  me      */.#defi
1c3e0 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45  ne SQLITE_CREATE
1c3f0 5f 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20  _TEMP_TABLE     
1c400 34 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  4   /* Table Nam
1c410 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20  e      NULL     
1c420 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e         */.#defin
1c430 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f  e SQLITE_CREATE_
1c440 54 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 35  TEMP_TRIGGER   5
1c450 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61     /* Trigger Na
1c460 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65  me    Table Name
1c470 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c480 20 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54   SQLITE_CREATE_T
1c490 45 4d 50 5f 56 49 45 57 20 20 20 20 20 20 36 20  EMP_VIEW      6 
1c4a0 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20    /* View Name  
1c4b0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c4c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c4d0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 52  SQLITE_CREATE_TR
1c4e0 49 47 47 45 52 20 20 20 20 20 20 20 20 37 20 20  IGGER        7  
1c4f0 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65   /* Trigger Name
1c500 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1c510 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1c520 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 49 45  QLITE_CREATE_VIE
1c530 57 20 20 20 20 20 20 20 20 20 20 20 38 20 20 20  W           8   
1c540 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20  /* View Name    
1c550 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1c560 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1c570 4c 49 54 45 5f 44 45 4c 45 54 45 20 20 20 20 20  LITE_DELETE     
1c580 20 20 20 20 20 20 20 20 20 20 20 39 20 20 20 2f             9   /
1c590 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20  * Table Name    
1c5a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1c5b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1c5c0 49 54 45 5f 44 52 4f 50 5f 49 4e 44 45 58 20 20  ITE_DROP_INDEX  
1c5d0 20 20 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a           10   /*
1c5e0 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20   Index Name     
1c5f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1c600 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1c610 54 45 5f 44 52 4f 50 5f 54 41 42 4c 45 20 20 20  TE_DROP_TABLE   
1c620 20 20 20 20 20 20 20 20 31 31 20 20 20 2f 2a 20          11   /* 
1c630 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1c640 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1c650 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1c660 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 49 4e 44 45  E_DROP_TEMP_INDE
1c670 58 20 20 20 20 20 20 31 32 20 20 20 2f 2a 20 49  X      12   /* I
1c680 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54  ndex Name      T
1c690 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a  able Name      *
1c6a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1c6b0 5f 44 52 4f 50 5f 54 45 4d 50 5f 54 41 42 4c 45  _DROP_TEMP_TABLE
1c6c0 20 20 20 20 20 20 31 33 20 20 20 2f 2a 20 54 61        13   /* Ta
1c6d0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55  ble Name      NU
1c6e0 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f  LL            */
1c6f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1c700 44 52 4f 50 5f 54 45 4d 50 5f 54 52 49 47 47 45  DROP_TEMP_TRIGGE
1c710 52 20 20 20 20 31 34 20 20 20 2f 2a 20 54 72 69  R    14   /* Tri
1c720 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62  gger Name    Tab
1c730 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a  le Name      */.
1c740 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1c750 52 4f 50 5f 54 45 4d 50 5f 56 49 45 57 20 20 20  ROP_TEMP_VIEW   
1c760 20 20 20 20 31 35 20 20 20 2f 2a 20 56 69 65 77      15   /* View
1c770 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c   Name       NULL
1c780 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1c790 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1c7a0 4f 50 5f 54 52 49 47 47 45 52 20 20 20 20 20 20  OP_TRIGGER      
1c7b0 20 20 20 31 36 20 20 20 2f 2a 20 54 72 69 67 67     16   /* Trigg
1c7c0 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65  er Name    Table
1c7d0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1c7e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1c7f0 50 5f 56 49 45 57 20 20 20 20 20 20 20 20 20 20  P_VIEW          
1c800 20 20 31 37 20 20 20 2f 2a 20 56 69 65 77 20 4e    17   /* View N
1c810 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20  ame       NULL  
1c820 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1c830 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 53 45  fine SQLITE_INSE
1c840 52 54 20 20 20 20 20 20 20 20 20 20 20 20 20 20  RT              
1c850 20 31 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   18   /* Table N
1c860 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1c870 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1c880 69 6e 65 20 53 51 4c 49 54 45 5f 50 52 41 47 4d  ine SQLITE_PRAGM
1c890 41 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  A               
1c8a0 31 39 20 20 20 2f 2a 20 50 72 61 67 6d 61 20 4e  19   /* Pragma N
1c8b0 61 6d 65 20 20 20 20 20 31 73 74 20 61 72 67 20  ame     1st arg 
1c8c0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 23 64 65 66 69  or NULL */.#defi
1c8d0 6e 65 20 53 51 4c 49 54 45 5f 52 45 41 44 20 20  ne SQLITE_READ  
1c8e0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32                 2
1c8f0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1c900 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61  e      Column Na
1c910 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1c920 65 20 53 51 4c 49 54 45 5f 53 45 4c 45 43 54 20  e SQLITE_SELECT 
1c930 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 31                21
1c940 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1c950 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1c960 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1c970 20 53 51 4c 49 54 45 5f 54 52 41 4e 53 41 43 54   SQLITE_TRANSACT
1c980 49 4f 4e 20 20 20 20 20 20 20 20 20 20 32 32 20  ION          22 
1c990 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1c9a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1c9b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1c9c0 53 51 4c 49 54 45 5f 55 50 44 41 54 45 20 20 20  SQLITE_UPDATE   
1c9d0 20 20 20 20 20 20 20 20 20 20 20 20 32 33 20 20              23  
1c9e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1c9f0 20 20 20 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20      Column Name 
1ca00 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1ca10 51 4c 49 54 45 5f 41 54 54 41 43 48 20 20 20 20  QLITE_ATTACH    
1ca20 20 20 20 20 20 20 20 20 20 20 20 32 34 20 20 20             24   
1ca30 2f 2a 20 46 69 6c 65 6e 61 6d 65 20 20 20 20 20  /* Filename     
1ca40 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ca50 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ca60 4c 49 54 45 5f 44 45 54 41 43 48 20 20 20 20 20  LITE_DETACH     
1ca70 20 20 20 20 20 20 20 20 20 20 32 35 20 20 20 2f            25   /
1ca80 2a 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20  * Database Name 
1ca90 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1caa0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1cab0 49 54 45 5f 41 4c 54 45 52 5f 54 41 42 4c 45 20  ITE_ALTER_TABLE 
1cac0 20 20 20 20 20 20 20 20 20 32 36 20 20 20 2f 2a           26   /*
1cad0 20 44 61 74 61 62 61 73 65 20 4e 61 6d 65 20 20   Database Name  
1cae0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1caf0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1cb00 54 45 5f 52 45 49 4e 44 45 58 20 20 20 20 20 20  TE_REINDEX      
1cb10 20 20 20 20 20 20 20 20 32 37 20 20 20 2f 2a 20          27   /* 
1cb20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1cb30 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1cb40 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1cb50 45 5f 41 4e 41 4c 59 5a 45 20 20 20 20 20 20 20  E_ANALYZE       
1cb60 20 20 20 20 20 20 20 32 38 20 20 20 2f 2a 20 54         28   /* T
1cb70 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1cb80 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1cb90 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1cba0 5f 43 52 45 41 54 45 5f 56 54 41 42 4c 45 20 20  _CREATE_VTABLE  
1cbb0 20 20 20 20 20 20 32 39 20 20 20 2f 2a 20 54 61        29   /* Ta
1cbc0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f  ble Name      Mo
1cbd0 64 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f  dule Name     */
1cbe0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1cbf0 44 52 4f 50 5f 56 54 41 42 4c 45 20 20 20 20 20  DROP_VTABLE     
1cc00 20 20 20 20 20 33 30 20 20 20 2f 2a 20 54 61 62       30   /* Tab
1cc10 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4d 6f 64  le Name      Mod
1cc20 75 6c 65 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  ule Name     */.
1cc30 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
1cc40 55 4e 43 54 49 4f 4e 20 20 20 20 20 20 20 20 20  UNCTION         
1cc50 20 20 20 20 33 31 20 20 20 2f 2a 20 4e 55 4c 4c      31   /* NULL
1cc60 20 20 20 20 20 20 20 20 20 20 20 20 46 75 6e 63              Func
1cc70 74 69 6f 6e 20 4e 61 6d 65 20 20 20 2a 2f 0a 23  tion Name   */.#
1cc80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 41  define SQLITE_SA
1cc90 56 45 50 4f 49 4e 54 20 20 20 20 20 20 20 20 20  VEPOINT         
1cca0 20 20 20 33 32 20 20 20 2f 2a 20 4f 70 65 72 61     32   /* Opera
1ccb0 74 69 6f 6e 20 20 20 20 20 20 20 53 61 76 65 70  tion       Savep
1ccc0 6f 69 6e 74 20 4e 61 6d 65 20 20 2a 2f 0a 23 64  oint Name  */.#d
1ccd0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 50  efine SQLITE_COP
1cce0 59 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  Y               
1ccf0 20 20 20 30 20 20 20 2f 2a 20 4e 6f 20 6c 6f 6e     0   /* No lon
1cd00 67 65 72 20 75 73 65 64 20 2a 2f 0a 0a 2f 2a 0a  ger used */../*.
1cd10 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 72 61  ** CAPI3REF: Tra
1cd20 63 69 6e 67 20 41 6e 64 20 50 72 6f 66 69 6c 69  cing And Profili
1cd30 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
1cd40 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
1cd50 73 20 72 65 67 69 73 74 65 72 20 63 61 6c 6c 62  s register callb
1cd60 61 63 6b 20 66 75 6e 63 74 69 6f 6e 73 20 74 68  ack functions th
1cd70 61 74 20 63 61 6e 20 62 65 20 75 73 65 64 20 66  at can be used f
1cd80 6f 72 0a 2a 2a 20 74 72 61 63 69 6e 67 20 61 6e  or.** tracing an
1cd90 64 20 70 72 6f 66 69 6c 69 6e 67 20 74 68 65 20  d profiling the 
1cda0 65 78 65 63 75 74 69 6f 6e 20 6f 66 20 53 51 4c  execution of SQL
1cdb0 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
1cdc0 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b  ** ^The callback
1cdd0 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73 74   function regist
1cde0 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ered by sqlite3_
1cdf0 74 72 61 63 65 28 29 20 69 73 20 69 6e 76 6f 6b  trace() is invok
1ce00 65 64 20 61 74 0a 2a 2a 20 76 61 72 69 6f 75 73  ed at.** various
1ce10 20 74 69 6d 65 73 20 77 68 65 6e 20 61 6e 20 53   times when an S
1ce20 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  QL statement is 
1ce30 62 65 69 6e 67 20 72 75 6e 20 62 79 20 5b 73 71  being run by [sq
1ce40 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a  lite3_step()]..*
1ce50 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
1ce60 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b 20  race() callback 
1ce70 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20  is invoked with 
1ce80 61 20 55 54 46 2d 38 20 72 65 6e 64 65 72 69 6e  a UTF-8 renderin
1ce90 67 20 6f 66 20 74 68 65 0a 2a 2a 20 53 51 4c 20  g of the.** SQL 
1cea0 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61  statement text a
1ceb0 73 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  s the statement 
1cec0 66 69 72 73 74 20 62 65 67 69 6e 73 20 65 78 65  first begins exe
1ced0 63 75 74 69 6e 67 2e 0a 2a 2a 20 5e 28 41 64 64  cuting..** ^(Add
1cee0 69 74 69 6f 6e 61 6c 20 73 71 6c 69 74 65 33 5f  itional sqlite3_
1cef0 74 72 61 63 65 28 29 20 63 61 6c 6c 62 61 63 6b  trace() callback
1cf00 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a 2a  s might occur.**
1cf10 20 61 73 20 65 61 63 68 20 74 72 69 67 67 65 72   as each trigger
1cf20 65 64 20 73 75 62 70 72 6f 67 72 61 6d 20 69 73  ed subprogram is
1cf30 20 65 6e 74 65 72 65 64 2e 20 20 54 68 65 20 63   entered.  The c
1cf40 61 6c 6c 62 61 63 6b 73 20 66 6f 72 20 74 72 69  allbacks for tri
1cf50 67 67 65 72 73 0a 2a 2a 20 63 6f 6e 74 61 69 6e  ggers.** contain
1cf60 20 61 20 55 54 46 2d 38 20 53 51 4c 20 63 6f 6d   a UTF-8 SQL com
1cf70 6d 65 6e 74 20 74 68 61 74 20 69 64 65 6e 74 69  ment that identi
1cf80 66 69 65 73 20 74 68 65 20 74 72 69 67 67 65 72  fies the trigger
1cf90 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  .)^.**.** ^The c
1cfa0 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1cfb0 20 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73   registered by s
1cfc0 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65 28 29  qlite3_profile()
1cfd0 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 61   is invoked.** a
1cfe0 73 20 65 61 63 68 20 53 51 4c 20 73 74 61 74 65  s each SQL state
1cff0 6d 65 6e 74 20 66 69 6e 69 73 68 65 73 2e 20 20  ment finishes.  
1d000 5e 54 68 65 20 70 72 6f 66 69 6c 65 20 63 61 6c  ^The profile cal
1d010 6c 62 61 63 6b 20 63 6f 6e 74 61 69 6e 73 0a 2a  lback contains.*
1d020 2a 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  * the original s
1d030 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 61 6e  tatement text an
1d040 64 20 61 6e 20 65 73 74 69 6d 61 74 65 20 6f 66  d an estimate of
1d050 20 77 61 6c 6c 2d 63 6c 6f 63 6b 20 74 69 6d 65   wall-clock time
1d060 0a 2a 2a 20 6f 66 20 68 6f 77 20 6c 6f 6e 67 20  .** of how long 
1d070 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74 20 74  that statement t
1d080 6f 6f 6b 20 74 6f 20 72 75 6e 2e 20 20 5e 54 68  ook to run.  ^Th
1d090 65 20 70 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61  e profile callba
1d0a0 63 6b 0a 2a 2a 20 74 69 6d 65 20 69 73 20 69 6e  ck.** time is in
1d0b0 20 75 6e 69 74 73 20 6f 66 20 6e 61 6e 6f 73 65   units of nanose
1d0c0 63 6f 6e 64 73 2c 20 68 6f 77 65 76 65 72 20 74  conds, however t
1d0d0 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c 65  he current imple
1d0e0 6d 65 6e 74 61 74 69 6f 6e 0a 2a 2a 20 69 73 20  mentation.** is 
1d0f0 6f 6e 6c 79 20 63 61 70 61 62 6c 65 20 6f 66 20  only capable of 
1d100 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 72 65 73 6f  millisecond reso
1d110 6c 75 74 69 6f 6e 20 73 6f 20 74 68 65 20 73 69  lution so the si
1d120 78 20 6c 65 61 73 74 20 73 69 67 6e 69 66 69 63  x least signific
1d130 61 6e 74 0a 2a 2a 20 64 69 67 69 74 73 20 69 6e  ant.** digits in
1d140 20 74 68 65 20 74 69 6d 65 20 61 72 65 20 6d 65   the time are me
1d150 61 6e 69 6e 67 6c 65 73 73 2e 20 20 46 75 74 75  aningless.  Futu
1d160 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53  re versions of S
1d170 51 4c 69 74 65 0a 2a 2a 20 6d 69 67 68 74 20 70  QLite.** might p
1d180 72 6f 76 69 64 65 20 67 72 65 61 74 65 72 20 72  rovide greater r
1d190 65 73 6f 6c 75 74 69 6f 6e 20 6f 6e 20 74 68 65  esolution on the
1d1a0 20 70 72 6f 66 69 6c 65 72 20 63 61 6c 6c 62 61   profiler callba
1d1b0 63 6b 2e 20 20 54 68 65 0a 2a 2a 20 73 71 6c 69  ck.  The.** sqli
1d1c0 74 65 33 5f 70 72 6f 66 69 6c 65 28 29 20 66 75  te3_profile() fu
1d1d0 6e 63 74 69 6f 6e 20 69 73 20 63 6f 6e 73 69 64  nction is consid
1d1e0 65 72 65 64 20 65 78 70 65 72 69 6d 65 6e 74 61  ered experimenta
1d1f0 6c 20 61 6e 64 20 69 73 0a 2a 2a 20 73 75 62 6a  l and is.** subj
1d200 65 63 74 20 74 6f 20 63 68 61 6e 67 65 20 69 6e  ect to change in
1d210 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
1d220 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 76   of SQLite..*/.v
1d230 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 74 72 61  oid *sqlite3_tra
1d240 63 65 28 73 71 6c 69 74 65 33 2a 2c 20 76 6f 69  ce(sqlite3*, voi
1d250 64 28 2a 78 54 72 61 63 65 29 28 76 6f 69 64 2a  d(*xTrace)(void*
1d260 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 20 76  ,const char*), v
1d270 6f 69 64 2a 29 3b 0a 53 51 4c 49 54 45 5f 45 58  oid*);.SQLITE_EX
1d280 50 45 52 49 4d 45 4e 54 41 4c 20 76 6f 69 64 20  PERIMENTAL void 
1d290 2a 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c 65  *sqlite3_profile
1d2a0 28 73 71 6c 69 74 65 33 2a 2c 0a 20 20 20 76 6f  (sqlite3*,.   vo
1d2b0 69 64 28 2a 78 50 72 6f 66 69 6c 65 29 28 76 6f  id(*xProfile)(vo
1d2c0 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  id*,const char*,
1d2d0 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34 29 2c  sqlite3_uint64),
1d2e0 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20   void*);../*.** 
1d2f0 43 41 50 49 33 52 45 46 3a 20 51 75 65 72 79 20  CAPI3REF: Query 
1d300 50 72 6f 67 72 65 73 73 20 43 61 6c 6c 62 61 63  Progress Callbac
1d310 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ks.**.** ^The sq
1d320 6c 69 74 65 33 5f 70 72 6f 67 72 65 73 73 5f 68  lite3_progress_h
1d330 61 6e 64 6c 65 72 28 44 2c 4e 2c 58 2c 50 29 20  andler(D,N,X,P) 
1d340 69 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73  interface causes
1d350 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a   the callback.**
1d360 20 66 75 6e 63 74 69 6f 6e 20 58 20 74 6f 20 62   function X to b
1d370 65 20 69 6e 76 6f 6b 65 64 20 70 65 72 69 6f 64  e invoked period
1d380 69 63 61 6c 6c 79 20 64 75 72 69 6e 67 20 6c 6f  ically during lo
1d390 6e 67 20 72 75 6e 6e 69 6e 67 20 63 61 6c 6c 73  ng running calls
1d3a0 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   to.** [sqlite3_
1d3b0 65 78 65 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65  exec()], [sqlite
1d3c0 33 5f 73 74 65 70 28 29 5d 20 61 6e 64 20 5b 73  3_step()] and [s
1d3d0 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65  qlite3_get_table
1d3e0 28 29 5d 20 66 6f 72 0a 2a 2a 20 64 61 74 61 62  ()] for.** datab
1d3f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44  ase connection D
1d400 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 75 73  .  An example us
1d410 65 20 66 6f 72 20 74 68 69 73 0a 2a 2a 20 69 6e  e for this.** in
1d420 74 65 72 66 61 63 65 20 69 73 20 74 6f 20 6b 65  terface is to ke
1d430 65 70 20 61 20 47 55 49 20 75 70 64 61 74 65 64  ep a GUI updated
1d440 20 64 75 72 69 6e 67 20 61 20 6c 61 72 67 65 20   during a large 
1d450 71 75 65 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  query..**.** ^Th
1d460 65 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73  e parameter P is
1d470 20 70 61 73 73 65 64 20 74 68 72 6f 75 67 68 20   passed through 
1d480 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61 72 61  as the only para
1d490 6d 65 74 65 72 20 74 6f 20 74 68 65 20 0a 2a 2a  meter to the .**
1d4a0 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1d4b0 6f 6e 20 58 2e 20 20 5e 54 68 65 20 70 61 72 61  on X.  ^The para
1d4c0 6d 65 74 65 72 20 4e 20 69 73 20 74 68 65 20 6e  meter N is the n
1d4d0 75 6d 62 65 72 20 6f 66 20 0a 2a 2a 20 5b 76 69  umber of .** [vi
1d4e0 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 6e  rtual machine in
1d4f0 73 74 72 75 63 74 69 6f 6e 73 5d 20 74 68 61 74  structions] that
1d500 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20 62   are evaluated b
1d510 65 74 77 65 65 6e 20 73 75 63 63 65 73 73 69 76  etween successiv
1d520 65 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 73  e.** invocations
1d530 20 6f 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   of the callback
1d540 20 58 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 6c 79 20   X..**.** ^Only 
1d550 61 20 73 69 6e 67 6c 65 20 70 72 6f 67 72 65 73  a single progres
1d560 73 20 68 61 6e 64 6c 65 72 20 6d 61 79 20 62 65  s handler may be
1d570 20 64 65 66 69 6e 65 64 20 61 74 20 6f 6e 65 20   defined at one 
1d580 74 69 6d 65 20 70 65 72 0a 2a 2a 20 5b 64 61 74  time per.** [dat
1d590 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1d5a0 5d 3b 20 73 65 74 74 69 6e 67 20 61 20 6e 65 77  ]; setting a new
1d5b0 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65   progress handle
1d5c0 72 20 63 61 6e 63 65 6c 73 20 74 68 65 0a 2a 2a  r cancels the.**
1d5d0 20 6f 6c 64 20 6f 6e 65 2e 20 20 5e 53 65 74 74   old one.  ^Sett
1d5e0 69 6e 67 20 70 61 72 61 6d 65 74 65 72 20 58 20  ing parameter X 
1d5f0 74 6f 20 4e 55 4c 4c 20 64 69 73 61 62 6c 65 73  to NULL disables
1d600 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68 61   the progress ha
1d610 6e 64 6c 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 70  ndler..** ^The p
1d620 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1d630 69 73 20 61 6c 73 6f 20 64 69 73 61 62 6c 65 64  is also disabled
1d640 20 62 79 20 73 65 74 74 69 6e 67 20 4e 20 74 6f   by setting N to
1d650 20 61 20 76 61 6c 75 65 20 6c 65 73 73 0a 2a 2a   a value less.**
1d660 20 74 68 61 6e 20 31 2e 0a 2a 2a 0a 2a 2a 20 5e   than 1..**.** ^
1d670 49 66 20 74 68 65 20 70 72 6f 67 72 65 73 73 20  If the progress 
1d680 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73  callback returns
1d690 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 20 6f   non-zero, the o
1d6a0 70 65 72 61 74 69 6f 6e 20 69 73 0a 2a 2a 20 69  peration is.** i
1d6b0 6e 74 65 72 72 75 70 74 65 64 2e 20 20 54 68 69  nterrupted.  Thi
1d6c0 73 20 66 65 61 74 75 72 65 20 63 61 6e 20 62 65  s feature can be
1d6d0 20 75 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65   used to impleme
1d6e0 6e 74 20 61 0a 2a 2a 20 22 43 61 6e 63 65 6c 22  nt a.** "Cancel"
1d6f0 20 62 75 74 74 6f 6e 20 6f 6e 20 61 20 47 55 49   button on a GUI
1d700 20 70 72 6f 67 72 65 73 73 20 64 69 61 6c 6f 67   progress dialog
1d710 20 62 6f 78 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20   box..**.** The 
1d720 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72  progress handler
1d730 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74 20 6e   callback must n
1d740 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
1d750 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
1d760 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
1d770 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
1d780 69 6e 76 6f 6b 65 64 20 74 68 65 20 70 72 6f 67  invoked the prog
1d790 72 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  ress handler..**
1d7a0 20 4e 6f 74 65 20 74 68 61 74 20 5b 73 71 6c 69   Note that [sqli
1d7b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
1d7c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
1d7d0 74 65 70 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69  tep()] both modi
1d7e0 66 79 20 74 68 65 69 72 0a 2a 2a 20 64 61 74 61  fy their.** data
1d7f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
1d800 20 66 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67   for the meaning
1d810 20 6f 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20   of "modify" in 
1d820 74 68 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a  this paragraph..
1d830 2a 2a 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  **.*/.void sqlit
1d840 65 33 5f 70 72 6f 67 72 65 73 73 5f 68 61 6e 64  e3_progress_hand
1d850 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  ler(sqlite3*, in
1d860 74 2c 20 69 6e 74 28 2a 29 28 76 6f 69 64 2a 29  t, int(*)(void*)
1d870 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  , void*);../*.**
1d880 20 43 41 50 49 33 52 45 46 3a 20 4f 70 65 6e 69   CAPI3REF: Openi
1d890 6e 67 20 41 20 4e 65 77 20 44 61 74 61 62 61 73  ng A New Databas
1d8a0 65 20 43 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 0a  e Connection.**.
1d8b0 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
1d8c0 65 73 20 6f 70 65 6e 20 61 6e 20 53 51 4c 69 74  es open an SQLit
1d8d0 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1d8e0 61 73 20 73 70 65 63 69 66 69 65 64 20 62 79 20  as specified by 
1d8f0 74 68 65 20 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65  the .** filename
1d900 20 61 72 67 75 6d 65 6e 74 2e 20 5e 54 68 65 20   argument. ^The 
1d910 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1d920 74 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64  t is interpreted
1d930 20 61 73 20 55 54 46 2d 38 20 66 6f 72 0a 2a 2a   as UTF-8 for.**
1d940 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20   sqlite3_open() 
1d950 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  and sqlite3_open
1d960 5f 76 32 28 29 20 61 6e 64 20 61 73 20 55 54 46  _v2() and as UTF
1d970 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74 69 76  -16 in the nativ
1d980 65 20 62 79 74 65 0a 2a 2a 20 6f 72 64 65 72 20  e byte.** order 
1d990 66 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  for sqlite3_open
1d9a0 31 36 28 29 2e 20 5e 28 41 20 5b 64 61 74 61 62  16(). ^(A [datab
1d9b0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
1d9c0 68 61 6e 64 6c 65 20 69 73 20 75 73 75 61 6c 6c  handle is usuall
1d9d0 79 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 69 6e  y.** returned in
1d9e0 20 2a 70 70 44 62 2c 20 65 76 65 6e 20 69 66 20   *ppDb, even if 
1d9f0 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e  an error occurs.
1da00 20 20 54 68 65 20 6f 6e 6c 79 20 65 78 63 65 70    The only excep
1da10 74 69 6f 6e 20 69 73 20 74 68 61 74 0a 2a 2a 20  tion is that.** 
1da20 69 66 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61  if SQLite is una
1da30 62 6c 65 20 74 6f 20 61 6c 6c 6f 63 61 74 65 20  ble to allocate 
1da40 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20 74  memory to hold t
1da50 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f 62 6a  he [sqlite3] obj
1da60 65 63 74 2c 0a 2a 2a 20 61 20 4e 55 4c 4c 20 77  ect,.** a NULL w
1da70 69 6c 6c 20 62 65 20 77 72 69 74 74 65 6e 20 69  ill be written i
1da80 6e 74 6f 20 2a 70 70 44 62 20 69 6e 73 74 65 61  nto *ppDb instea
1da90 64 20 6f 66 20 61 20 70 6f 69 6e 74 65 72 20 74  d of a pointer t
1daa0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 0a  o the [sqlite3].
1dab0 2a 2a 20 6f 62 6a 65 63 74 2e 29 5e 20 5e 28 49  ** object.)^ ^(I
1dac0 66 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69  f the database i
1dad0 73 20 6f 70 65 6e 65 64 20 28 61 6e 64 2f 6f 72  s opened (and/or
1dae0 20 63 72 65 61 74 65 64 29 20 73 75 63 63 65 73   created) succes
1daf0 73 66 75 6c 6c 79 2c 20 74 68 65 6e 0a 2a 2a 20  sfully, then.** 
1db00 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69 73 20 72  [SQLITE_OK] is r
1db10 65 74 75 72 6e 65 64 2e 20 20 4f 74 68 65 72 77  eturned.  Otherw
1db20 69 73 65 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ise an [error co
1db30 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
1db40 29 5e 20 5e 54 68 65 0a 2a 2a 20 5b 73 71 6c 69  )^ ^The.** [sqli
1db50 74 65 33 5f 65 72 72 6d 73 67 28 29 5d 20 6f 72  te3_errmsg()] or
1db60 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1db70 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 63  16()] routines c
1db80 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 6f 62  an be used to ob
1db90 74 61 69 6e 0a 2a 2a 20 61 6e 20 45 6e 67 6c 69  tain.** an Engli
1dba0 73 68 20 6c 61 6e 67 75 61 67 65 20 64 65 73 63  sh language desc
1dbb0 72 69 70 74 69 6f 6e 20 6f 66 20 74 68 65 20 65  ription of the e
1dbc0 72 72 6f 72 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  rror following a
1dbd0 20 66 61 69 6c 75 72 65 20 6f 66 20 61 6e 79 0a   failure of any.
1dbe0 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
1dbf0 33 5f 6f 70 65 6e 28 29 20 72 6f 75 74 69 6e 65  3_open() routine
1dc00 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 64 65  s..**.** ^The de
1dc10 66 61 75 6c 74 20 65 6e 63 6f 64 69 6e 67 20 66  fault encoding f
1dc20 6f 72 20 74 68 65 20 64 61 74 61 62 61 73 65 20  or the database 
1dc30 77 69 6c 6c 20 62 65 20 55 54 46 2d 38 20 69 66  will be UTF-8 if
1dc40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  .** sqlite3_open
1dc50 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 70  () or sqlite3_op
1dc60 65 6e 5f 76 32 28 29 20 69 73 20 63 61 6c 6c 65  en_v2() is calle
1dc70 64 20 61 6e 64 0a 2a 2a 20 55 54 46 2d 31 36 20  d and.** UTF-16 
1dc80 69 6e 20 74 68 65 20 6e 61 74 69 76 65 20 62 79  in the native by
1dc90 74 65 20 6f 72 64 65 72 20 69 66 20 73 71 6c 69  te order if sqli
1dca0 74 65 33 5f 6f 70 65 6e 31 36 28 29 20 69 73 20  te3_open16() is 
1dcb0 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 74  used..**.** Whet
1dcc0 68 65 72 20 6f 72 20 6e 6f 74 20 61 6e 20 65 72  her or not an er
1dcd0 72 6f 72 20 6f 63 63 75 72 73 20 77 68 65 6e 20  ror occurs when 
1dce0 69 74 20 69 73 20 6f 70 65 6e 65 64 2c 20 72 65  it is opened, re
1dcf0 73 6f 75 72 63 65 73 0a 2a 2a 20 61 73 73 6f 63  sources.** assoc
1dd00 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
1dd10 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1dd20 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 73 68 6f 75  ion] handle shou
1dd30 6c 64 20 62 65 20 72 65 6c 65 61 73 65 64 20 62  ld be released b
1dd40 79 0a 2a 2a 20 70 61 73 73 69 6e 67 20 69 74 20  y.** passing it 
1dd50 74 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73  to [sqlite3_clos
1dd60 65 28 29 5d 20 77 68 65 6e 20 69 74 20 69 73 20  e()] when it is 
1dd70 6e 6f 20 6c 6f 6e 67 65 72 20 72 65 71 75 69 72  no longer requir
1dd80 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ed..**.** The sq
1dd90 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1dda0 69 6e 74 65 72 66 61 63 65 20 77 6f 72 6b 73 20  interface works 
1ddb0 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 6f 70 65  like sqlite3_ope
1ddc0 6e 28 29 0a 2a 2a 20 65 78 63 65 70 74 20 74 68  n().** except th
1ddd0 61 74 20 69 74 20 61 63 63 65 70 74 73 20 74 77  at it accepts tw
1dde0 6f 20 61 64 64 69 74 69 6f 6e 61 6c 20 70 61 72  o additional par
1ddf0 61 6d 65 74 65 72 73 20 66 6f 72 20 61 64 64 69  ameters for addi
1de00 74 69 6f 6e 61 6c 20 63 6f 6e 74 72 6f 6c 0a 2a  tional control.*
1de10 2a 20 6f 76 65 72 20 74 68 65 20 6e 65 77 20 64  * over the new d
1de20 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1de30 6f 6e 2e 20 20 5e 28 54 68 65 20 66 6c 61 67 73  on.  ^(The flags
1de40 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
1de50 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1de60 28 29 20 63 61 6e 20 74 61 6b 65 20 6f 6e 65 20  () can take one 
1de70 6f 66 0a 2a 2a 20 74 68 65 20 66 6f 6c 6c 6f 77  of.** the follow
1de80 69 6e 67 20 74 68 72 65 65 20 76 61 6c 75 65 73  ing three values
1de90 2c 20 6f 70 74 69 6f 6e 61 6c 6c 79 20 63 6f 6d  , optionally com
1dea0 62 69 6e 65 64 20 77 69 74 68 20 74 68 65 20 0a  bined with the .
1deb0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1dec0 4e 4f 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54  NOMUTEX], [SQLIT
1ded0 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58  E_OPEN_FULLMUTEX
1dee0 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ], [SQLITE_OPEN_
1def0 53 48 41 52 45 44 43 41 43 48 45 5d 2c 0a 2a 2a  SHAREDCACHE],.**
1df00 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1df10 49 56 41 54 45 43 41 43 48 45 5d 2c 20 61 6e 64  IVATECACHE], and
1df20 2f 6f 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  /or [SQLITE_OPEN
1df30 5f 55 52 49 5d 20 66 6c 61 67 73 3a 29 5e 0a 2a  _URI] flags:)^.*
1df40 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20 5e 28 3c  *.** <dl>.** ^(<
1df50 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  dt>[SQLITE_OPEN_
1df60 52 45 41 44 4f 4e 4c 59 5d 3c 2f 64 74 3e 0a 2a  READONLY]</dt>.*
1df70 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61 62 61  * <dd>The databa
1df80 73 65 20 69 73 20 6f 70 65 6e 65 64 20 69 6e 20  se is opened in 
1df90 72 65 61 64 2d 6f 6e 6c 79 20 6d 6f 64 65 2e 20  read-only mode. 
1dfa0 20 49 66 20 74 68 65 20 64 61 74 61 62 61 73 65   If the database
1dfb0 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20 61 6c 72   does not.** alr
1dfc0 65 61 64 79 20 65 78 69 73 74 2c 20 61 6e 20 65  eady exist, an e
1dfd0 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64  rror is returned
1dfe0 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  .</dd>)^.**.** ^
1dff0 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f 50 45  (<dt>[SQLITE_OPE
1e000 4e 5f 52 45 41 44 57 52 49 54 45 5d 3c 2f 64 74  N_READWRITE]</dt
1e010 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1e020 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1e030 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1e040 77 72 69 74 69 6e 67 20 69 66 20 70 6f 73 73 69  writing if possi
1e050 62 6c 65 2c 20 6f 72 20 72 65 61 64 69 6e 67 0a  ble, or reading.
1e060 2a 2a 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 66  ** only if the f
1e070 69 6c 65 20 69 73 20 77 72 69 74 65 20 70 72 6f  ile is write pro
1e080 74 65 63 74 65 64 20 62 79 20 74 68 65 20 6f 70  tected by the op
1e090 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 2e 20  erating system. 
1e0a0 20 49 6e 20 65 69 74 68 65 72 0a 2a 2a 20 63 61   In either.** ca
1e0b0 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20  se the database 
1e0c0 6d 75 73 74 20 61 6c 72 65 61 64 79 20 65 78 69  must already exi
1e0d0 73 74 2c 20 6f 74 68 65 72 77 69 73 65 20 61 6e  st, otherwise an
1e0e0 20 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e   error is return
1e0f0 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  ed.</dd>)^.**.**
1e100 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45 5f 4f   ^(<dt>[SQLITE_O
1e110 50 45 4e 5f 52 45 41 44 57 52 49 54 45 5d 20 7c  PEN_READWRITE] |
1e120 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
1e130 45 41 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  EATE]</dt>.** <d
1e140 64 3e 54 68 65 20 64 61 74 61 62 61 73 65 20 69  d>The database i
1e150 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61  s opened for rea
1e160 64 69 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67  ding and writing
1e170 2c 20 61 6e 64 20 69 73 20 63 72 65 61 74 65 64  , and is created
1e180 20 69 66 0a 2a 2a 20 69 74 20 64 6f 65 73 20 6e   if.** it does n
1e190 6f 74 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ot already exist
1e1a0 2e 20 54 68 69 73 20 69 73 20 74 68 65 20 62 65  . This is the be
1e1b0 68 61 76 69 6f 72 20 74 68 61 74 20 69 73 20 61  havior that is a
1e1c0 6c 77 61 79 73 20 75 73 65 64 20 66 6f 72 0a 2a  lways used for.*
1e1d0 2a 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  * sqlite3_open()
1e1e0 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65   and sqlite3_ope
1e1f0 6e 31 36 28 29 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  n16().</dd>)^.**
1e200 20 3c 2f 64 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20   </dl>.**.** If 
1e210 74 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65  the 3rd paramete
1e220 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  r to sqlite3_ope
1e230 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 6f 6e  n_v2() is not on
1e240 65 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f 6d 62  e of the.** comb
1e250 69 6e 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61  inations shown a
1e260 62 6f 76 65 20 6f 70 74 69 6f 6e 61 6c 6c 79 20  bove optionally 
1e270 63 6f 6d 62 69 6e 65 64 20 77 69 74 68 20 6f 74  combined with ot
1e280 68 65 72 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  her.** [SQLITE_O
1e290 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 53  PEN_READONLY | S
1e2a0 51 4c 49 54 45 5f 4f 50 45 4e 5f 2a 20 62 69 74  QLITE_OPEN_* bit
1e2b0 73 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 62  s].** then the b
1e2c0 65 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66  ehavior is undef
1e2d0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ined..**.** ^If 
1e2e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  the [SQLITE_OPEN
1e2f0 5f 4e 4f 4d 55 54 45 58 5d 20 66 6c 61 67 20 69  _NOMUTEX] flag i
1e300 73 20 73 65 74 2c 20 74 68 65 6e 20 74 68 65 20  s set, then the 
1e310 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e320 69 6f 6e 0a 2a 2a 20 6f 70 65 6e 73 20 69 6e 20  ion.** opens in 
1e330 74 68 65 20 6d 75 6c 74 69 2d 74 68 72 65 61 64  the multi-thread
1e340 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
1e350 5d 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65  ] as long as the
1e360 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 0a 2a   single-thread.*
1e370 2a 20 6d 6f 64 65 20 68 61 73 20 6e 6f 74 20 62  * mode has not b
1e380 65 65 6e 20 73 65 74 20 61 74 20 63 6f 6d 70 69  een set at compi
1e390 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74  le-time or start
1e3a0 2d 74 69 6d 65 2e 20 20 5e 49 66 20 74 68 65 0a  -time.  ^If the.
1e3b0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  ** [SQLITE_OPEN_
1e3c0 46 55 4c 4c 4d 55 54 45 58 5d 20 66 6c 61 67 20  FULLMUTEX] flag 
1e3d0 69 73 20 73 65 74 20 74 68 65 6e 20 74 68 65 20  is set then the 
1e3e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
1e3f0 69 6f 6e 20 6f 70 65 6e 73 0a 2a 2a 20 69 6e 20  ion opens.** in 
1e400 74 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b  the serialized [
1e410 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
1e420 75 6e 6c 65 73 73 20 73 69 6e 67 6c 65 2d 74 68  unless single-th
1e430 72 65 61 64 20 77 61 73 0a 2a 2a 20 70 72 65 76  read was.** prev
1e440 69 6f 75 73 6c 79 20 73 65 6c 65 63 74 65 64 20  iously selected 
1e450 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  at compile-time 
1e460 6f 72 20 73 74 61 72 74 2d 74 69 6d 65 2e 0a 2a  or start-time..*
1e470 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f  * ^The [SQLITE_O
1e480 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45 5d  PEN_SHAREDCACHE]
1e490 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1e4a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1e4b0 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a 20 65 6c  tion to be.** el
1e4c0 69 67 69 62 6c 65 20 74 6f 20 75 73 65 20 5b 73  igible to use [s
1e4d0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1e4e0 5d 2c 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ], regardless of
1e4f0 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   whether or not 
1e500 73 68 61 72 65 64 0a 2a 2a 20 63 61 63 68 65 20  shared.** cache 
1e510 69 73 20 65 6e 61 62 6c 65 64 20 75 73 69 6e 67  is enabled using
1e520 20 5b 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65   [sqlite3_enable
1e530 5f 73 68 61 72 65 64 5f 63 61 63 68 65 28 29 5d  _shared_cache()]
1e540 2e 20 20 5e 54 68 65 0a 2a 2a 20 5b 53 51 4c 49  .  ^The.** [SQLI
1e550 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45 43  TE_OPEN_PRIVATEC
1e560 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73 65  ACHE] flag cause
1e570 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  s the database c
1e580 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 6e 6f 74  onnection to not
1e590 0a 2a 2a 20 70 61 72 74 69 63 69 70 61 74 65 20  .** participate 
1e5a0 69 6e 20 5b 73 68 61 72 65 64 20 63 61 63 68 65  in [shared cache
1e5b0 20 6d 6f 64 65 5d 20 65 76 65 6e 20 69 66 20 69   mode] even if i
1e5c0 74 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  t is enabled..**
1e5d0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
1e5e0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
1e5f0 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69  ite3_open_v2() i
1e600 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1e610 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66  e.** [sqlite3_vf
1e620 73 5d 20 6f 62 6a 65 63 74 20 74 68 61 74 20 64  s] object that d
1e630 65 66 69 6e 65 73 20 74 68 65 20 6f 70 65 72 61  efines the opera
1e640 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e 74 65  ting system inte
1e650 72 66 61 63 65 20 74 68 61 74 0a 2a 2a 20 74 68  rface that.** th
1e660 65 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63  e new database c
1e670 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 6f 75 6c 64  onnection should
1e680 20 75 73 65 2e 20 20 5e 49 66 20 74 68 65 20 66   use.  ^If the f
1e690 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1e6a0 69 73 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  is.** a NULL poi
1e6b0 6e 74 65 72 20 74 68 65 6e 20 74 68 65 20 64 65  nter then the de
1e6c0 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76  fault [sqlite3_v
1e6d0 66 73 5d 20 6f 62 6a 65 63 74 20 69 73 20 75 73  fs] object is us
1e6e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
1e6f0 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 22 3a  e filename is ":
1e700 6d 65 6d 6f 72 79 3a 22 2c 20 74 68 65 6e 20 61  memory:", then a
1e710 20 70 72 69 76 61 74 65 2c 20 74 65 6d 70 6f 72   private, tempor
1e720 61 72 79 20 69 6e 2d 6d 65 6d 6f 72 79 20 64 61  ary in-memory da
1e730 74 61 62 61 73 65 0a 2a 2a 20 69 73 20 63 72 65  tabase.** is cre
1e740 61 74 65 64 20 66 6f 72 20 74 68 65 20 63 6f 6e  ated for the con
1e750 6e 65 63 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20  nection.  ^This 
1e760 69 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61  in-memory databa
1e770 73 65 20 77 69 6c 6c 20 76 61 6e 69 73 68 20 77  se will vanish w
1e780 68 65 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  hen.** the datab
1e790 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
1e7a0 73 20 63 6c 6f 73 65 64 2e 20 20 46 75 74 75 72  s closed.  Futur
1e7b0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1e7c0 4c 69 74 65 20 6d 69 67 68 74 0a 2a 2a 20 6d 61  Lite might.** ma
1e7d0 6b 65 20 75 73 65 20 6f 66 20 61 64 64 69 74 69  ke use of additi
1e7e0 6f 6e 61 6c 20 73 70 65 63 69 61 6c 20 66 69 6c  onal special fil
1e7f0 65 6e 61 6d 65 73 20 74 68 61 74 20 62 65 67 69  enames that begi
1e800 6e 20 77 69 74 68 20 74 68 65 20 22 3a 22 20 63  n with the ":" c
1e810 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 49 74 20  haracter..** It 
1e820 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
1e830 68 61 74 20 77 68 65 6e 20 61 20 64 61 74 61 62  hat when a datab
1e840 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 61 63 74  ase filename act
1e850 75 61 6c 6c 79 20 64 6f 65 73 20 62 65 67 69 6e  ually does begin
1e860 20 77 69 74 68 0a 2a 2a 20 61 20 22 3a 22 20 63   with.** a ":" c
1e870 68 61 72 61 63 74 65 72 20 79 6f 75 20 73 68 6f  haracter you sho
1e880 75 6c 64 20 70 72 65 66 69 78 20 74 68 65 20 66  uld prefix the f
1e890 69 6c 65 6e 61 6d 65 20 77 69 74 68 20 61 20 70  ilename with a p
1e8a0 61 74 68 6e 61 6d 65 20 73 75 63 68 20 61 73 0a  athname such as.
1e8b0 2a 2a 20 22 2e 2f 22 20 74 6f 20 61 76 6f 69 64  ** "./" to avoid
1e8c0 20 61 6d 62 69 67 75 69 74 79 2e 0a 2a 2a 0a 2a   ambiguity..**.*
1e8d0 2a 20 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61  * ^If the filena
1e8e0 6d 65 20 69 73 20 61 6e 20 65 6d 70 74 79 20 73  me is an empty s
1e8f0 74 72 69 6e 67 2c 20 74 68 65 6e 20 61 20 70 72  tring, then a pr
1e900 69 76 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79  ivate, temporary
1e910 0a 2a 2a 20 6f 6e 2d 64 69 73 6b 20 64 61 74 61  .** on-disk data
1e920 62 61 73 65 20 77 69 6c 6c 20 62 65 20 63 72 65  base will be cre
1e930 61 74 65 64 2e 20 20 5e 54 68 69 73 20 70 72 69  ated.  ^This pri
1e940 76 61 74 65 20 64 61 74 61 62 61 73 65 20 77 69  vate database wi
1e950 6c 6c 20 62 65 0a 2a 2a 20 61 75 74 6f 6d 61 74  ll be.** automat
1e960 69 63 61 6c 6c 79 20 64 65 6c 65 74 65 64 20 61  ically deleted a
1e970 73 20 73 6f 6f 6e 20 61 73 20 74 68 65 20 64 61  s soon as the da
1e980 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
1e990 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
1e9a0 2a 2a 20 5b 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ** [[URI filenam
1e9b0 65 73 20 69 6e 20 73 71 6c 69 74 65 33 5f 6f 70  es in sqlite3_op
1e9c0 65 6e 28 29 5d 5d 20 3c 68 33 3e 55 52 49 20 46  en()]] <h3>URI F
1e9d0 69 6c 65 6e 61 6d 65 73 3c 2f 68 33 3e 0a 2a 2a  ilenames</h3>.**
1e9e0 0a 2a 2a 20 5e 49 66 20 5b 55 52 49 20 66 69 6c  .** ^If [URI fil
1e9f0 65 6e 61 6d 65 5d 20 69 6e 74 65 72 70 72 65 74  ename] interpret
1ea00 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64  ation is enabled
1ea10 2c 20 61 6e 64 20 74 68 65 20 66 69 6c 65 6e 61  , and the filena
1ea20 6d 65 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 62  me argument.** b
1ea30 65 67 69 6e 73 20 77 69 74 68 20 22 66 69 6c 65  egins with "file
1ea40 3a 22 2c 20 74 68 65 6e 20 74 68 65 20 66 69 6c  :", then the fil
1ea50 65 6e 61 6d 65 20 69 73 20 69 6e 74 65 72 70 72  ename is interpr
1ea60 65 74 65 64 20 61 73 20 61 20 55 52 49 2e 20 5e  eted as a URI. ^
1ea70 55 52 49 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  URI.** filename 
1ea80 69 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69  interpretation i
1ea90 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
1eaa0 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52   [SQLITE_OPEN_UR
1eab0 49 5d 20 66 6c 61 67 20 69 73 0a 2a 2a 20 73 65  I] flag is.** se
1eac0 74 20 69 6e 20 74 68 65 20 66 6f 75 72 74 68 20  t in the fourth 
1ead0 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69  argument to sqli
1eae0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2c 20 6f  te3_open_v2(), o
1eaf0 72 20 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 62  r if it has.** b
1eb00 65 65 6e 20 65 6e 61 62 6c 65 64 20 67 6c 6f 62  een enabled glob
1eb10 61 6c 6c 79 20 75 73 69 6e 67 20 74 68 65 20 5b  ally using the [
1eb20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 55 52  SQLITE_CONFIG_UR
1eb30 49 5d 20 6f 70 74 69 6f 6e 20 77 69 74 68 20 74  I] option with t
1eb40 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  he.** [sqlite3_c
1eb50 6f 6e 66 69 67 28 29 5d 20 6d 65 74 68 6f 64 20  onfig()] method 
1eb60 6f 72 20 62 79 20 74 68 65 20 5b 53 51 4c 49 54  or by the [SQLIT
1eb70 45 5f 55 53 45 5f 55 52 49 5d 20 63 6f 6d 70 69  E_USE_URI] compi
1eb80 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a  le-time option..
1eb90 2a 2a 20 41 73 20 6f 66 20 53 51 4c 69 74 65 20  ** As of SQLite 
1eba0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 37 2c 20 55  version 3.7.7, U
1ebb0 52 49 20 66 69 6c 65 6e 61 6d 65 20 69 6e 74 65  RI filename inte
1ebc0 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 74 75  rpretation is tu
1ebd0 72 6e 65 64 20 6f 66 66 0a 2a 2a 20 62 79 20 64  rned off.** by d
1ebe0 65 66 61 75 6c 74 2c 20 62 75 74 20 66 75 74 75  efault, but futu
1ebf0 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
1ec00 51 4c 69 74 65 20 6d 69 67 68 74 20 65 6e 61 62  QLite might enab
1ec10 6c 65 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 0a  le URI filename.
1ec20 2a 2a 20 69 6e 74 65 72 70 72 65 74 61 74 69 6f  ** interpretatio
1ec30 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 20 20 53  n by default.  S
1ec40 65 65 20 22 5b 55 52 49 20 66 69 6c 65 6e 61 6d  ee "[URI filenam
1ec50 65 73 5d 22 20 66 6f 72 20 61 64 64 69 74 69 6f  es]" for additio
1ec60 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69  nal.** informati
1ec70 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20 66 69  on..**.** URI fi
1ec80 6c 65 6e 61 6d 65 73 20 61 72 65 20 70 61 72 73  lenames are pars
1ec90 65 64 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20  ed according to 
1eca0 52 46 43 20 33 39 38 36 2e 20 5e 49 66 20 74 68  RFC 3986. ^If th
1ecb0 65 20 55 52 49 20 63 6f 6e 74 61 69 6e 73 20 61  e URI contains a
1ecc0 6e 0a 2a 2a 20 61 75 74 68 6f 72 69 74 79 2c 20  n.** authority, 
1ecd0 74 68 65 6e 20 69 74 20 6d 75 73 74 20 62 65 20  then it must be 
1ece0 65 69 74 68 65 72 20 61 6e 20 65 6d 70 74 79 20  either an empty 
1ecf0 73 74 72 69 6e 67 20 6f 72 20 74 68 65 20 73 74  string or the st
1ed00 72 69 6e 67 20 0a 2a 2a 20 22 6c 6f 63 61 6c 68  ring .** "localh
1ed10 6f 73 74 22 2e 20 5e 49 66 20 74 68 65 20 61 75  ost". ^If the au
1ed20 74 68 6f 72 69 74 79 20 69 73 20 6e 6f 74 20 61  thority is not a
1ed30 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1ed40 72 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2c 20 61  r "localhost", a
1ed50 6e 20 0a 2a 2a 20 65 72 72 6f 72 20 69 73 20 72  n .** error is r
1ed60 65 74 75 72 6e 65 64 20 74 6f 20 74 68 65 20 63  eturned to the c
1ed70 61 6c 6c 65 72 2e 20 5e 54 68 65 20 66 72 61 67  aller. ^The frag
1ed80 6d 65 6e 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  ment component o
1ed90 66 20 61 20 55 52 49 2c 20 69 66 20 0a 2a 2a 20  f a URI, if .** 
1eda0 70 72 65 73 65 6e 74 2c 20 69 73 20 69 67 6e 6f  present, is igno
1edb0 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  red..**.** ^SQLi
1edc0 74 65 20 75 73 65 73 20 74 68 65 20 70 61 74 68  te uses the path
1edd0 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 74 68   component of th
1ede0 65 20 55 52 49 20 61 73 20 74 68 65 20 6e 61 6d  e URI as the nam
1edf0 65 20 6f 66 20 74 68 65 20 64 69 73 6b 20 66 69  e of the disk fi
1ee00 6c 65 0a 2a 2a 20 77 68 69 63 68 20 63 6f 6e 74  le.** which cont
1ee10 61 69 6e 73 20 74 68 65 20 64 61 74 61 62 61 73  ains the databas
1ee20 65 2e 20 5e 49 66 20 74 68 65 20 70 61 74 68 20  e. ^If the path 
1ee30 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 27 2f  begins with a '/
1ee40 27 20 63 68 61 72 61 63 74 65 72 2c 20 0a 2a 2a  ' character, .**
1ee50 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74 65   then it is inte
1ee60 72 70 72 65 74 65 64 20 61 73 20 61 6e 20 61 62  rpreted as an ab
1ee70 73 6f 6c 75 74 65 20 70 61 74 68 2e 20 5e 49 66  solute path. ^If
1ee80 20 74 68 65 20 70 61 74 68 20 64 6f 65 73 20 6e   the path does n
1ee90 6f 74 20 62 65 67 69 6e 20 0a 2a 2a 20 77 69 74  ot begin .** wit
1eea0 68 20 61 20 27 2f 27 20 28 6d 65 61 6e 69 6e 67  h a '/' (meaning
1eeb0 20 74 68 61 74 20 74 68 65 20 61 75 74 68 6f 72   that the author
1eec0 69 74 79 20 73 65 63 74 69 6f 6e 20 69 73 20 6f  ity section is o
1eed0 6d 69 74 74 65 64 20 66 72 6f 6d 20 74 68 65 20  mitted from the 
1eee0 55 52 49 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  URI).** then the
1eef0 20 70 61 74 68 20 69 73 20 69 6e 74 65 72 70 72   path is interpr
1ef00 65 74 65 64 20 61 73 20 61 20 72 65 6c 61 74 69  eted as a relati
1ef10 76 65 20 70 61 74 68 2e 20 0a 2a 2a 20 5e 4f 6e  ve path. .** ^On
1ef20 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1ef30 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1ef40 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1ef50 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1ef60 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1ef70 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1ef80 2a 20 5b 5b 63 6f 72 65 20 55 52 49 20 71 75 65  * [[core URI que
1ef90 72 79 20 70 61 72 61 6d 65 74 65 72 73 5d 5d 0a  ry parameters]].
1efa0 2a 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d  ** The query com
1efb0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1efc0 6d 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61  may contain para
1efd0 6d 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20  meters that are 
1efe0 69 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65  interpreted.** e
1eff0 69 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20  ither by SQLite 
1f000 69 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20  itself, or by a 
1f010 5b 56 46 53 20 7c 20 63 75 73 74 6f 6d 20 56 46  [VFS | custom VF
1f020 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  S implementation
1f030 5d 2e 0a 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74  ]..** SQLite int
1f040 65 72 70 72 65 74 73 20 74 68 65 20 66 6f 6c 6c  erprets the foll
1f050 6f 77 69 6e 67 20 74 68 72 65 65 20 71 75 65 72  owing three quer
1f060 79 20 70 61 72 61 6d 65 74 65 72 73 3a 0a 2a 2a  y parameters:.**
1f070 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c  .** <ul>.**   <l
1f080 69 3e 20 3c 62 3e 76 66 73 3c 2f 62 3e 3a 20 5e  i> <b>vfs</b>: ^
1f090 54 68 65 20 22 76 66 73 22 20 70 61 72 61 6d 65  The "vfs" parame
1f0a0 74 65 72 20 6d 61 79 20 62 65 20 75 73 65 64 20  ter may be used 
1f0b0 74 6f 20 73 70 65 63 69 66 79 20 74 68 65 20 6e  to specify the n
1f0c0 61 6d 65 20 6f 66 0a 2a 2a 20 20 20 20 20 61 20  ame of.**     a 
1f0d0 56 46 53 20 6f 62 6a 65 63 74 20 74 68 61 74 20  VFS object that 
1f0e0 70 72 6f 76 69 64 65 73 20 74 68 65 20 6f 70 65  provides the ope
1f0f0 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 6e  rating system in
1f100 74 65 72 66 61 63 65 20 74 68 61 74 20 73 68 6f  terface that sho
1f110 75 6c 64 0a 2a 2a 20 20 20 20 20 62 65 20 75 73  uld.**     be us
1f120 65 64 20 74 6f 20 61 63 63 65 73 73 20 74 68 65  ed to access the
1f130 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 6f   database file o
1f140 6e 20 64 69 73 6b 2e 20 5e 49 66 20 74 68 69 73  n disk. ^If this
1f150 20 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74   option is set t
1f160 6f 0a 2a 2a 20 20 20 20 20 61 6e 20 65 6d 70 74  o.**     an empt
1f170 79 20 73 74 72 69 6e 67 20 74 68 65 20 64 65 66  y string the def
1f180 61 75 6c 74 20 56 46 53 20 6f 62 6a 65 63 74 20  ault VFS object 
1f190 69 73 20 75 73 65 64 2e 20 5e 53 70 65 63 69 66  is used. ^Specif
1f1a0 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e 0a  ying an unknown.
1f1b0 2a 2a 20 20 20 20 20 56 46 53 20 69 73 20 61 6e  **     VFS is an
1f1c0 20 65 72 72 6f 72 2e 20 5e 49 66 20 73 71 6c 69   error. ^If sqli
1f1d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1f1e0 20 75 73 65 64 20 61 6e 64 20 74 68 65 20 76 66   used and the vf
1f1f0 73 20 6f 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 20  s option is.**  
1f200 20 20 20 70 72 65 73 65 6e 74 2c 20 74 68 65 6e     present, then
1f210 20 74 68 65 20 56 46 53 20 73 70 65 63 69 66 69   the VFS specifi
1f220 65 64 20 62 79 20 74 68 65 20 6f 70 74 69 6f 6e  ed by the option
1f230 20 74 61 6b 65 73 20 70 72 65 63 65 64 65 6e 63   takes precedenc
1f240 65 20 6f 76 65 72 0a 2a 2a 20 20 20 20 20 74 68  e over.**     th
1f250 65 20 76 61 6c 75 65 20 70 61 73 73 65 64 20 61  e value passed a
1f260 73 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72  s the fourth par
1f270 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
1f280 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2a 0a  3_open_v2()..**.
1f290 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 6d 6f 64  **   <li> <b>mod
1f2a0 65 3c 2f 62 3e 3a 20 5e 28 54 68 65 20 6d 6f 64  e</b>: ^(The mod
1f2b0 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20  e parameter may 
1f2c0 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65 72  be set to either
1f2d0 20 22 72 6f 22 2c 20 22 72 77 22 20 6f 72 0a 2a   "ro", "rw" or.*
1f2e0 2a 20 20 20 20 20 22 72 77 63 22 2e 20 41 74 74  *     "rwc". Att
1f2f0 65 6d 70 74 69 6e 67 20 74 6f 20 73 65 74 20 69  empting to set i
1f300 74 20 74 6f 20 61 6e 79 20 6f 74 68 65 72 20 76  t to any other v
1f310 61 6c 75 65 20 69 73 20 61 6e 20 65 72 72 6f 72  alue is an error
1f320 29 5e 2e 20 0a 2a 2a 20 20 20 20 20 5e 49 66 20  )^. .**     ^If 
1f330 22 72 6f 22 20 69 73 20 73 70 65 63 69 66 69 65  "ro" is specifie
1f340 64 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61  d, then the data
1f350 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1f360 6f 72 20 72 65 61 64 2d 6f 6e 6c 79 20 0a 2a 2a  or read-only .**
1f370 20 20 20 20 20 61 63 63 65 73 73 2c 20 6a 75 73       access, jus
1f380 74 20 61 73 20 69 66 20 74 68 65 20 5b 53 51 4c  t as if the [SQL
1f390 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c  ITE_OPEN_READONL
1f3a0 59 5d 20 66 6c 61 67 20 68 61 64 20 62 65 65 6e  Y] flag had been
1f3b0 20 73 65 74 20 69 6e 20 74 68 65 20 0a 2a 2a 20   set in the .** 
1f3c0 20 20 20 20 74 68 69 72 64 20 61 72 67 75 6d 65      third argume
1f3d0 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 70 72  nt to sqlite3_pr
1f3e0 65 70 61 72 65 5f 76 32 28 29 2e 20 5e 49 66 20  epare_v2(). ^If 
1f3f0 74 68 65 20 6d 6f 64 65 20 6f 70 74 69 6f 6e 20  the mode option 
1f400 69 73 20 73 65 74 20 74 6f 20 0a 2a 2a 20 20 20  is set to .**   
1f410 20 20 22 72 77 22 2c 20 74 68 65 6e 20 74 68 65    "rw", then the
1f420 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1f430 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 77 72 69  ned for read-wri
1f440 74 65 20 28 62 75 74 20 6e 6f 74 20 63 72 65 61  te (but not crea
1f450 74 65 29 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  te) .**     acce
1f460 73 73 2c 20 61 73 20 69 66 20 53 51 4c 49 54 45  ss, as if SQLITE
1f470 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20  _OPEN_READWRITE 
1f480 28 62 75 74 20 6e 6f 74 20 53 51 4c 49 54 45 5f  (but not SQLITE_
1f490 4f 50 45 4e 5f 43 52 45 41 54 45 29 20 68 61 64  OPEN_CREATE) had
1f4a0 20 0a 2a 2a 20 20 20 20 20 62 65 65 6e 20 73 65   .**     been se
1f4b0 74 2e 20 5e 56 61 6c 75 65 20 22 72 77 63 22 20  t. ^Value "rwc" 
1f4c0 69 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f  is equivalent to
1f4d0 20 73 65 74 74 69 6e 67 20 62 6f 74 68 20 0a 2a   setting both .*
1f4e0 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f 50 45  *     SQLITE_OPE
1f4f0 4e 5f 52 45 41 44 57 52 49 54 45 20 61 6e 64 20  N_READWRITE and 
1f500 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1f510 54 45 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f  TE. ^If sqlite3_
1f520 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 0a 2a 2a  open_v2() is .**
1f530 20 20 20 20 20 75 73 65 64 2c 20 69 74 20 69 73       used, it is
1f540 20 61 6e 20 65 72 72 6f 72 20 74 6f 20 73 70 65   an error to spe
1f550 63 69 66 79 20 61 20 76 61 6c 75 65 20 66 6f 72  cify a value for
1f560 20 74 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65   the mode parame
1f570 74 65 72 20 74 68 61 74 20 69 73 20 0a 2a 2a 20  ter that is .** 
1f580 20 20 20 20 6c 65 73 73 20 72 65 73 74 72 69 63      less restric
1f590 74 69 76 65 20 74 68 61 6e 20 74 68 61 74 20 73  tive than that s
1f5a0 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20  pecified by the 
1f5b0 66 6c 61 67 73 20 70 61 73 73 65 64 20 61 73 20  flags passed as 
1f5c0 74 68 65 20 74 68 69 72 64 20 0a 2a 2a 20 20 20  the third .**   
1f5d0 20 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a    parameter..**.
1f5e0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 63 61 63  **   <li> <b>cac
1f5f0 68 65 3c 2f 62 3e 3a 20 5e 54 68 65 20 63 61 63  he</b>: ^The cac
1f600 68 65 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79  he parameter may
1f610 20 62 65 20 73 65 74 20 74 6f 20 65 69 74 68 65   be set to eithe
1f620 72 20 22 73 68 61 72 65 64 22 20 6f 72 0a 2a 2a  r "shared" or.**
1f630 20 20 20 20 20 22 70 72 69 76 61 74 65 22 2e 20       "private". 
1f640 5e 53 65 74 74 69 6e 67 20 69 74 20 74 6f 20 22  ^Setting it to "
1f650 73 68 61 72 65 64 22 20 69 73 20 65 71 75 69 76  shared" is equiv
1f660 61 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67  alent to setting
1f670 20 74 68 65 0a 2a 2a 20 20 20 20 20 53 51 4c 49   the.**     SQLI
1f680 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1f690 43 48 45 20 62 69 74 20 69 6e 20 74 68 65 20 66  CHE bit in the f
1f6a0 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 70 61  lags argument pa
1f6b0 73 73 65 64 20 74 6f 0a 2a 2a 20 20 20 20 20 73  ssed to.**     s
1f6c0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1f6d0 2e 20 5e 53 65 74 74 69 6e 67 20 74 68 65 20 63  . ^Setting the c
1f6e0 61 63 68 65 20 70 61 72 61 6d 65 74 65 72 20 74  ache parameter t
1f6f0 6f 20 22 70 72 69 76 61 74 65 22 20 69 73 20 0a  o "private" is .
1f700 2a 2a 20 20 20 20 20 65 71 75 69 76 61 6c 65 6e  **     equivalen
1f710 74 20 74 6f 20 73 65 74 74 69 6e 67 20 74 68 65  t to setting the
1f720 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1f730 56 41 54 45 43 41 43 48 45 20 62 69 74 2e 0a 2a  VATECACHE bit..*
1f740 2a 20 20 20 20 20 5e 49 66 20 73 71 6c 69 74 65  *     ^If sqlite
1f750 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 75  3_open_v2() is u
1f760 73 65 64 20 61 6e 64 20 74 68 65 20 22 63 61 63  sed and the "cac
1f770 68 65 22 20 70 61 72 61 6d 65 74 65 72 20 69 73  he" parameter is
1f780 20 70 72 65 73 65 6e 74 20 69 6e 0a 2a 2a 20 20   present in.**  
1f790 20 20 20 61 20 55 52 49 20 66 69 6c 65 6e 61 6d     a URI filenam
1f7a0 65 2c 20 69 74 73 20 76 61 6c 75 65 20 6f 76 65  e, its value ove
1f7b0 72 72 69 64 65 73 20 61 6e 79 20 62 65 68 61 76  rrides any behav
1f7c0 69 6f 75 72 20 72 65 71 75 65 73 74 65 64 20 62  iour requested b
1f7d0 79 20 73 65 74 74 69 6e 67 0a 2a 2a 20 20 20 20  y setting.**    
1f7e0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52 49   SQLITE_OPEN_PRI
1f7f0 56 41 54 45 43 41 43 48 45 20 6f 72 20 53 51 4c  VATECACHE or SQL
1f800 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43  ITE_OPEN_SHAREDC
1f810 41 43 48 45 20 66 6c 61 67 2e 0a 2a 2a 20 3c 2f  ACHE flag..** </
1f820 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 53 70 65 63 69  ul>.**.** ^Speci
1f830 66 79 69 6e 67 20 61 6e 20 75 6e 6b 6e 6f 77 6e  fying an unknown
1f840 20 70 61 72 61 6d 65 74 65 72 20 69 6e 20 74 68   parameter in th
1f850 65 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e  e query componen
1f860 74 20 6f 66 20 61 20 55 52 49 20 69 73 20 6e 6f  t of a URI is no
1f870 74 20 61 6e 0a 2a 2a 20 65 72 72 6f 72 2e 20 20  t an.** error.  
1f880 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73 20  Future versions 
1f890 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74 20  of SQLite might 
1f8a0 75 6e 64 65 72 73 74 61 6e 64 20 61 64 64 69 74  understand addit
1f8b0 69 6f 6e 61 6c 20 71 75 65 72 79 0a 2a 2a 20 70  ional query.** p
1f8c0 61 72 61 6d 65 74 65 72 73 2e 20 20 53 65 65 20  arameters.  See 
1f8d0 22 5b 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  "[query paramete
1f8e0 72 73 20 77 69 74 68 20 73 70 65 63 69 61 6c 20  rs with special 
1f8f0 6d 65 61 6e 69 6e 67 20 74 6f 20 53 51 4c 69 74  meaning to SQLit
1f900 65 5d 22 20 66 6f 72 0a 2a 2a 20 61 64 64 69 74  e]" for.** addit
1f910 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74 69 6f  ional informatio
1f920 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  n..**.** [[URI f
1f930 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65 73  ilename examples
1f940 5d 5d 20 3c 68 33 3e 55 52 49 20 66 69 6c 65 6e  ]] <h3>URI filen
1f950 61 6d 65 20 65 78 61 6d 70 6c 65 73 3c 2f 68 33  ame examples</h3
1f960 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20 62  >.**.** <table b
1f970 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e 3d  order="1" align=
1f980 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64 69  center cellpaddi
1f990 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68  ng=5>.** <tr><th
1f9a0 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  > URI filenames 
1f9b0 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a 20  <th> Results.** 
1f9c0 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61  <tr><td> file:da
1f9d0 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20  ta.db <td> .**  
1f9e0 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68 65          Open the
1f9f0 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1fa00 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1fa10 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74 72  irectory..** <tr
1fa20 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65  ><td> file:/home
1fa30 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62 72  /fred/data.db<br
1fa40 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69  >.**          fi
1fa50 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64 2f  le:///home/fred/
1fa60 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a 2a  data.db <br> .**
1fa70 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1fa80 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65 2f  /localhost/home/
1fa90 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1faa0 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20  > <td> .**      
1fab0 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61 74      Open the dat
1fac0 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f 6d  abase file "/hom
1fad0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22 2e  e/fred/data.db".
1fae0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1faf0 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f 6d  e://darkstar/hom
1fb00 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c  e/fred/data.db <
1fb10 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20  td> .**         
1fb20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72 6b   An error. "dark
1fb30 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20 72  star" is not a r
1fb40 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f 72  ecognized author
1fb50 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 20  ity..** <tr><td 
1fb60 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70 61  style="white-spa
1fb70 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a 20  ce:nowrap"> .** 
1fb80 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f 2f           file://
1fb90 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32 30  /C:/Documents%20
1fba0 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f 66  and%20Settings/f
1fbb0 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74 61  red/Desktop/data
1fbc0 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e 20  .db.**     <td> 
1fbd0 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f 70  Windows only: Op
1fbe0 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74  en the file "dat
1fbf0 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73 20  a.db" on fred's 
1fc00 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76 65  desktop on drive
1fc10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a 2e  .**          C:.
1fc20 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 25   Note that the %
1fc30 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20 74  20 escaping in t
1fc40 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20 6e  his example is n
1fc50 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a 20  ot strictly .** 
1fc60 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73 61           necessa
1fc70 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72 61  ry - space chara
1fc80 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73 65  cters can be use
1fc90 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20 20  d literally.**  
1fca0 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20 66          in URI f
1fcb0 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74 72  ilenames..** <tr
1fcc0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1fcd0 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68 65  db?mode=ro&cache
1fce0 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a 2a  =private <td> .*
1fcf0 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1fd00 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20 69  file "data.db" i
1fd10 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64 69  n the current di
1fd20 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61 64  rectory for read
1fd30 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a 2a  -only access..**
1fd40 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72 64            Regard
1fd50 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20  less of whether 
1fd60 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63 61  or not shared-ca
1fd70 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61 62  che mode is enab
1fd80 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20 20  led by.**       
1fd90 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65 20     default, use 
1fda0 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65 2e  a private cache.
1fdb0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c  .** <tr><td> fil
1fdc0 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74  e:/home/fred/dat
1fdd0 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e 6f  a.db?vfs=unix-no
1fde0 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20 20  lock <td>.**    
1fdf0 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65 20        Open file 
1fe00 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1fe10 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73 70  .db". Use the sp
1fe20 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78 2d  ecial VFS "unix-
1fe30 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72 3e  nolock"..** <tr>
1fe40 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e 64  <td> file:data.d
1fe50 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79 20  b?mode=readonly 
1fe60 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1fe70 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65 61    An error. "rea
1fe80 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61 20  donly" is not a 
1fe90 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f 72  valid option for
1fea0 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72 61   the "mode" para
1feb0 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62 6c  meter..** </tabl
1fec0 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68 65  e>.**.** ^URI he
1fed0 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70 65  xadecimal escape
1fee0 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48 29   sequences (%HH)
1fef0 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20 77   are supported w
1ff00 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20 61  ithin the path a
1ff10 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d 70  nd.** query comp
1ff20 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49 2e  onents of a URI.
1ff30 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65   A hexadecimal e
1ff40 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20 63  scape sequence c
1ff50 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a 20  onsists of a.** 
1ff60 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20 22  percent sign - "
1ff70 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62 79  %" - followed by
1ff80 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65 78   exactly two hex
1ff90 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73 20  adecimal digits 
1ffa0 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20 61  .** specifying a
1ffb0 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20 5e  n octet value. ^
1ffc0 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68 20  Before the path 
1ffd0 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e 65  or query compone
1ffe0 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49 20  nts of a.** URI 
1fff0 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e 74  filename are int
20000 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20 61  erpreted, they a
20010 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e 67  re encoded using
20020 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20 0a   UTF-8 and all .
20030 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  ** hexadecimal e
20040 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
20050 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73 69  replaced by a si
20060 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61 69  ngle byte contai
20070 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72 72  ning the.** corr
20080 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74 2e  esponding octet.
20090 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73 73   If this process
200a0 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69 6e   generates an in
200b0 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63 6f  valid UTF-8 enco
200c0 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65 73  ding,.** the res
200d0 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
200e0 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f 74  ed..**.** <b>Not
200f0 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73 65  e to Windows use
20100 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e 63  rs:</b>  The enc
20110 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20 74  oding used for t
20120 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75  he filename argu
20130 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69 74  ment.** of sqlit
20140 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
20150 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
20160 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20 6e  must be UTF-8, n
20170 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20 63  ot whatever.** c
20180 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72 65  odepage is curre
20190 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20 46  ntly defined.  F
201a0 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69 6e  ilenames contain
201b0 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e 61  ing internationa
201c0 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73 20  l.** characters 
201d0 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65  must be converte
201e0 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f 72  d to UTF-8 prior
201f0 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65 6d   to passing them
20200 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   into.** sqlite3
20210 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69 74  _open() or sqlit
20220 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a 2f  e3_open_v2()..*/
20230 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65  .int sqlite3_ope
20240 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  n(.  const char 
20250 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
20260 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
20270 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
20280 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20 20  qlite3 **ppDb   
20290 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
202a0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
202b0 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  */.);.int sqlite
202c0 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e 73  3_open16(.  cons
202d0 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d 65  t void *filename
202e0 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  ,   /* Database 
202f0 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31 36  filename (UTF-16
20300 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a  ) */.  sqlite3 *
20310 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20 2f  *ppDb          /
20320 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64 62  * OUT: SQLite db
20330 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e   handle */.);.in
20340 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76  t sqlite3_open_v
20350 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  2(.  const char 
20360 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a 20  *filename,   /* 
20370 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61 6d  Database filenam
20380 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20 73  e (UTF-8) */.  s
20390 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20 20  qlite3 **ppDb,  
203a0 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53         /* OUT: S
203b0 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65 20  QLite db handle 
203c0 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c 20  */.  int flags, 
203d0 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
203e0 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73 74  Flags */.  const
203f0 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20 20   char *zVfs     
20400 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56 46     /* Name of VF
20410 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65 20  S module to use 
20420 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  */.);../*.** CAP
20430 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 20 56 61  I3REF: Obtain Va
20440 6c 75 65 73 20 46 6f 72 20 55 52 49 20 50 61 72  lues For URI Par
20450 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 54 68  ameters.**.** Th
20460 65 73 65 20 61 72 65 20 75 74 69 6c 69 74 79 20  ese are utility 
20470 72 6f 75 74 69 6e 65 73 2c 20 75 73 65 66 75 6c  routines, useful
20480 20 74 6f 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e   to VFS implemen
20490 74 61 74 69 6f 6e 73 2c 20 74 68 61 74 20 63 68  tations, that ch
204a0 65 63 6b 0a 2a 2a 20 74 6f 20 73 65 65 20 69 66  eck.** to see if
204b0 20 61 20 64 61 74 61 62 61 73 65 20 66 69 6c 65   a database file
204c0 20 77 61 73 20 61 20 55 52 49 20 74 68 61 74 20   was a URI that 
204d0 63 6f 6e 74 61 69 6e 65 64 20 61 20 73 70 65 63  contained a spec
204e0 69 66 69 63 20 71 75 65 72 79 20 0a 2a 2a 20 70  ific query .** p
204f0 61 72 61 6d 65 74 65 72 2c 20 61 6e 64 20 69 66  arameter, and if
20500 20 73 6f 20 6f 62 74 61 69 6e 73 20 74 68 65 20   so obtains the 
20510 76 61 6c 75 65 20 6f 66 20 74 68 61 74 20 71 75  value of that qu
20520 65 72 79 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ery parameter..*
20530 2a 0a 2a 2a 20 49 66 20 46 20 69 73 20 74 68 65  *.** If F is the
20540 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
20550 6d 65 20 70 6f 69 6e 74 65 72 20 70 61 73 73 65  me pointer passe
20560 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
20570 28 29 20 6d 65 74 68 6f 64 20 6f 66 20 0a 2a 2a  () method of .**
20580 20 61 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74   a VFS implement
20590 61 74 69 6f 6e 20 77 68 65 6e 20 74 68 65 20 66  ation when the f
205a0 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72 20 74  lags parameter t
205b0 6f 20 78 4f 70 65 6e 28 29 20 68 61 73 20 6f 6e  o xOpen() has on
205c0 65 20 6f 72 20 0a 2a 2a 20 6d 6f 72 65 20 6f 66  e or .** more of
205d0 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45   the [SQLITE_OPE
205e0 4e 5f 55 52 49 5d 20 6f 72 20 5b 53 51 4c 49 54  N_URI] or [SQLIT
205f0 45 5f 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 5d 20  E_OPEN_MAIN_DB] 
20600 62 69 74 73 20 73 65 74 20 61 6e 64 0a 2a 2a 20  bits set and.** 
20610 50 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f 66  P is the name of
20620 20 74 68 65 20 71 75 65 72 79 20 70 61 72 61 6d   the query param
20630 65 74 65 72 2c 20 74 68 65 6e 0a 2a 2a 20 73 71  eter, then.** sq
20640 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d 65  lite3_uri_parame
20650 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e 73  ter(F,P) returns
20660 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
20670 65 20 50 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  e P.** parameter
20680 20 69 66 20 69 74 20 65 78 69 73 74 73 20 6f 72   if it exists or
20690 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
206a0 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 20 61 70  if P does not ap
206b0 70 65 61 72 20 61 73 20 61 20 0a 2a 2a 20 71 75  pear as a .** qu
206c0 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  ery parameter on
206d0 20 46 2e 20 20 49 66 20 50 20 69 73 20 61 20 71   F.  If P is a q
206e0 75 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 6f  uery parameter o
206f0 66 20 46 0a 2a 2a 20 68 61 73 20 6e 6f 20 65 78  f F.** has no ex
20700 70 6c 69 63 69 74 20 76 61 6c 75 65 2c 20 74 68  plicit value, th
20710 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 70  en sqlite3_uri_p
20720 61 72 61 6d 65 74 65 72 28 46 2c 50 29 20 72 65  arameter(F,P) re
20730 74 75 72 6e 73 0a 2a 2a 20 61 20 70 6f 69 6e 74  turns.** a point
20740 65 72 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  er to an empty s
20750 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  tring..**.** The
20760 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20770 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72 6f 75 74  lean(F,P,B) rout
20780 69 6e 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ine assumes that
20790 20 50 20 69 73 20 61 20 62 6f 6f 6c 65 61 6e 0a   P is a boolean.
207a0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  ** parameter and
207b0 20 72 65 74 75 72 6e 73 20 74 72 75 65 20 28 31   returns true (1
207c0 29 20 6f 72 20 66 61 6c 73 65 20 28 30 29 20 61  ) or false (0) a
207d0 63 63 6f 72 64 69 6e 67 20 74 6f 20 74 68 65 20  ccording to the 
207e0 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 50 2e 20 20  value.** of P.  
207f0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 72 69 5f  The sqlite3_uri_
20800 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20 72  boolean(F,P,B) r
20810 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74  outine returns t
20820 72 75 65 20 28 31 29 20 69 66 20 74 68 65 0a 2a  rue (1) if the.*
20830 2a 20 76 61 6c 75 65 20 6f 66 20 71 75 65 72 79  * value of query
20840 20 70 61 72 61 6d 65 74 65 72 20 50 20 69 73 20   parameter P is 
20850 6f 6e 65 20 6f 66 20 22 79 65 73 22 2c 20 22 74  one of "yes", "t
20860 72 75 65 22 2c 20 6f 72 20 22 6f 6e 22 20 69 6e  rue", or "on" in
20870 20 61 6e 79 0a 2a 2a 20 63 61 73 65 20 6f 72 20   any.** case or 
20880 69 66 20 74 68 65 20 76 61 6c 75 65 20 62 65 67  if the value beg
20890 69 6e 73 20 77 69 74 68 20 61 20 6e 6f 6e 2d 7a  ins with a non-z
208a0 65 72 6f 20 6e 75 6d 62 65 72 2e 20 20 54 68 65  ero number.  The
208b0 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 75 72 69   .** sqlite3_uri
208c0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
208d0 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 73  routines returns
208e0 20 66 61 6c 73 65 20 28 30 29 20 69 66 20 74 68   false (0) if th
208f0 65 20 76 61 6c 75 65 20 6f 66 0a 2a 2a 20 71 75  e value of.** qu
20900 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 50 20  ery parameter P 
20910 69 73 20 6f 6e 65 20 6f 66 20 22 6e 6f 22 2c 20  is one of "no", 
20920 22 66 61 6c 73 65 22 2c 20 6f 72 20 22 6f 66 66  "false", or "off
20930 22 20 69 6e 20 61 6e 79 20 63 61 73 65 20 6f 72  " in any case or
20940 0a 2a 2a 20 69 66 20 74 68 65 20 76 61 6c 75 65  .** if the value
20950 20 62 65 67 69 6e 73 20 77 69 74 68 20 61 20 6e   begins with a n
20960 75 6d 65 72 69 63 20 7a 65 72 6f 2e 20 20 49 66  umeric zero.  If
20970 20 50 20 69 73 20 6e 6f 74 20 61 20 71 75 65 72   P is not a quer
20980 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f  y.** parameter o
20990 6e 20 46 20 6f 72 20 69 66 20 74 68 65 20 76 61  n F or if the va
209a0 6c 75 65 20 6f 66 20 50 20 69 73 20 64 6f 65 73  lue of P is does
209b0 20 6e 6f 74 20 6d 61 74 63 68 20 61 6e 79 20 6f   not match any o
209c0 66 20 74 68 65 0a 2a 2a 20 61 62 6f 76 65 2c 20  f the.** above, 
209d0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 75 72 69  then sqlite3_uri
209e0 5f 62 6f 6f 6c 65 61 6e 28 46 2c 50 2c 42 29 20  _boolean(F,P,B) 
209f0 72 65 74 75 72 6e 73 20 28 42 21 3d 30 29 2e 0a  returns (B!=0)..
20a00 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65  **.** The sqlite
20a10 33 5f 75 72 69 5f 69 6e 74 36 34 28 46 2c 50 2c  3_uri_int64(F,P,
20a20 44 29 20 72 6f 75 74 69 6e 65 20 63 6f 6e 76 65  D) routine conve
20a30 72 74 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66  rts the value of
20a40 20 50 20 69 6e 74 6f 20 61 0a 2a 2a 20 36 34 2d   P into a.** 64-
20a50 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
20a60 65 72 20 61 6e 64 20 72 65 74 75 72 6e 73 20 74  er and returns t
20a70 68 61 74 20 69 6e 74 65 67 65 72 2c 20 6f 72 20  hat integer, or 
20a80 44 20 69 66 20 50 20 64 6f 65 73 20 6e 6f 74 0a  D if P does not.
20a90 2a 2a 20 65 78 69 73 74 2e 20 20 49 66 20 74 68  ** exist.  If th
20aa0 65 20 76 61 6c 75 65 20 6f 66 20 50 20 69 73 20  e value of P is 
20ab0 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65 72 20  something other 
20ac0 74 68 61 6e 20 61 6e 20 69 6e 74 65 67 65 72 2c  than an integer,
20ad0 20 74 68 65 6e 0a 2a 2a 20 7a 65 72 6f 20 69 73   then.** zero is
20ae0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 0a 2a   returned..** .*
20af0 2a 20 49 66 20 46 20 69 73 20 61 20 4e 55 4c 4c  * If F is a NULL
20b00 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 73   pointer, then s
20b10 71 6c 69 74 65 33 5f 75 72 69 5f 70 61 72 61 6d  qlite3_uri_param
20b20 65 74 65 72 28 46 2c 50 29 20 72 65 74 75 72 6e  eter(F,P) return
20b30 73 20 4e 55 4c 4c 20 61 6e 64 0a 2a 2a 20 73 71  s NULL and.** sq
20b40 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f 6c 65 61  lite3_uri_boolea
20b50 6e 28 46 2c 50 2c 42 29 20 72 65 74 75 72 6e 73  n(F,P,B) returns
20b60 20 42 2e 20 20 49 66 20 46 20 69 73 20 6e 6f 74   B.  If F is not
20b70 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
20b80 61 6e 64 0a 2a 2a 20 69 73 20 6e 6f 74 20 61 20  and.** is not a 
20b90 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 70 61  database file pa
20ba0 74 68 6e 61 6d 65 20 70 6f 69 6e 74 65 72 20 74  thname pointer t
20bb0 68 61 74 20 53 51 4c 69 74 65 20 70 61 73 73 65  hat SQLite passe
20bc0 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
20bd0 0a 2a 2a 20 56 46 53 20 6d 65 74 68 6f 64 2c 20  .** VFS method, 
20be0 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f  then the behavio
20bf0 72 20 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e  r of this routin
20c00 65 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  e is undefined a
20c10 6e 64 20 70 72 6f 62 61 62 6c 79 0a 2a 2a 20 75  nd probably.** u
20c20 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63  ndesirable..*/.c
20c30 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
20c40 65 33 5f 75 72 69 5f 70 61 72 61 6d 65 74 65 72  e3_uri_parameter
20c50 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 69  (const char *zFi
20c60 6c 65 6e 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68  lename, const ch
20c70 61 72 20 2a 7a 50 61 72 61 6d 29 3b 0a 69 6e 74  ar *zParam);.int
20c80 20 73 71 6c 69 74 65 33 5f 75 72 69 5f 62 6f 6f   sqlite3_uri_boo
20c90 6c 65 61 6e 28 63 6f 6e 73 74 20 63 68 61 72 20  lean(const char 
20ca0 2a 7a 46 69 6c 65 2c 20 63 6f 6e 73 74 20 63 68  *zFile, const ch
20cb0 61 72 20 2a 7a 50 61 72 61 6d 2c 20 69 6e 74 20  ar *zParam, int 
20cc0 62 44 65 66 61 75 6c 74 29 3b 0a 73 71 6c 69 74  bDefault);.sqlit
20cd0 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
20ce0 5f 75 72 69 5f 69 6e 74 36 34 28 63 6f 6e 73 74  _uri_int64(const
20cf0 20 63 68 61 72 2a 2c 20 63 6f 6e 73 74 20 63 68   char*, const ch
20d00 61 72 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  ar*, sqlite3_int
20d10 36 34 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  64);.../*.** CAP
20d20 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f 64  I3REF: Error Cod
20d30 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73 0a  es And Messages.
20d40 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
20d50 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e 74  e3_errcode() int
20d60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
20d70 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73 75  he numeric [resu
20d80 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b  lt code] or.** [
20d90 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
20da0 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d 6f  code] for the mo
20db0 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65 64  st recent failed
20dc0 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20 63   sqlite3_* API c
20dd0 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65  all.** associate
20de0 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  d with a [databa
20df0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e 20  se connection]. 
20e00 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20 63  If a prior API c
20e10 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62 75  all failed.** bu
20e20 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
20e30 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63 65  t API call succe
20e40 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72 6e  eded, the return
20e50 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20 73   value from.** s
20e60 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28 29  qlite3_errcode()
20e70 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20 20   is undefined.  
20e80 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78 74  ^The sqlite3_ext
20e90 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29 0a  ended_errcode().
20ea0 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73 20  ** interface is 
20eb0 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74 20  the same except 
20ec0 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20 72  that it always r
20ed0 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20 5b  eturns the .** [
20ee0 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
20ef0 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e 20  code] even when 
20f00 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
20f10 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69 73  codes are.** dis
20f20 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  abled..**.** ^Th
20f30 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67  e sqlite3_errmsg
20f40 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 65  () and sqlite3_e
20f50 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72 6e  rrmsg16() return
20f60 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61 67   English-languag
20f70 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20 64  e.** text that d
20f80 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72 72  escribes the err
20f90 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55 54  or, as either UT
20fa0 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72 65  F-8 or UTF-16 re
20fb0 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e  spectively..** ^
20fc0 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64 20  (Memory to hold 
20fd0 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61 67  the error messag
20fe0 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e 61  e string is mana
20ff0 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e 0a  ged internally..
21000 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69  ** The applicati
21010 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  on does not need
21020 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74 20   to worry about 
21030 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73 75  freeing the resu
21040 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  lt..** However, 
21050 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e 67  the error string
21060 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77 72   might be overwr
21070 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f 63  itten or dealloc
21080 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73 65  ated by.** subse
21090 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20 6f  quent calls to o
210a0 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65  ther SQLite inte
210b0 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73 2e  rface functions.
210c0 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74 68  )^.**.** When th
210d0 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74 68  e serialized [th
210e0 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69 73  reading mode] is
210f0 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67 68   in use, it migh
21100 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73 65  t be the.** case
21110 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20 65   that a second e
21120 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20 61  rror occurs on a
21130 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64   separate thread
21140 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 74   in between.** t
21150 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20 66  he time of the f
21160 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20 74  irst error and t
21170 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73 65  he call to these
21180 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
21190 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65 6e  When that happen
211a0 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65 72  s, the second er
211b0 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70 6f  ror will be repo
211c0 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73 65  rted since these
211d0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61  .** interfaces a
211e0 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68 65  lways report the
211f0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65 73   most recent res
21200 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a 2a  ult.  To avoid.*
21210 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68 72  * this, each thr
21220 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20 65  ead can obtain e
21230 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66 20  xclusive use of 
21240 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
21250 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20 62  nnection] D.** b
21260 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c 69  y invoking [sqli
21270 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72 5d  te3_mutex_enter]
21280 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75 74  ([sqlite3_db_mut
21290 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20 62  ex](D)) before b
212a0 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20 75  eginning.** to u
212b0 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69 6e  se D and invokin
212c0 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  g [sqlite3_mutex
212d0 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65 33  _leave]([sqlite3
212e0 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 61  _db_mutex](D)) a
212f0 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c 6c  fter.** all call
21300 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66 61  s to the interfa
21310 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65 20  ces listed here 
21320 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a 2a  are completed..*
21330 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65 72  *.** If an inter
21340 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68 20  face fails with 
21350 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20 74  SQLITE_MISUSE, t
21360 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69 6e  hat means the in
21370 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20 69  terface.** was i
21380 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63 74  nvoked incorrect
21390 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69 63  ly by the applic
213a0 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74 20  ation.  In that 
213b0 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72 72  case, the.** err
213c0 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73 73  or code and mess
213d0 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20 6e  age may or may n
213e0 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69 6e  ot be set..*/.in
213f0 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64  t sqlite3_errcod
21400 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
21410 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
21420 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71 6c  nded_errcode(sql
21430 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73 74  ite3 *db);.const
21440 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 65   char *sqlite3_e
21450 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29 3b  rrmsg(sqlite3*);
21460 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
21470 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73 71  ite3_errmsg16(sq
21480 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
21490 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53 74  CAPI3REF: SQL St
214a0 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a  atement Object.*
214b0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 65  * KEYWORDS: {pre
214c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 7d  pared statement}
214d0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
214e0 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e 20  ments}.**.** An 
214f0 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69 73  instance of this
21500 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65 6e   object represen
21510 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c 20  ts a single SQL 
21520 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54 68  statement..** Th
21530 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61 72  is object is var
21540 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73 20  iously known as 
21550 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61 74  a "prepared stat
21560 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20 22  ement" or a.** "
21570 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74 61  compiled SQL sta
21580 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70 6c  tement" or simpl
21590 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65 6e  y as a "statemen
215a0 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c 69  t"..**.** The li
215b0 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65 6e  fe of a statemen
215c0 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73 6f  t object goes so
215d0 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68 69  mething like thi
215e0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
215f0 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68 65   <li> Create the
21600 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b 73   object using [s
21610 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21620 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74 65  2()] or a relate
21630 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74 69  d.**      functi
21640 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e 64  on..** <li> Bind
21650 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73 74   values to [host
21660 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73 69   parameters] usi
21670 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62  ng the sqlite3_b
21680 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20 20  ind_*().**      
21690 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20 3c  interfaces..** <
216a0 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c 20  li> Run the SQL 
216b0 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
216c0 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65 20  te3_step()] one 
216d0 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a 2a  or more times..*
216e0 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68 65  * <li> Reset the
216f0 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67   statement using
21700 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
21710 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b 0a  )] then go back.
21720 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70 20  **      to step 
21730 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72 6f  2.  Do this zero
21740 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
21750 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79 20  ** <li> Destroy 
21760 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67  the object using
21770 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
21780 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a  ze()]..** </ol>.
21790 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 64  **.** Refer to d
217a0 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e 20  ocumentation on 
217b0 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68 6f  individual metho
217c0 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64 64  ds above for add
217d0 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72  itional.** infor
217e0 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65 64  mation..*/.typed
217f0 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74 65  ef struct sqlite
21800 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f 73  3_stmt sqlite3_s
21810 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  tmt;../*.** CAPI
21820 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20 4c  3REF: Run-time L
21830 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  imits.**.** ^(Th
21840 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c 6c  is interface all
21850 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ows the size of 
21860 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75 63  various construc
21870 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65 64  ts to be limited
21880 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63 74  .** on a connect
21890 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69 6f  ion by connectio
218a0 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66 69  n basis.  The fi
218b0 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69 73  rst parameter is
218c0 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73   the.** [databas
218d0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77 68  e connection] wh
218e0 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f 20  ose limit is to 
218f0 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69 65  be set or querie
21900 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f 6e  d.  The.** secon
21910 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 6f  d parameter is o
21920 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69 74  ne of the [limit
21930 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68 61   categories] tha
21940 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63 6c  t define a.** cl
21950 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63 74  ass of construct
21960 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69 6d  s to be size lim
21970 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72 64  ited.  The third
21980 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
21990 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20 66  e.** new limit f
219a0 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75 63  or that construc
219b0 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  t.)^.**.** ^If t
219c0 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73 20  he new limit is 
219d0 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62 65  a negative numbe
219e0 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73 20  r, the limit is 
219f0 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e 28  unchanged..** ^(
21a00 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20 63  For each limit c
21a10 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f 4c  ategory SQLITE_L
21a20 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e  IMIT_<i>NAME</i>
21a30 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a 20   there is a .** 
21a40 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20 75  [limits | hard u
21a50 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20 73  pper bound].** s
21a60 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
21a70 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72 6f  me by a C prepro
21a80 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61 6c  cessor macro cal
21a90 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c  led.** [limits |
21aa0 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e 4e   SQLITE_MAX_<i>N
21ab0 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54 68  AME</i>]..** (Th
21ac0 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20 74  e "_LIMIT_" in t
21ad0 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e 67  he name is chang
21ae0 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29 29  ed to "_MAX_".))
21af0 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20 74  ^.** ^Attempts t
21b00 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69 6d  o increase a lim
21b10 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61 72  it above its har
21b20 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61 72  d upper bound ar
21b30 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74 72  e.** silently tr
21b40 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20 68  uncated to the h
21b50 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 2e  ard upper bound.
21b60 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c 65  .**.** ^Regardle
21b70 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
21b80 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20 77   not the limit w
21b90 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65 20  as changed, the 
21ba0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  .** [sqlite3_lim
21bb0 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  it()] interface 
21bc0 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69 6f  returns the prio
21bd0 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 6c  r value of the l
21be0 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65 2c  imit..** ^Hence,
21bf0 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75 72   to find the cur
21c00 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61 20  rent value of a 
21c10 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63 68  limit without ch
21c20 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73 69  anging it,.** si
21c30 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69 73  mply invoke this
21c40 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68 20   interface with 
21c50 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  the third parame
21c60 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a 2a  ter set to -1..*
21c70 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c 69  *.** Run-time li
21c80 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64 65  mits are intende
21c90 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70 70  d for use in app
21ca0 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 6d  lications that m
21cb0 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74 68  anage.** both th
21cc0 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61 6c  eir own internal
21cd0 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61 6c   database and al
21ce0 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68 61  so databases tha
21cf0 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65 64  t are controlled
21d00 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65 64  .** by untrusted
21d10 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63 65   external source
21d20 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20 61  s.  An example a
21d30 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68 74  pplication might
21d40 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72 6f   be a.** web bro
21d50 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69 74  wser that has it
21d60 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73 20  s own databases 
21d70 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73 74  for storing hist
21d80 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61 72  ory and.** separ
21d90 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63 6f  ate databases co
21da0 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76 61  ntrolled by Java
21db0 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74 69  Script applicati
21dc0 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a 2a  ons downloaded.*
21dd0 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72 6e  * off the Intern
21de0 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e 61  et.  The interna
21df0 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e 20  l databases can 
21e00 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a 20  be given the.** 
21e10 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20 6c  large, default l
21e20 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73 65  imits.  Database
21e30 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78 74  s managed by ext
21e40 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63 61  ernal sources ca
21e50 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d 75  n.** be given mu
21e60 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69 74  ch smaller limit
21e70 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70 72  s designed to pr
21e80 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20 6f  event a denial o
21e90 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74 74  f service.** att
21ea0 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72 73  ack.  Developers
21eb0 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e 74   might also want
21ec0 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71 6c   to use the [sql
21ed0 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69  ite3_set_authori
21ee0 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72 66  zer()].** interf
21ef0 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20 63  ace to further c
21f00 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65 64  ontrol untrusted
21f10 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65 20   SQL.  The size 
21f20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
21f30 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61 6e  ** created by an
21f40 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69 70   untrusted scrip
21f50 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69 6e  t can be contain
21f60 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20  ed using the.** 
21f70 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
21f80 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a 2a   [PRAGMA]..**.**
21f90 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c 69   New run-time li
21fa0 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20 6d  mit categories m
21fb0 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20 66  ay be added in f
21fc0 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e 0a  uture releases..
21fd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6c  */.int sqlite3_l
21fe0 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20 69  imit(sqlite3*, i
21ff0 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56 61  nt id, int newVa
22000 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  l);../*.** CAPI3
22010 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c 69  REF: Run-Time Li
22020 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a 2a  mit Categories.*
22030 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69 6d  * KEYWORDS: {lim
22040 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a 6c  it category} {*l
22050 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 7d  imit categories}
22060 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
22070 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76 61  stants define va
22080 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e 63  rious performanc
22090 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61 74  e limits.** that
220a0 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64 20   can be lowered 
220b0 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69 6e  at run-time usin
220c0 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
220d0 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e 6f  ()]..** The syno
220e0 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61 6e  psis of the mean
220f0 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72 69  ings of the vari
22100 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73 68  ous limits is sh
22110 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41 64  own below..** Ad
22120 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61  ditional informa
22130 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62 6c  tion is availabl
22140 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20 4c  e at [limits | L
22150 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65 5d  imits in SQLite]
22160 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a 20  ..**.** <dl>.** 
22170 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  [[SQLITE_LIMIT_L
22180 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  ENGTH]] ^(<dt>SQ
22190 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54  LITE_LIMIT_LENGT
221a0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
221b0 65 20 6d 61 78 69 6d 75 6d 20 73 69 7a 65 20 6f  e maximum size o
221c0 66 20 61 6e 79 20 73 74 72 69 6e 67 20 6f 72 20  f any string or 
221d0 42 4c 4f 42 20 6f 72 20 74 61 62 6c 65 20 72 6f  BLOB or table ro
221e0 77 2c 20 69 6e 20 62 79 74 65 73 2e 3c 64 64 3e  w, in bytes.<dd>
221f0 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22200 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
22210 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
22220 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47  E_LIMIT_SQL_LENG
22230 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22240 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
22250 68 20 6f 66 20 61 6e 20 53 51 4c 20 73 74 61 74  h of an SQL stat
22260 65 6d 65 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e  ement, in bytes.
22270 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
22280 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c  SQLITE_LIMIT_COL
22290 55 4d 4e 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49  UMN]] ^(<dt>SQLI
222a0 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 3c  TE_LIMIT_COLUMN<
222b0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
222c0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
222d0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 74  f columns in a t
222e0 61 62 6c 65 20 64 65 66 69 6e 69 74 69 6f 6e 20  able definition 
222f0 6f 72 20 69 6e 20 74 68 65 0a 2a 2a 20 72 65 73  or in the.** res
22300 75 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45  ult set of a [SE
22310 4c 45 43 54 5d 20 6f 72 20 74 68 65 20 6d 61 78  LECT] or the max
22320 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 63  imum number of c
22330 6f 6c 75 6d 6e 73 20 69 6e 20 61 6e 20 69 6e 64  olumns in an ind
22340 65 78 0a 2a 2a 20 6f 72 20 69 6e 20 61 6e 20 4f  ex.** or in an O
22350 52 44 45 52 20 42 59 20 6f 72 20 47 52 4f 55 50  RDER BY or GROUP
22360 20 42 59 20 63 6c 61 75 73 65 2e 3c 2f 64 64 3e   BY clause.</dd>
22370 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22380 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
22390 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  TH]] ^(<dt>SQLIT
223a0 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45 50  E_LIMIT_EXPR_DEP
223b0 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
223c0 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70 74 68  he maximum depth
223d0 20 6f 66 20 74 68 65 20 70 61 72 73 65 20 74 72   of the parse tr
223e0 65 65 20 6f 6e 20 61 6e 79 20 65 78 70 72 65 73  ee on any expres
223f0 73 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  sion.</dd>)^.**.
22400 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
22410 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43  T_COMPOUND_SELEC
22420 54 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  T]] ^(<dt>SQLITE
22430 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
22440 53 45 4c 45 43 54 3c 2f 64 74 3e 0a 2a 2a 20 3c  SELECT</dt>.** <
22450 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e  dd>The maximum n
22460 75 6d 62 65 72 20 6f 66 20 74 65 72 6d 73 20 69  umber of terms i
22470 6e 20 61 20 63 6f 6d 70 6f 75 6e 64 20 53 45 4c  n a compound SEL
22480 45 43 54 20 73 74 61 74 65 6d 65 6e 74 2e 3c 2f  ECT statement.</
22490 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51  dd>)^.**.** [[SQ
224a0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
224b0 4f 50 5d 5d 20 5e 28 3c 64 74 3e 53 51 4c 49 54  OP]] ^(<dt>SQLIT
224c0 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c  E_LIMIT_VDBE_OP<
224d0 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
224e0 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f  maximum number o
224f0 66 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69  f instructions i
22500 6e 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68  n a virtual mach
22510 69 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75  ine program.** u
22520 73 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74  sed to implement
22530 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   an SQL statemen
22540 74 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69  t.  This limit i
22550 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a  s not currently.
22560 2a 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f  ** enforced, tho
22570 75 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62  ugh that might b
22580 65 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20  e added in some 
22590 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
225a0 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64  f.** SQLite.</dd
225b0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  >)^.**.** [[SQLI
225c0 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f  TE_LIMIT_FUNCTIO
225d0 4e 5f 41 52 47 5d 5d 20 5e 28 3c 64 74 3e 53 51  N_ARG]] ^(<dt>SQ
225e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54  LITE_LIMIT_FUNCT
225f0 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a 20  ION_ARG</dt>.** 
22600 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
22610 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d 65  number of argume
22620 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69 6f  nts on a functio
22630 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20  n.</dd>)^.**.** 
22640 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41  [[SQLITE_LIMIT_A
22650 54 54 41 43 48 45 44 5d 5d 20 5e 28 3c 64 74 3e  TTACHED]] ^(<dt>
22660 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
22670 41 43 48 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ACHED</dt>.** <d
22680 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75  d>The maximum nu
22690 6d 62 65 72 20 6f 66 20 5b 41 54 54 41 43 48 20  mber of [ATTACH 
226a0 7c 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  | attached datab
226b0 61 73 65 73 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  ases].)^</dd>.**
226c0 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d  .** [[SQLITE_LIM
226d0 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f  IT_LIKE_PATTERN_
226e0 4c 45 4e 47 54 48 5d 5d 0a 2a 2a 20 5e 28 3c 64  LENGTH]].** ^(<d
226f0 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  t>SQLITE_LIMIT_L
22700 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47  IKE_PATTERN_LENG
22710 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  TH</dt>.** <dd>T
22720 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74  he maximum lengt
22730 68 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e  h of the pattern
22740 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65   argument to the
22750 20 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47   [LIKE] or.** [G
22760 4c 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c  LOB] operators.<
22770 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  /dd>)^.**.** [[S
22780 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49  QLITE_LIMIT_VARI
22790 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 5d 0a 2a 2a  ABLE_NUMBER]].**
227a0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
227b0 4d 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d  MIT_VARIABLE_NUM
227c0 42 45 52 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  BER</dt>.** <dd>
227d0 54 68 65 20 6d 61 78 69 6d 75 6d 20 69 6e 64 65  The maximum inde
227e0 78 20 6e 75 6d 62 65 72 20 6f 66 20 61 6e 79 20  x number of any 
227f0 5b 70 61 72 61 6d 65 74 65 72 5d 20 69 6e 20 61  [parameter] in a
22800 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e  n SQL statement.
22810 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  )^.**.** [[SQLIT
22820 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f  E_LIMIT_TRIGGER_
22830 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e 53 51  DEPTH]] ^(<dt>SQ
22840 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47  LITE_LIMIT_TRIGG
22850 45 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a  ER_DEPTH</dt>.**
22860 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
22870 20 64 65 70 74 68 20 6f 66 20 72 65 63 75 72 73   depth of recurs
22880 69 6f 6e 20 66 6f 72 20 74 72 69 67 67 65 72 73  ion for triggers
22890 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c  .</dd>)^.** </dl
228a0 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
228b0 49 54 45 5f 4c 49 4d 49 54 5f 4c 45 4e 47 54 48  ITE_LIMIT_LENGTH
228c0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
228d0 20 20 20 20 30 0a 23 64 65 66 69 6e 65 20 53 51      0.#define SQ
228e0 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c  LITE_LIMIT_SQL_L
228f0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
22900 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
22910 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55  QLITE_LIMIT_COLU
22920 4d 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 20  MN              
22930 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20        2.#define 
22940 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
22950 52 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20  R_DEPTH         
22960 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
22970 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f   SQLITE_LIMIT_CO
22980 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 20 20 20  MPOUND_SELECT   
22990 20 20 20 20 20 20 20 20 34 0a 23 64 65 66 69 6e          4.#defin
229a0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
229b0 44 42 45 5f 4f 50 20 20 20 20 20 20 20 20 20 20  DBE_OP          
229c0 20 20 20 20 20 20 20 20 20 35 0a 23 64 65 66 69           5.#defi
229d0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
229e0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 20 20 20 20  FUNCTION_ARG    
229f0 20 20 20 20 20 20 20 20 20 20 36 0a 23 64 65 66            6.#def
22a00 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
22a10 5f 41 54 54 41 43 48 45 44 20 20 20 20 20 20 20  _ATTACHED       
22a20 20 20 20 20 20 20 20 20 20 20 20 37 0a 23 64 65             7.#de
22a30 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
22a40 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e 5f 4c  T_LIKE_PATTERN_L
22a50 45 4e 47 54 48 20 20 20 20 20 20 20 38 0a 23 64  ENGTH       8.#d
22a60 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
22a70 49 54 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42  IT_VARIABLE_NUMB
22a80 45 52 20 20 20 20 20 20 20 20 20 20 20 39 0a 23  ER           9.#
22a90 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
22aa0 4d 49 54 5f 54 52 49 47 47 45 52 5f 44 45 50 54  MIT_TRIGGER_DEPT
22ab0 48 20 20 20 20 20 20 20 20 20 20 20 20 31 30 0a  H            10.
22ac0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22ad0 20 43 6f 6d 70 69 6c 69 6e 67 20 41 6e 20 53 51   Compiling An SQ
22ae0 4c 20 53 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b  L Statement.** K
22af0 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 73 74  EYWORDS: {SQL st
22b00 61 74 65 6d 65 6e 74 20 63 6f 6d 70 69 6c 65 72  atement compiler
22b10 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20 65 78 65 63 75  }.**.** To execu
22b20 74 65 20 61 6e 20 53 51 4c 20 71 75 65 72 79 2c  te an SQL query,
22b30 20 69 74 20 6d 75 73 74 20 66 69 72 73 74 20 62   it must first b
22b40 65 20 63 6f 6d 70 69 6c 65 64 20 69 6e 74 6f 20  e compiled into 
22b50 61 20 62 79 74 65 2d 63 6f 64 65 0a 2a 2a 20 70  a byte-code.** p
22b60 72 6f 67 72 61 6d 20 75 73 69 6e 67 20 6f 6e 65  rogram using one
22b70 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
22b80 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  es..**.** The fi
22b90 72 73 74 20 61 72 67 75 6d 65 6e 74 2c 20 22 64  rst argument, "d
22ba0 62 22 2c 20 69 73 20 61 20 5b 64 61 74 61 62 61  b", is a [databa
22bb0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
22bc0 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 0a 2a  btained from a.*
22bd0 2a 20 70 72 69 6f 72 20 73 75 63 63 65 73 73 66  * prior successf
22be0 75 6c 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  ul call to [sqli
22bf0 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
22c00 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
22c10 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   or.** [sqlite3_
22c20 6f 70 65 6e 31 36 28 29 5d 2e 20 20 54 68 65 20  open16()].  The 
22c30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
22c40 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 68 61 76  ion must not hav
22c50 65 20 62 65 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a  e been closed..*
22c60 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20  *.** The second 
22c70 61 72 67 75 6d 65 6e 74 2c 20 22 7a 53 71 6c 22  argument, "zSql"
22c80 2c 20 69 73 20 74 68 65 20 73 74 61 74 65 6d 65  , is the stateme
22c90 6e 74 20 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65  nt to be compile
22ca0 64 2c 20 65 6e 63 6f 64 65 64 0a 2a 2a 20 61 73  d, encoded.** as
22cb0 20 65 69 74 68 65 72 20 55 54 46 2d 38 20 6f 72   either UTF-8 or
22cc0 20 55 54 46 2d 31 36 2e 20 20 54 68 65 20 73 71   UTF-16.  The sq
22cd0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 20  lite3_prepare() 
22ce0 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70  and sqlite3_prep
22cf0 61 72 65 5f 76 32 28 29 0a 2a 2a 20 69 6e 74 65  are_v2().** inte
22d00 72 66 61 63 65 73 20 75 73 65 20 55 54 46 2d 38  rfaces use UTF-8
22d10 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 70 72  , and sqlite3_pr
22d20 65 70 61 72 65 31 36 28 29 20 61 6e 64 20 73 71  epare16() and sq
22d30 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
22d40 76 32 28 29 0a 2a 2a 20 75 73 65 20 55 54 46 2d  v2().** use UTF-
22d50 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  16..**.** ^If th
22d60 65 20 6e 42 79 74 65 20 61 72 67 75 6d 65 6e 74  e nByte argument
22d70 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 7a 65   is less than ze
22d80 72 6f 2c 20 74 68 65 6e 20 7a 53 71 6c 20 69 73  ro, then zSql is
22d90 20 72 65 61 64 20 75 70 20 74 6f 20 74 68 65 0a   read up to the.
22da0 2a 2a 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  ** first zero te
22db0 72 6d 69 6e 61 74 6f 72 2e 20 5e 49 66 20 6e 42  rminator. ^If nB
22dc0 79 74 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  yte is non-negat
22dd0 69 76 65 2c 20 74 68 65 6e 20 69 74 20 69 73 20  ive, then it is 
22de0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e  the maximum.** n
22df0 75 6d 62 65 72 20 6f 66 20 20 62 79 74 65 73 20  umber of  bytes 
22e00 72 65 61 64 20 66 72 6f 6d 20 7a 53 71 6c 2e 20  read from zSql. 
22e10 20 5e 57 68 65 6e 20 6e 42 79 74 65 20 69 73 20   ^When nByte is 
22e20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68  non-negative, th
22e30 65 0a 2a 2a 20 7a 53 71 6c 20 73 74 72 69 6e 67  e.** zSql string
22e40 20 65 6e 64 73 20 61 74 20 65 69 74 68 65 72 20   ends at either 
22e50 74 68 65 20 66 69 72 73 74 20 27 5c 30 30 30 27  the first '\000'
22e60 20 6f 72 20 27 5c 75 30 30 30 30 27 20 63 68 61   or '\u0000' cha
22e70 72 61 63 74 65 72 20 6f 72 0a 2a 2a 20 74 68 65  racter or.** the
22e80 20 6e 42 79 74 65 2d 74 68 20 62 79 74 65 2c 20   nByte-th byte, 
22e90 77 68 69 63 68 65 76 65 72 20 63 6f 6d 65 73 20  whichever comes 
22ea0 66 69 72 73 74 2e 20 49 66 20 74 68 65 20 63 61  first. If the ca
22eb0 6c 6c 65 72 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68  ller knows.** th
22ec0 61 74 20 74 68 65 20 73 75 70 70 6c 69 65 64 20  at the supplied 
22ed0 73 74 72 69 6e 67 20 69 73 20 6e 75 6c 2d 74 65  string is nul-te
22ee0 72 6d 69 6e 61 74 65 64 2c 20 74 68 65 6e 20 74  rminated, then t
22ef0 68 65 72 65 20 69 73 20 61 20 73 6d 61 6c 6c 0a  here is a small.
22f00 2a 2a 20 70 65 72 66 6f 72 6d 61 6e 63 65 20 61  ** performance a
22f10 64 76 61 6e 74 61 67 65 20 74 6f 20 62 65 20 67  dvantage to be g
22f20 61 69 6e 65 64 20 62 79 20 70 61 73 73 69 6e 67  ained by passing
22f30 20 61 6e 20 6e 42 79 74 65 20 70 61 72 61 6d 65   an nByte parame
22f40 74 65 72 20 74 68 61 74 0a 2a 2a 20 69 73 20 65  ter that.** is e
22f50 71 75 61 6c 20 74 6f 20 74 68 65 20 6e 75 6d 62  qual to the numb
22f60 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74  er of bytes in t
22f70 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 20  he input string 
22f80 3c 69 3e 69 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e  <i>including</i>
22f90 0a 2a 2a 20 74 68 65 20 6e 75 6c 2d 74 65 72 6d  .** the nul-term
22fa0 69 6e 61 74 6f 72 20 62 79 74 65 73 20 61 73 20  inator bytes as 
22fb0 74 68 69 73 20 73 61 76 65 73 20 53 51 4c 69 74  this saves SQLit
22fc0 65 20 66 72 6f 6d 20 68 61 76 69 6e 67 20 74 6f  e from having to
22fd0 0a 2a 2a 20 6d 61 6b 65 20 61 20 63 6f 70 79 20  .** make a copy 
22fe0 6f 66 20 74 68 65 20 69 6e 70 75 74 20 73 74 72  of the input str
22ff0 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70  ing..**.** ^If p
23000 7a 54 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c  zTail is not NUL
23010 4c 20 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69  L then *pzTail i
23020 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
23030 74 6f 20 74 68 65 20 66 69 72 73 74 20 62 79 74  to the first byt
23040 65 0a 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e  e.** past the en
23050 64 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 53  d of the first S
23060 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20  QL statement in 
23070 7a 53 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75  zSql.  These rou
23080 74 69 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f  tines only.** co
23090 6d 70 69 6c 65 20 74 68 65 20 66 69 72 73 74 20  mpile the first 
230a0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71  statement in zSq
230b0 6c 2c 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73  l, so *pzTail is
230c0 20 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74   left pointing t
230d0 6f 0a 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e  o.** what remain
230e0 73 20 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a  s uncompiled..**
230f0 0a 2a 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20  .** ^*ppStmt is 
23100 6c 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f  left pointing to
23110 20 61 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65   a compiled [pre
23120 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23130 20 74 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20   that can be.** 
23140 65 78 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b  executed using [
23150 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e  sqlite3_step()].
23160 20 20 5e 49 66 20 74 68 65 72 65 20 69 73 20 61    ^If there is a
23170 6e 20 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74  n error, *ppStmt
23180 20 69 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55   is set.** to NU
23190 4c 4c 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70  LL.  ^If the inp
231a0 75 74 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73  ut text contains
231b0 20 6e 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20   no SQL (if the 
231c0 69 6e 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74  input is an empt
231d0 79 0a 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61  y.** string or a
231e0 20 63 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a   comment) then *
231f0 70 70 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f  ppStmt is set to
23200 20 4e 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61   NULL..** The ca
23210 6c 6c 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20  lling procedure 
23220 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66  is responsible f
23230 6f 72 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20  or deleting the 
23240 63 6f 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20  compiled.** SQL 
23250 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20  statement using 
23260 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
23270 65 28 29 5d 20 61 66 74 65 72 20 69 74 20 68 61  e()] after it ha
23280 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
23290 69 74 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61  it..** ppStmt ma
232a0 79 20 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a  y not be NULL..*
232b0 2a 0a 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73  *.** ^On success
232c0 2c 20 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72  , the sqlite3_pr
232d0 65 70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f  epare() family o
232e0 66 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  f routines retur
232f0 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a  n [SQLITE_OK];.*
23300 2a 20 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b  * otherwise an [
23310 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72  error code] is r
23320 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  eturned..**.** T
23330 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
23340 72 65 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69  re_v2() and sqli
23350 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
23360 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  () interfaces ar
23370 65 0a 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e.** recommended
23380 20 66 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f   for all new pro
23390 67 72 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f  grams. The two o
233a0 6c 64 65 72 20 69 6e 74 65 72 66 61 63 65 73 20  lder interfaces 
233b0 61 72 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20  are retained.** 
233c0 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f  for backwards co
233d0 6d 70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74  mpatibility, but
233e0 20 74 68 65 69 72 20 75 73 65 20 69 73 20 64 69   their use is di
233f0 73 63 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49  scouraged..** ^I
23400 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
23410 66 61 63 65 73 2c 20 74 68 65 20 70 72 65 70 61  faces, the prepa
23420 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
23430 20 74 68 61 74 20 69 73 20 72 65 74 75 72 6e 65   that is returne
23440 64 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  d (the [sqlite3_
23450 73 74 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f  stmt] object) co
23460 6e 74 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66  ntains a copy of
23470 20 74 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c   the.** original
23480 20 53 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20   SQL text. This 
23490 63 61 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69  causes the [sqli
234a0 74 65 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65  te3_step()] inte
234b0 72 66 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61  rface to.** beha
234c0 76 65 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69  ve differently i
234d0 6e 20 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a  n three ways:.**
234e0 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e  .** <ol>.** <li>
234f0 0a 2a 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61  .** ^If the data
23500 62 61 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e  base schema chan
23510 67 65 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20  ges, instead of 
23520 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
23530 45 5f 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a  E_SCHEMA] as it.
23540 2a 2a 20 61 6c 77 61 79 73 20 75 73 65 64 20 74  ** always used t
23550 6f 20 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73  o do, [sqlite3_s
23560 74 65 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f  tep()] will auto
23570 6d 61 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70  matically recomp
23580 69 6c 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73  ile the SQL.** s
23590 74 61 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79  tatement and try
235a0 20 74 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e   to run it again
235b0 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a  ..** </li>.**.**
235c0 20 3c 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61   <li>.** ^When a
235d0 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20  n error occurs, 
235e0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
235f0 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65   will return one
23600 20 6f 66 20 74 68 65 20 64 65 74 61 69 6c 65 64   of the detailed
23610 0a 2a 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73  .** [error codes
23620 5d 20 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65  ] or [extended e
23630 72 72 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54  rror codes].  ^T
23640 68 65 20 6c 65 67 61 63 79 20 62 65 68 61 76 69  he legacy behavi
23650 6f 72 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b  or was that.** [
23660 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
23670 77 6f 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72  would only retur
23680 6e 20 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c  n a generic [SQL
23690 49 54 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c  ITE_ERROR] resul
236a0 74 20 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68  t code.** and th
236b0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f  e application wo
236c0 75 6c 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65  uld have to make
236d0 20 61 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74   a second call t
236e0 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  o [sqlite3_reset
236f0 28 29 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20  ()].** in order 
23700 74 6f 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65  to find the unde
23710 72 6c 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20  rlying cause of 
23720 74 68 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74  the problem. Wit
23730 68 20 74 68 65 20 22 76 32 22 20 70 72 65 70 61  h the "v2" prepa
23740 72 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73  re.** interfaces
23750 2c 20 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67  , the underlying
23760 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20   reason for the 
23770 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
23780 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a  d immediately..*
23790 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c  * </li>.**.** <l
237a0 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  i>.** ^If the sp
237b0 65 63 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75  ecific value bou
237c0 6e 64 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72  nd to [parameter
237d0 20 7c 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65   | host paramete
237e0 72 5d 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48  r] in the .** WH
237f0 45 52 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74  ERE clause might
23800 20 69 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63   influence the c
23810 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
23820 6c 61 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d  lan for a statem
23830 65 6e 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ent,.** then the
23840 20 73 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20   statement will 
23850 62 65 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  be automatically
23860 20 72 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20   recompiled, as 
23870 69 66 20 74 68 65 72 65 20 68 61 64 20 62 65 65  if there had bee
23880 6e 20 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63  n .** a schema c
23890 68 61 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69  hange, on the fi
238a0 72 73 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74  rst  [sqlite3_st
238b0 65 70 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f  ep()] call follo
238c0 77 69 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a  wing any change.
238d0 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74  ** to the [sqlit
238e0 65 33 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62  e3_bind_text | b
238f0 69 6e 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74  indings] of that
23900 20 5b 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a   [parameter]. .*
23910 2a 20 5e 54 68 65 20 73 70 65 63 69 66 69 63 20  * ^The specific 
23920 76 61 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63  value of WHERE-c
23930 6c 61 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72  lause [parameter
23940 5d 20 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63  ] might influenc
23950 65 20 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65  e the .** choice
23960 20 6f 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69   of query plan i
23970 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20  f the parameter 
23980 69 73 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64  is the left-hand
23990 20 73 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45   side of a [LIKE
239a0 5d 0a 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f  ].** or [GLOB] o
239b0 70 65 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68  perator or if th
239c0 65 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 63  e parameter is c
239d0 6f 6d 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e  ompared to an in
239e0 64 65 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  dexed column.** 
239f0 61 6e 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  and the [SQLITE_
23a00 45 4e 41 42 4c 45 5f 53 54 41 54 33 5d 20 63 6f  ENABLE_STAT3] co
23a10 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
23a20 6e 20 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  n is enabled..**
23a30 20 74 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a   the .** </li>.*
23a40 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73  * </ol>.*/.int s
23a50 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a  qlite3_prepare(.
23a60 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
23a70 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
23a80 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
23a90 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53    const char *zS
23aa0 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
23ab0 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
23ac0 38 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69  8 encoded */.  i
23ad0 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20  nt nByte,       
23ae0 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75         /* Maximu
23af0 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c  m length of zSql
23b00 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20   in bytes. */.  
23b10 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70  sqlite3_stmt **p
23b20 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20  pStmt,  /* OUT: 
23b30 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65  Statement handle
23b40 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
23b50 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a   **pzTail     /*
23b60 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f   OUT: Pointer to
23b70 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20   unused portion 
23b80 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e  of zSql */.);.in
23b90 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  t sqlite3_prepar
23ba0 65 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20  e_v2(.  sqlite3 
23bb0 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20  *db,            
23bc0 2f 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64  /* Database hand
23bd0 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68  le */.  const ch
23be0 61 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20  ar *zSql,       
23bf0 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  /* SQL statement
23c00 2c 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20  , UTF-8 encoded 
23c10 2a 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20  */.  int nByte, 
23c20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
23c30 4d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  Maximum length o
23c40 66 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e  f zSql in bytes.
23c50 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74   */.  sqlite3_st
23c60 6d 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a  mt **ppStmt,  /*
23c70 20 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20   OUT: Statement 
23c80 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73  handle */.  cons
23c90 74 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20  t char **pzTail 
23ca0 20 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e      /* OUT: Poin
23cb0 74 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f  ter to unused po
23cc0 72 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f  rtion of zSql */
23cd0 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
23ce0 70 72 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c  prepare16(.  sql
23cf0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
23d00 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
23d10 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
23d20 73 74 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20  st void *zSql,  
23d30 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
23d40 65 6d 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e  ement, UTF-16 en
23d50 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e  coded */.  int n
23d60 42 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20  Byte,           
23d70 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65     /* Maximum le
23d80 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20  ngth of zSql in 
23d90 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69  bytes. */.  sqli
23da0 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d  te3_stmt **ppStm
23db0 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74  t,  /* OUT: Stat
23dc0 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a  ement handle */.
23dd0 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70    const void **p
23de0 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54  zTail     /* OUT
23df0 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75  : Pointer to unu
23e00 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a  sed portion of z
23e10 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71  Sql */.);.int sq
23e20 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
23e30 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
23e40 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
23e50 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
23e60 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64   */.  const void
23e70 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
23e80 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
23e90 55 54 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a  UTF-16 encoded *
23ea0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
23eb0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
23ec0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
23ed0 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
23ee0 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
23ef0 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
23f00 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
23f10 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
23f20 20 76 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20   void **pzTail  
23f30 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
23f40 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
23f50 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
23f60 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
23f70 45 46 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53  EF: Retrieving S
23f80 74 61 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a  tatement SQL.**.
23f90 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61  ** ^This interfa
23fa0 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 74  ce can be used t
23fb0 6f 20 72 65 74 72 69 65 76 65 20 61 20 73 61 76  o retrieve a sav
23fc0 65 64 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f  ed copy of the o
23fd0 72 69 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74  riginal.** SQL t
23fe0 65 78 74 20 75 73 65 64 20 74 6f 20 63 72 65 61  ext used to crea
23ff0 74 65 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  te a [prepared s
24000 74 61 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61  tatement] if tha
24010 74 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a  t statement was.
24020 2a 2a 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e  ** compiled usin
24030 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
24040 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
24050 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
24060 61 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a  are16_v2()]..*/.
24070 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
24080 74 65 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f  te3_sql(sqlite3_
24090 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
240a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
240b0 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53  etermine If An S
240c0 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69  QL Statement Wri
240d0 74 65 73 20 54 68 65 20 44 61 74 61 62 61 73 65  tes The Database
240e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
240f0 74 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c  te3_stmt_readonl
24100 79 28 58 29 20 69 6e 74 65 72 66 61 63 65 20 72  y(X) interface r
24110 65 74 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e  eturns true (non
24120 2d 7a 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64  -zero) if.** and
24130 20 6f 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72   only if the [pr
24140 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
24150 5d 20 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72  ] X makes no dir
24160 65 63 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a  ect changes to.*
24170 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66  * the content of
24180 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
24190 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74  le..**.** Note t
241a0 68 61 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e  hat [application
241b0 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e  -defined SQL fun
241c0 63 74 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76  ctions] or.** [v
241d0 69 72 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d  irtual tables] m
241e0 69 67 68 74 20 63 68 61 6e 67 65 20 74 68 65 20  ight change the 
241f0 64 61 74 61 62 61 73 65 20 69 6e 64 69 72 65 63  database indirec
24200 74 6c 79 20 61 73 20 61 20 73 69 64 65 20 65 66  tly as a side ef
24210 66 65 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72  fect.  .** ^(For
24220 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20   example, if an 
24230 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69  application defi
24240 6e 65 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22  nes a function "
24250 65 76 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a  eval()" that .**
24260 20 63 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f   calls [sqlite3_
24270 65 78 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68  exec()], then th
24280 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20  e following SQL 
24290 73 74 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a  statement would.
242a0 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ** change the da
242b0 74 61 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f  tabase file thro
242c0 75 67 68 20 73 69 64 65 2d 65 66 66 65 63 74 73  ugh side-effects
242d0 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
242e0 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
242f0 53 45 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c  SELECT eval('DEL
24300 45 54 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52  ETE FROM t1') FR
24310 4f 4d 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e  OM t2;.** </pre>
24320 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
24330 0a 2a 2a 20 42 75 74 20 62 65 63 61 75 73 65 20  .** But because 
24340 74 68 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  the [SELECT] sta
24350 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20  tement does not 
24360 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61 62  change the datab
24370 61 73 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65  ase file.** dire
24380 63 74 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74  ctly, sqlite3_st
24390 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f  mt_readonly() wo
243a0 75 6c 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e  uld still return
243b0 20 74 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e   true.)^.**.** ^
243c0 54 72 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74  Transaction cont
243d0 72 6f 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73  rol statements s
243e0 75 63 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20  uch as [BEGIN], 
243f0 5b 43 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42  [COMMIT], [ROLLB
24400 41 43 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f  ACK],.** [SAVEPO
24410 49 4e 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41  INT], and [RELEA
24420 53 45 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65  SE] cause sqlite
24430 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
24440 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65  ) to return true
24450 2c 0a 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73  ,.** since the s
24460 74 61 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65  tatements themse
24470 6c 76 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75  lves do not actu
24480 61 6c 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20  ally modify the 
24490 64 61 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20  database but.** 
244a0 72 61 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74  rather they cont
244b0 72 6f 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f  rol the timing o
244c0 66 20 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61  f when other sta
244d0 74 65 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74  tements modify t
244e0 68 65 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e  he .** database.
244f0 20 20 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20    ^The [ATTACH] 
24500 61 6e 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61  and [DETACH] sta
24510 74 65 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75  tements also cau
24520 73 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74  se.** sqlite3_st
24530 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f  mt_readonly() to
24540 20 72 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e   return true sin
24550 63 65 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20  ce, while those 
24560 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68  statements.** ch
24570 61 6e 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75  ange the configu
24580 72 61 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61  ration of a data
24590 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c  base connection,
245a0 20 74 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b   they do not mak
245b0 65 20 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f  e .** changes to
245c0 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
245d0 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c  the database fil
245e0 65 73 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69  es on disk..*/.i
245f0 6e 74 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f  nt sqlite3_stmt_
24600 72 65 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33  readonly(sqlite3
24610 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
24620 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
24630 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 20 50  Determine If A P
24640 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e  repared Statemen
24650 74 20 48 61 73 20 42 65 65 6e 20 52 65 73 65 74  t Has Been Reset
24660 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
24670 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29  te3_stmt_busy(S)
24680 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
24690 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a 65 72  ns true (non-zer
246a0 6f 29 20 69 66 20 74 68 65 0a 2a 2a 20 5b 70 72  o) if the.** [pr
246b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
246c0 5d 20 53 20 68 61 73 20 62 65 65 6e 20 73 74 65  ] S has been ste
246d0 70 70 65 64 20 61 74 20 6c 65 61 73 74 20 6f 6e  pped at least on
246e0 63 65 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71  ce using .** [sq
246f0 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 62  lite3_step(S)] b
24700 75 74 20 68 61 73 20 6e 6f 74 20 72 75 6e 20 74  ut has not run t
24710 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 6e 64  o completion and
24720 2f 6f 72 20 68 61 73 20 6e 6f 74 20 0a 2a 2a 20  /or has not .** 
24730 62 65 65 6e 20 72 65 73 65 74 20 75 73 69 6e 67  been reset using
24740 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
24750 53 29 5d 2e 20 20 5e 54 68 65 20 73 71 6c 69 74  S)].  ^The sqlit
24760 65 33 5f 73 74 6d 74 5f 62 75 73 79 28 53 29 0a  e3_stmt_busy(S).
24770 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  ** interface ret
24780 75 72 6e 73 20 66 61 6c 73 65 20 69 66 20 53 20  urns false if S 
24790 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
247a0 72 2e 20 20 49 66 20 53 20 69 73 20 6e 6f 74 20  r.  If S is not 
247b0 61 20 0a 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74  a .** NULL point
247c0 65 72 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  er and is not a 
247d0 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 76 61 6c  pointer to a val
247e0 69 64 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  id [prepared sta
247f0 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
24800 74 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  t, then the beha
24810 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65  vior is undefine
24820 64 20 61 6e 64 20 70 72 6f 62 61 62 6c 79 20 75  d and probably u
24830 6e 64 65 73 69 72 61 62 6c 65 2e 0a 2a 2a 0a 2a  ndesirable..**.*
24840 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61 63 65  * This interface
24850 20 63 61 6e 20 62 65 20 75 73 65 64 20 69 6e 20   can be used in 
24860 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 5b 73 71 6c  combination [sql
24870 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28 29  ite3_next_stmt()
24880 5d 0a 2a 2a 20 74 6f 20 6c 6f 63 61 74 65 20 61  ].** to locate a
24890 6c 6c 20 70 72 65 70 61 72 65 64 20 73 74 61 74  ll prepared stat
248a0 65 6d 65 6e 74 73 20 61 73 73 6f 63 69 61 74 65  ements associate
248b0 64 20 77 69 74 68 20 61 20 64 61 74 61 62 61 73  d with a databas
248c0 65 20 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e  e .** connection
248d0 20 74 68 61 74 20 61 72 65 20 69 6e 20 6e 65 65   that are in nee
248e0 64 20 6f 66 20 62 65 69 6e 67 20 72 65 73 65 74  d of being reset
248f0 2e 20 20 54 68 69 73 20 63 61 6e 20 62 65 20 75  .  This can be u
24900 73 65 64 2c 0a 2a 2a 20 66 6f 72 20 65 78 61 6d  sed,.** for exam
24910 70 6c 65 2c 20 69 6e 20 64 69 61 67 6e 6f 73 74  ple, in diagnost
24920 69 63 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 73  ic routines to s
24930 65 61 72 63 68 20 66 6f 72 20 70 72 65 70 61 72  earch for prepar
24940 65 64 20 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74  ed .** statement
24950 73 20 74 68 61 74 20 61 72 65 20 68 6f 6c 64 69  s that are holdi
24960 6e 67 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  ng a transaction
24970 20 6f 70 65 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71   open..*/.int sq
24980 6c 69 74 65 33 5f 73 74 6d 74 5f 62 75 73 79 28  lite3_stmt_busy(
24990 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a  sqlite3_stmt*);.
249a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
249b0 20 44 79 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70   Dynamically Typ
249c0 65 64 20 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a  ed Value Object.
249d0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
249e0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
249f0 76 61 6c 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63  value} {unprotec
24a00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
24a10 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  e}.**.** SQLite 
24a20 75 73 65 73 20 74 68 65 20 73 71 6c 69 74 65 33  uses the sqlite3
24a30 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f  _value object to
24a40 20 72 65 70 72 65 73 65 6e 74 20 61 6c 6c 20 76   represent all v
24a50 61 6c 75 65 73 0a 2a 2a 20 74 68 61 74 20 63 61  alues.** that ca
24a60 6e 20 62 65 20 73 74 6f 72 65 64 20 69 6e 20 61  n be stored in a
24a70 20 64 61 74 61 62 61 73 65 20 74 61 62 6c 65 2e   database table.
24a80 20 53 51 4c 69 74 65 20 75 73 65 73 20 64 79 6e   SQLite uses dyn
24a90 61 6d 69 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66  amic typing.** f
24aa0 6f 72 20 74 68 65 20 76 61 6c 75 65 73 20 69 74  or the values it
24ab0 20 73 74 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65   stores.  ^Value
24ac0 73 20 73 74 6f 72 65 64 20 69 6e 20 73 71 6c 69  s stored in sqli
24ad0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
24ae0 73 0a 2a 2a 20 63 61 6e 20 62 65 20 69 6e 74 65  s.** can be inte
24af0 67 65 72 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70  gers, floating p
24b00 6f 69 6e 74 20 76 61 6c 75 65 73 2c 20 73 74 72  oint values, str
24b10 69 6e 67 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20  ings, BLOBs, or 
24b20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73  NULL..**.** An s
24b30 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
24b40 65 63 74 20 6d 61 79 20 62 65 20 65 69 74 68 65  ect may be eithe
24b50 72 20 22 70 72 6f 74 65 63 74 65 64 22 20 6f 72  r "protected" or
24b60 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a   "unprotected"..
24b70 2a 2a 20 53 6f 6d 65 20 69 6e 74 65 72 66 61 63  ** Some interfac
24b80 65 73 20 72 65 71 75 69 72 65 20 61 20 70 72 6f  es require a pro
24b90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24ba0 61 6c 75 65 2e 20 20 4f 74 68 65 72 20 69 6e 74  alue.  Other int
24bb0 65 72 66 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20  erfaces.** will 
24bc0 61 63 63 65 70 74 20 65 69 74 68 65 72 20 61 20  accept either a 
24bd0 70 72 6f 74 65 63 74 65 64 20 6f 72 20 61 6e 20  protected or an 
24be0 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
24bf0 74 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76  te3_value..** Ev
24c00 65 72 79 20 69 6e 74 65 72 66 61 63 65 20 74 68  ery interface th
24c10 61 74 20 61 63 63 65 70 74 73 20 73 71 6c 69 74  at accepts sqlit
24c20 65 33 5f 76 61 6c 75 65 20 61 72 67 75 6d 65 6e  e3_value argumen
24c30 74 73 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20  ts specifies.** 
24c40 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 69  whether or not i
24c50 74 20 72 65 71 75 69 72 65 73 20 61 20 70 72 6f  t requires a pro
24c60 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
24c70 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  alue..**.** The 
24c80 74 65 72 6d 73 20 22 70 72 6f 74 65 63 74 65 64  terms "protected
24c90 22 20 61 6e 64 20 22 75 6e 70 72 6f 74 65 63 74  " and "unprotect
24ca0 65 64 22 20 72 65 66 65 72 20 74 6f 20 77 68 65  ed" refer to whe
24cb0 74 68 65 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61  ther or not.** a
24cc0 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 2e 20   mutex is held. 
24cd0 20 41 6e 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74   An internal mut
24ce0 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20 61  ex is held for a
24cf0 20 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71   protected.** sq
24d00 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24d10 63 74 20 62 75 74 20 6e 6f 20 6d 75 74 65 78 20  ct but no mutex 
24d20 69 73 20 68 65 6c 64 20 66 6f 72 20 61 6e 20 75  is held for an u
24d30 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71  nprotected.** sq
24d40 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65  lite3_value obje
24d50 63 74 2e 20 20 49 66 20 53 51 4c 69 74 65 20 69  ct.  If SQLite i
24d60 73 20 63 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65  s compiled to be
24d70 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 65 64   single-threaded
24d80 0a 2a 2a 20 28 77 69 74 68 20 5b 53 51 4c 49 54  .** (with [SQLIT
24d90 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
24da0 61 6e 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  and with [sqlite
24db0 33 5f 74 68 72 65 61 64 73 61 66 65 28 29 5d 20  3_threadsafe()] 
24dc0 72 65 74 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20  returning 0).** 
24dd0 6f 72 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  or if SQLite is 
24de0 72 75 6e 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65  run in one of re
24df0 64 75 63 65 64 20 6d 75 74 65 78 20 6d 6f 64 65  duced mutex mode
24e00 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f  s .** [SQLITE_CO
24e10 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
24e20 44 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  D] or [SQLITE_CO
24e30 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44  NFIG_MULTITHREAD
24e40 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 72 65 20  ].** then there 
24e50 69 73 20 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f  is no distinctio
24e60 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65 63  n between protec
24e70 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65 63  ted and unprotec
24e80 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76  ted.** sqlite3_v
24e90 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 61 6e 64  alue objects and
24ea0 20 74 68 65 79 20 63 61 6e 20 62 65 20 75 73 65   they can be use
24eb0 64 20 69 6e 74 65 72 63 68 61 6e 67 65 61 62 6c  d interchangeabl
24ec0 79 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20  y.  However,.** 
24ed0 66 6f 72 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65  for maximum code
24ee0 20 70 6f 72 74 61 62 69 6c 69 74 79 20 69 74 20   portability it 
24ef0 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74  is recommended t
24f00 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  hat applications
24f10 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74  .** still make t
24f20 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  he distinction b
24f30 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
24f40 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
24f50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
24f60 65 20 6f 62 6a 65 63 74 73 20 65 76 65 6e 20 77  e objects even w
24f70 68 65 6e 20 6e 6f 74 20 73 74 72 69 63 74 6c 79  hen not strictly
24f80 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
24f90 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61   ^The sqlite3_va
24fa0 6c 75 65 20 6f 62 6a 65 63 74 73 20 74 68 61 74  lue objects that
24fb0 20 61 72 65 20 70 61 73 73 65 64 20 61 73 20 70   are passed as p
24fc0 61 72 61 6d 65 74 65 72 73 20 69 6e 74 6f 20 74  arameters into t
24fd0 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61  he.** implementa
24fe0 74 69 6f 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61  tion of [applica
24ff0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c  tion-defined SQL
25000 20 66 75 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20   functions] are 
25010 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54  protected..** ^T
25020 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
25030 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
25040 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   by.** [sqlite3_
25050 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20  column_value()] 
25060 69 73 20 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a  is unprotected..
25070 2a 2a 20 55 6e 70 72 6f 74 65 63 74 65 64 20 73  ** Unprotected s
25080 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a  qlite3_value obj
25090 65 63 74 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65  ects may only be
250a0 20 75 73 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73   used with.** [s
250b0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
250c0 6c 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  lue()] and [sqli
250d0 74 65 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29  te3_bind_value()
250e0 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  ]..** The [sqlit
250f0 65 33 5f 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20  e3_value_blob | 
25100 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79  sqlite3_value_ty
25110 70 65 28 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a  pe()] family of.
25120 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 72 65  ** interfaces re
25130 71 75 69 72 65 20 70 72 6f 74 65 63 74 65 64 20  quire protected 
25140 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
25150 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65  jects..*/.typede
25160 66 20 73 74 72 75 63 74 20 4d 65 6d 20 73 71 6c  f struct Mem sql
25170 69 74 65 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a  ite3_value;../*.
25180 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c  ** CAPI3REF: SQL
25190 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
251a0 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54  t Object.**.** T
251b0 68 65 20 63 6f 6e 74 65 78 74 20 69 6e 20 77 68  he context in wh
251c0 69 63 68 20 61 6e 20 53 51 4c 20 66 75 6e 63 74  ich an SQL funct
251d0 69 6f 6e 20 65 78 65 63 75 74 65 73 20 69 73 20  ion executes is 
251e0 73 74 6f 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20  stored in an.** 
251f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
25200 6f 62 6a 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e  object.  ^A poin
25210 74 65 72 20 74 6f 20 61 6e 20 73 71 6c 69 74 65  ter to an sqlite
25220 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74  3_context object
25230 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 66 69  .** is always fi
25240 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rst parameter to
25250 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65   [application-de
25260 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69  fined SQL functi
25270 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70  ons]..** The app
25280 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
25290 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d   SQL function im
252a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c  plementation wil
252b0 6c 20 70 61 73 73 20 74 68 69 73 0a 2a 2a 20 70  l pass this.** p
252c0 6f 69 6e 74 65 72 20 74 68 72 6f 75 67 68 20 69  ointer through i
252d0 6e 74 6f 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71  nto calls to [sq
252e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
252f0 20 7c 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c   | sqlite3_resul
25300 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65  t()],.** [sqlite
25310 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
25320 65 78 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ext()], [sqlite3
25330 5f 75 73 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a  _user_data()],.*
25340 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
25350 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c  xt_db_handle()],
25360 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   [sqlite3_get_au
25370 78 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64  xdata()],.** and
25380 2f 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73 65 74  /or [sqlite3_set
25390 5f 61 75 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a  _auxdata()]..*/.
253a0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
253b0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 73  qlite3_context s
253c0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a  qlite3_context;.
253d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
253e0 20 42 69 6e 64 69 6e 67 20 56 61 6c 75 65 73 20   Binding Values 
253f0 54 6f 20 50 72 65 70 61 72 65 64 20 53 74 61 74  To Prepared Stat
25400 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52  ements.** KEYWOR
25410 44 53 3a 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  DS: {host parame
25420 74 65 72 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d  ter} {host param
25430 65 74 65 72 73 7d 20 7b 68 6f 73 74 20 70 61 72  eters} {host par
25440 61 6d 65 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20  ameter name}.** 
25450 4b 45 59 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70  KEYWORDS: {SQL p
25460 61 72 61 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70  arameter} {SQL p
25470 61 72 61 6d 65 74 65 72 73 7d 20 7b 70 61 72 61  arameters} {para
25480 6d 65 74 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a  meter binding}.*
25490 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 65 20 53 51  *.** ^(In the SQ
254a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 74 65 78 74  L statement text
254b0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
254c0 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
254d0 20 61 6e 64 20 69 74 73 20 76 61 72 69 61 6e 74   and its variant
254e0 73 2c 0a 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d  s,.** literals m
254f0 61 79 20 62 65 20 72 65 70 6c 61 63 65 64 20 62  ay be replaced b
25500 79 20 61 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  y a [parameter] 
25510 74 68 61 74 20 6d 61 74 63 68 65 73 20 6f 6e 65  that matches one
25520 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a   of following.**
25530 20 74 65 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a   templates:.**.*
25540 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
25550 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a  ?.** <li>  ?NNN.
25560 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a  ** <li>  :VVV.**
25570 20 3c 6c 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c   <li>  @VVV.** <
25580 6c 69 3e 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75  li>  $VVV.** </u
25590 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20  l>.**.** In the 
255a0 74 65 6d 70 6c 61 74 65 73 20 61 62 6f 76 65 2c  templates above,
255b0 20 4e 4e 4e 20 72 65 70 72 65 73 65 6e 74 73 20   NNN represents 
255c0 61 6e 20 69 6e 74 65 67 65 72 20 6c 69 74 65 72  an integer liter
255d0 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72  al,.** and VVV r
255e0 65 70 72 65 73 65 6e 74 73 20 61 6e 20 61 6c 70  epresents an alp
255f0 68 61 6e 75 6d 65 72 69 63 20 69 64 65 6e 74 69  hanumeric identi
25600 66 69 65 72 2e 29 5e 20 20 5e 54 68 65 20 76 61  fier.)^  ^The va
25610 6c 75 65 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a  lues of these.**
25620 20 70 61 72 61 6d 65 74 65 72 73 20 28 61 6c 73   parameters (als
25630 6f 20 63 61 6c 6c 65 64 20 22 68 6f 73 74 20 70  o called "host p
25640 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 73 22 20  arameter names" 
25650 6f 72 20 22 53 51 4c 20 70 61 72 61 6d 65 74 65  or "SQL paramete
25660 72 73 22 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73  rs").** can be s
25670 65 74 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c  et using the sql
25680 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
25690 75 74 69 6e 65 73 20 64 65 66 69 6e 65 64 20 68  utines defined h
256a0 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ere..**.** ^The 
256b0 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
256c0 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69  o the sqlite3_bi
256d0 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 73 20  nd_*() routines 
256e0 69 73 20 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70  is always.** a p
256f0 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73  ointer to the [s
25700 71 6c 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a  qlite3_stmt] obj
25710 65 63 74 20 72 65 74 75 72 6e 65 64 20 66 72 6f  ect returned fro
25720 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  m.** [sqlite3_pr
25730 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 69  epare_v2()] or i
25740 74 73 20 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a  ts variants..**.
25750 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
25760 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 69  rgument is the i
25770 6e 64 65 78 20 6f 66 20 74 68 65 20 53 51 4c 20  ndex of the SQL 
25780 70 61 72 61 6d 65 74 65 72 20 74 6f 20 62 65 20  parameter to be 
25790 73 65 74 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66  set..** ^The lef
257a0 74 6d 6f 73 74 20 53 51 4c 20 70 61 72 61 6d 65  tmost SQL parame
257b0 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64 65 78  ter has an index
257c0 20 6f 66 20 31 2e 20 20 5e 57 68 65 6e 20 74 68   of 1.  ^When th
257d0 65 20 73 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20  e same named.** 
257e0 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 69 73  SQL parameter is
257f0 20 75 73 65 64 20 6d 6f 72 65 20 74 68 61 6e 20   used more than 
25800 6f 6e 63 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64  once, second and
25810 20 73 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f   subsequent.** o
25820 63 63 75 72 72 65 6e 63 65 73 20 68 61 76 65 20  ccurrences have 
25830 74 68 65 20 73 61 6d 65 20 69 6e 64 65 78 20 61  the same index a
25840 73 20 74 68 65 20 66 69 72 73 74 20 6f 63 63 75  s the first occu
25850 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20  rrence..** ^The 
25860 69 6e 64 65 78 20 66 6f 72 20 6e 61 6d 65 64 20  index for named 
25870 70 61 72 61 6d 65 74 65 72 73 20 63 61 6e 20 62  parameters can b
25880 65 20 6c 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e  e looked up usin
25890 67 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  g the.** [sqlite
258a0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
258b0 5f 69 6e 64 65 78 28 29 5d 20 41 50 49 20 69 66  _index()] API if
258c0 20 64 65 73 69 72 65 64 2e 20 20 5e 54 68 65 20   desired.  ^The 
258d0 69 6e 64 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e  index.** for "?N
258e0 4e 4e 22 20 70 61 72 61 6d 65 74 65 72 73 20 69  NN" parameters i
258f0 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 4e  s the value of N
25900 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20  NN..** ^The NNN 
25910 76 61 6c 75 65 20 6d 75 73 74 20 62 65 20 62 65  value must be be
25920 74 77 65 65 6e 20 31 20 61 6e 64 20 74 68 65 20  tween 1 and the 
25930 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29  [sqlite3_limit()
25940 5d 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 5b  ].** parameter [
25950 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52  SQLITE_LIMIT_VAR
25960 49 41 42 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64  IABLE_NUMBER] (d
25970 65 66 61 75 6c 74 20 76 61 6c 75 65 3a 20 39 39  efault value: 99
25980 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74  9)..**.** ^The t
25990 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
259a0 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 62 69   the value to bi
259b0 6e 64 20 74 6f 20 74 68 65 20 70 61 72 61 6d 65  nd to the parame
259c0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20  ter..**.** ^(In 
259d0 74 68 6f 73 65 20 72 6f 75 74 69 6e 65 73 20 74  those routines t
259e0 68 61 74 20 68 61 76 65 20 61 20 66 6f 75 72 74  hat have a fourt
259f0 68 20 61 72 67 75 6d 65 6e 74 2c 20 69 74 73 20  h argument, its 
25a00 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a 20  value is the.** 
25a10 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
25a20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  in the parameter
25a30 2e 20 20 54 6f 20 62 65 20 63 6c 65 61 72 3a 20  .  To be clear: 
25a40 74 68 65 20 76 61 6c 75 65 20 69 73 20 74 68 65  the value is the
25a50 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75  .** number of <u
25a60 3e 62 79 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68  >bytes</u> in th
25a70 65 20 76 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65  e value, not the
25a80 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 72 61   number of chara
25a90 63 74 65 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20  cters.)^.** ^If 
25aa0 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  the fourth param
25ab0 65 74 65 72 20 69 73 20 6e 65 67 61 74 69 76 65  eter is negative
25ac0 2c 20 74 68 65 20 6c 65 6e 67 74 68 20 6f 66 20  , the length of 
25ad0 74 68 65 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a  the string is.**
25ae0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62   the number of b
25af0 79 74 65 73 20 75 70 20 74 6f 20 74 68 65 20 66  ytes up to the f
25b00 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
25b10 61 74 6f 72 2e 0a 2a 2a 20 49 66 20 61 20 6e 6f  ator..** If a no
25b20 6e 2d 6e 65 67 61 74 69 76 65 20 66 6f 75 72 74  n-negative fourt
25b30 68 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 70  h parameter is p
25b40 72 6f 76 69 64 65 64 20 74 6f 20 73 71 6c 69 74  rovided to sqlit
25b50 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 0a 2a  e3_bind_text().*
25b60 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69 6e  * or sqlite3_bin
25b70 64 5f 74 65 78 74 31 36 28 29 20 74 68 65 6e 20  d_text16() then 
25b80 74 68 61 74 20 70 61 72 61 6d 65 74 65 72 20 6d  that parameter m
25b90 75 73 74 20 62 65 20 74 68 65 20 62 79 74 65 20  ust be the byte 
25ba0 6f 66 66 73 65 74 0a 2a 2a 20 77 68 65 72 65 20  offset.** where 
25bb0 74 68 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74  the NUL terminat
25bc0 6f 72 20 77 6f 75 6c 64 20 6f 63 63 75 72 20 61  or would occur a
25bd0 73 73 75 6d 69 6e 67 20 74 68 65 20 73 74 72 69  ssuming the stri
25be0 6e 67 20 77 65 72 65 20 4e 55 4c 0a 2a 2a 20 74  ng were NUL.** t
25bf0 65 72 6d 69 6e 61 74 65 64 2e 20 20 49 66 20 61  erminated.  If a
25c00 6e 79 20 4e 55 4c 20 63 68 61 72 61 63 74 65 72  ny NUL character
25c10 73 20 6f 63 63 75 72 20 61 74 20 62 79 74 65 20  s occur at byte 
25c20 6f 66 66 73 65 74 73 20 6c 65 73 73 20 74 68 61  offsets less tha
25c30 6e 20 0a 2a 2a 20 74 68 65 20 76 61 6c 75 65 20  n .** the value 
25c40 6f 66 20 74 68 65 20 66 6f 75 72 74 68 20 70 61  of the fourth pa
25c50 72 61 6d 65 74 65 72 20 74 68 65 6e 20 74 68 65  rameter then the
25c60 20 72 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e   resulting strin
25c70 67 20 76 61 6c 75 65 20 77 69 6c 6c 0a 2a 2a 20  g value will.** 
25c80 63 6f 6e 74 61 69 6e 20 65 6d 62 65 64 64 65 64  contain embedded
25c90 20 4e 55 4c 73 2e 20 20 54 68 65 20 72 65 73 75   NULs.  The resu
25ca0 6c 74 20 6f 66 20 65 78 70 72 65 73 73 69 6f 6e  lt of expression
25cb0 73 20 69 6e 76 6f 6c 76 69 6e 67 20 73 74 72 69  s involving stri
25cc0 6e 67 73 0a 2a 2a 20 77 69 74 68 20 65 6d 62 65  ngs.** with embe
25cd0 64 64 65 64 20 4e 55 4c 73 20 69 73 20 75 6e 64  dded NULs is und
25ce0 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
25cf0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
25d00 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69 6e  t to sqlite3_bin
25d10 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65  d_blob(), sqlite
25d20 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c 20 61  3_bind_text(), a
25d30 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69  nd.** sqlite3_bi
25d40 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73 20 61  nd_text16() is a
25d50 20 64 65 73 74 72 75 63 74 6f 72 20 75 73 65 64   destructor used
25d60 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
25d70 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20 73 74  he BLOB or.** st
25d80 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c 69 74  ring after SQLit
25d90 65 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  e has finished w
25da0 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20 64 65  ith it.  ^The de
25db0 73 74 72 75 63 74 6f 72 20 69 73 20 63 61 6c 6c  structor is call
25dc0 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f 73 65  ed.** to dispose
25dd0 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f 72 20   of the BLOB or 
25de0 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66 20 74  string even if t
25df0 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74  he call to sqlit
25e00 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29 2c 0a  e3_bind_blob(),.
25e10 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  ** sqlite3_bind_
25e20 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c 69 74  text(), or sqlit
25e30 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 29  e3_bind_text16()
25e40 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e 49 66   fails.  .** ^If
25e50 20 74 68 65 20 66 69 66 74 68 20 61 72 67 75 6d   the fifth argum
25e60 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20 73 70  ent is.** the sp
25e70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53 51 4c  ecial value [SQL
25e80 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74 68 65  ITE_STATIC], the
25e90 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d 65 73  n SQLite assumes
25ea0 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69 6e 66   that the.** inf
25eb0 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e 20 73  ormation is in s
25ec0 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67 65 64  tatic, unmanaged
25ed0 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65 73 20   space and does 
25ee0 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65 20 66  not need to be f
25ef0 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  reed..** ^If the
25f00 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20   fifth argument 
25f10 68 61 73 20 74 68 65 20 76 61 6c 75 65 20 5b 53  has the value [S
25f20 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 5d  QLITE_TRANSIENT]
25f30 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65  , then.** SQLite
25f40 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e 20 70   makes its own p
25f50 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74  rivate copy of t
25f60 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69 61 74  he data immediat
25f70 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a 20 74  ely, before.** t
25f80 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25f90 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  *() routine retu
25fa0 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  rns..**.** ^The 
25fb0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a 65 72  sqlite3_bind_zer
25fc0 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e 65 20  oblob() routine 
25fd0 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f 66 20  binds a BLOB of 
25fe0 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a 2a 2a  length N that.**
25ff0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
26000 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65 72 6f  zeroes.  ^A zero
26010 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69 78 65  blob uses a fixe
26020 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65 6d 6f  d amount of memo
26030 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e 20 69  ry.** (just an i
26040 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64 20 69  nteger to hold i
26050 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65 20 69  ts size) while i
26060 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f 63 65  t is being proce
26070 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62 6c 6f  ssed..** Zeroblo
26080 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65 64 20  bs are intended 
26090 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c 61 63  to serve as plac
260a0 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42 4c 4f  eholders for BLO
260b0 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f 6e 74  Bs whose.** cont
260c0 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77 72 69  ent is later wri
260d0 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tten using.** [s
260e0 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70 65 6e  qlite3_blob_open
260f0 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c 20 42   | incremental B
26100 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69 6e 65  LOB I/O] routine
26110 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74 69 76  s..** ^A negativ
26120 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68 65 20  e value for the 
26130 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c 74 73  zeroblob results
26140 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74   in a zero-lengt
26150 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49  h BLOB..**.** ^I
26160 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73 71 6c  f any of the sql
26170 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f  ite3_bind_*() ro
26180 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
26190 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20 70 6f  d with a NULL po
261a0 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74 68 65  inter.** for the
261b0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
261c0 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20 61 20  ment] or with a 
261d0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
261e0 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a 2a 20  nt for which.** 
261f0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
26200 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c 65 64   has been called
26210 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79 20 74   more recently t
26220 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  han [sqlite3_res
26230 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e 20 74  et()],.** then t
26240 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72 65 74  he call will ret
26250 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  urn [SQLITE_MISU
26260 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73 71 6c  SE].  If any sql
26270 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a 2a 20  ite3_bind_().** 
26280 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73 73 65  routine is passe
26290 64 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74  d a [prepared st
262a0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 68 61  atement] that ha
262b0 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64  s been finalized
262c0 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20  , the.** result 
262d0 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61 6e 64  is undefined and
262e0 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d 66 75   probably harmfu
262f0 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64 69 6e  l..**.** ^Bindin
26300 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65 61 72  gs are not clear
26310 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74  ed by the [sqlit
26320 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f 75 74  e3_reset()] rout
26330 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75 6e 64  ine..** ^Unbound
26340 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20   parameters are 
26350 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 4e  interpreted as N
26360 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ULL..**.** ^The 
26370 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 20 72  sqlite3_bind_* r
26380 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 5b  outines return [
26390 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75  SQLITE_OK] on su
263a0 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a 20 5b  ccess or an.** [
263b0 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66 20 61  error code] if a
263c0 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77 72 6f  nything goes wro
263d0 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f  ng..** ^[SQLITE_
263e0 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75 72 6e  RANGE] is return
263f0 65 64 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  ed if the parame
26400 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69 73 20  ter.** index is 
26410 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20 20 5e  out of range.  ^
26420 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 69  [SQLITE_NOMEM] i
26430 73 20 72 65 74 75 72 6e 65 64 20 69 66 20 6d 61  s returned if ma
26440 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  lloc() fails..**
26450 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26460 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
26470 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 0a  meter_count()],.
26480 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
26490 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28  _parameter_name(
264a0 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  )], and [sqlite3
264b0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
264c0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
264d0 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c   sqlite3_bind_bl
264e0 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ob(sqlite3_stmt*
264f0 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76 6f 69  , int, const voi
26500 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69 64 28  d*, int n, void(
26510 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e 74 20  *)(void*));.int 
26520 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64 6f 75  sqlite3_bind_dou
26530 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ble(sqlite3_stmt
26540 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65 29 3b  *, int, double);
26550 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
26560 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  d_int(sqlite3_st
26570 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29 3b 0a  mt*, int, int);.
26580 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
26590 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73  _int64(sqlite3_s
265a0 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74  tmt*, int, sqlit
265b0 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74 20 73  e3_int64);.int s
265c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75 6c 6c  qlite3_bind_null
265d0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
265e0 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  int);.int sqlite
265f0 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71 6c 69  3_bind_text(sqli
26600 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20  te3_stmt*, int, 
26610 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e 74  const char*, int
26620 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   n, void(*)(void
26630 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  *));.int sqlite3
26640 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73 71 6c  _bind_text16(sql
26650 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
26660 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
26670 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
26680 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  ));.int sqlite3_
26690 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c 69 74  bind_value(sqlit
266a0 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63  e3_stmt*, int, c
266b0 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76 61 6c  onst sqlite3_val
266c0 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
266d0 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62 28  3_bind_zeroblob(
266e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
266f0 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a  nt, int n);../*.
26700 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 75 6d  ** CAPI3REF: Num
26710 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72 61 6d  ber Of SQL Param
26720 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  eters.**.** ^Thi
26730 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65  s routine can be
26740 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20 74 68   used to find th
26750 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53 51 4c  e number of [SQL
26760 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a 2a 20   parameters].** 
26770 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  in a [prepared s
26780 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51 4c 20  tatement].  SQL 
26790 70 61 72 61 6d 65 74 65 72 73 20 61 72 65 20 74  parameters are t
267a0 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a 2a 20  okens of the.** 
267b0 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e 4e 22  form "?", "?NNN"
267c0 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41 41 22  , ":AAA", "$AAA"
267d0 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68 61 74  , or "@AAA" that
267e0 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70 6c 61   serve as.** pla
267f0 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 76 61  ceholders for va
26800 6c 75 65 73 20 74 68 61 74 20 61 72 65 20 5b 73  lues that are [s
26810 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26820 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74 6f 20   | bound].** to 
26830 74 68 65 20 70 61 72 61 6d 65 74 65 72 73 20 61  the parameters a
26840 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65 2e 0a  t a later time..
26850 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72 6f 75  **.** ^(This rou
26860 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20 72 65  tine actually re
26870 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65 78 20  turns the index 
26880 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74 20 28  of the largest (
26890 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20 70 61  rightmost).** pa
268a0 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61 6c 6c  rameter. For all
268b0 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20 3f 4e   forms except ?N
268c0 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20 63 6f  NN, this will co
268d0 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68 65 0a  rrespond to the.
268e0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75 6e 69  ** number of uni
268f0 71 75 65 20 70 61 72 61 6d 65 74 65 72 73 2e 20  que parameters. 
26900 20 49 66 20 70 61 72 61 6d 65 74 65 72 73 20 6f   If parameters o
26910 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72 6d 20  f the ?NNN form 
26920 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74 68 65  are used,.** the
26930 72 65 20 6d 61 79 20 62 65 20 67 61 70 73 20 69  re may be gaps i
26940 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a 2a 2a  n the list.)^.**
26950 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73  .** See also: [s
26960 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
26970 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
26980 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
26990 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
269a0 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71  e()], and.** [sq
269b0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
269c0 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a  eter_index()]..*
269d0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  /.int sqlite3_bi
269e0 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75  nd_parameter_cou
269f0 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  nt(sqlite3_stmt*
26a00 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
26a10 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20 48 6f  EF: Name Of A Ho
26a20 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a 2a 0a  st Parameter.**.
26a30 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
26a40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
26a50 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72 66 61  ame(P,N) interfa
26a60 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68  ce returns.** th
26a70 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 4e 2d  e name of the N-
26a80 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  th [SQL paramete
26a90 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65 70 61  r] in the [prepa
26aa0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 50  red statement] P
26ab0 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72 61 6d  ..** ^(SQL param
26ac0 65 74 65 72 73 20 6f 66 20 74 68 65 20 66 6f 72  eters of the for
26ad0 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a 41 41  m "?NNN" or ":AA
26ae0 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f 72 20  A" or "@AAA" or 
26af0 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65 20 61  "$AAA".** have a
26b00 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73 20 74   name which is t
26b10 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e 4e 22  he string "?NNN"
26b20 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20 22 40   or ":AAA" or "@
26b30 41 41 41 22 20 6f 72 20 22 24 41 41 41 22 0a 2a  AAA" or "$AAA".*
26b40 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 0a  * respectively..
26b50 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64  ** In other word
26b60 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c 20 22  s, the initial "
26b70 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22 40 22  :" or "$" or "@"
26b80 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20 69 6e   or "?".** is in
26b90 63 6c 75 64 65 64 20 61 73 20 70 61 72 74 20 6f  cluded as part o
26ba0 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a 2a 2a  f the name.)^.**
26bb0 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f 66 20   ^Parameters of 
26bc0 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77 69 74  the form "?" wit
26bd0 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69 6e 67  hout a following
26be0 20 69 6e 74 65 67 65 72 20 68 61 76 65 20 6e 6f   integer have no
26bf0 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61 72 65   name.** and are
26c00 20 72 65 66 65 72 72 65 64 20 74 6f 20 61 73 20   referred to as 
26c10 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20 22 61  "nameless" or "a
26c20 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d 65 74  nonymous paramet
26c30 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ers"..**.** ^The
26c40 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72 61   first host para
26c50 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e 64  meter has an ind
26c60 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e 0a  ex of 1, not 0..
26c70 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76 61  **.** ^If the va
26c80 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66 20  lue N is out of 
26c90 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65 20  range or if the 
26ca0 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20 69  N-th parameter i
26cb0 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20 74  s.** nameless, t
26cc0 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74 75  hen NULL is retu
26cd0 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74 75  rned.  ^The retu
26ce0 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a 2a  rned string is.*
26cf0 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46 2d  * always in UTF-
26d00 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e 20  8 encoding even 
26d10 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61 72  if the named par
26d20 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f 72  ameter was.** or
26d30 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66 69  iginally specifi
26d40 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e 20  ed as UTF-16 in 
26d50 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26d60 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  16()] or.** [sql
26d70 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76  ite3_prepare16_v
26d80 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  2()]..**.** See 
26d90 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 62  also: [sqlite3_b
26da0 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65 33  ind_blob|sqlite3
26db0 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73 71  _bind()],.** [sq
26dc0 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
26dd0 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20 61  eter_count()], a
26de0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  nd.** [sqlite3_b
26df0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
26e00 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73 74  dex()]..*/.const
26e10 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 62   char *sqlite3_b
26e20 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61  ind_parameter_na
26e30 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26e40 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  , int);../*.** C
26e50 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20 4f  API3REF: Index O
26e60 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57 69  f A Parameter Wi
26e70 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65 0a  th A Given Name.
26e80 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74 68  **.** ^Return th
26e90 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53 51  e index of an SQ
26ea0 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76 65  L parameter give
26eb0 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54 68  n its name.  ^Th
26ec0 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75 65  e.** index value
26ed0 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75 69   returned is sui
26ee0 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61 73  table for use as
26ef0 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20 70   the second.** p
26f00 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c  arameter to [sql
26f10 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
26f20 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e 20  qlite3_bind()]. 
26f30 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20 72   ^A zero.** is r
26f40 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d 61  eturned if no ma
26f50 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65 72  tching parameter
26f60 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68 65   is found.  ^The
26f70 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e 61   parameter.** na
26f80 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65 6e  me must be given
26f90 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20 69   in UTF-8 even i
26fa0 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 73  f the original s
26fb0 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73 20  tatement.** was 
26fc0 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55 54  prepared from UT
26fd0 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67 20  F-16 text using 
26fe0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26ff0 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  16_v2()]..**.** 
27000 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74  See also: [sqlit
27010 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c  e3_bind_blob|sql
27020 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a  ite3_bind()],.**
27030 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70   [sqlite3_bind_p
27040 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29  arameter_count()
27050 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  ], and.** [sqlit
27060 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
27070 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
27080 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
27090 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78 28  parameter_index(
270a0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 63  sqlite3_stmt*, c
270b0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
270c0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
270d0 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42 69  EF: Reset All Bi
270e0 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65 70  ndings On A Prep
270f0 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
27100 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20 74  *.** ^Contrary t
27110 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e 20  o the intuition 
27120 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74 65  of many, [sqlite
27130 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73 20  3_reset()] does 
27140 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68 65  not reset.** the
27150 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
27160 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20  lob | bindings] 
27170 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20 73  on a [prepared s
27180 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e 55  tatement]..** ^U
27190 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  se this routine 
271a0 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f 73  to reset all hos
271b0 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
271c0 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  NULL..*/.int sql
271d0 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64 69  ite3_clear_bindi
271e0 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ngs(sqlite3_stmt
271f0 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
27200 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20 43  REF: Number Of C
27210 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73 75  olumns In A Resu
27220 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52 65  lt Set.**.** ^Re
27230 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72 20  turn the number 
27240 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68  of columns in th
27250 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65 74  e result set ret
27260 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a 20  urned by the.** 
27270 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
27280 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75 74  ent]. ^This rout
27290 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69 66  ine returns 0 if
272a0 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51 4c   pStmt is an SQL
272b0 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74 68  .** statement th
272c0 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74 75  at does not retu
272d0 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78 61  rn data (for exa
272e0 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45 5d  mple an [UPDATE]
272f0 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  )..**.** See als
27300 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74 61  o: [sqlite3_data
27310 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e 74  _count()].*/.int
27320 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
27330 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74  count(sqlite3_st
27340 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
27350 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c  ** CAPI3REF: Col
27360 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20 52  umn Names In A R
27370 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20  esult Set.**.** 
27380 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
27390 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20  return the name 
273a0 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70 61  assigned to a pa
273b0 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e 0a  rticular column.
273c0 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ** in the result
273d0 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45 43   set of a [SELEC
273e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e  T] statement.  ^
273f0 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  The sqlite3_colu
27400 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e 74  mn_name().** int
27410 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
27420 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a 65   pointer to a ze
27430 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54  ro-terminated UT
27440 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61 6e  F-8 string.** an
27450 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  d sqlite3_column
27460 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72 6e  _name16() return
27470 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  s a pointer to a
27480 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
27490 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69 6e  .** UTF-16 strin
274a0 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20 70  g.  ^The first p
274b0 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 20  arameter is the 
274c0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
274d0 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d 70  ent].** that imp
274e0 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45 4c  lements the [SEL
274f0 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
27500 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61  ^The second para
27510 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a 20  meter is the.** 
27520 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20 20  column number.  
27530 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63 6f  ^The leftmost co
27540 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20 30  lumn is number 0
27550 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74  ..**.** ^The ret
27560 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f 69  urned string poi
27570 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75 6e  nter is valid un
27580 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20 5b  til either the [
27590 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
275a0 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72 6f  nt].** is destro
275b0 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  yed by [sqlite3_
275c0 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20 75  finalize()] or u
275d0 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d 65  ntil the stateme
275e0 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63 61  nt is automatica
275f0 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72 65  lly.** reprepare
27600 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20 63  d by the first c
27610 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
27620 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70 61  step()] for a pa
27630 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a 20  rticular run.** 
27640 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65 78  or until the nex
27650 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c  t call to.** sql
27660 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
27670 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f  () or sqlite3_co
27680 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f 6e  lumn_name16() on
27690 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d 6e   the same column
276a0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c 69  ..**.** ^If sqli
276b0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61 69  te3_malloc() fai
276c0 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70 72  ls during the pr
276d0 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74 68  ocessing of eith
276e0 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28 66  er routine.** (f
276f0 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69 6e  or example durin
27700 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20 66  g a conversion f
27710 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54 46  rom UTF-8 to UTF
27720 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20 4e  -16) then a.** N
27730 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
27740 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
27750 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72 65  The name of a re
27760 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20 74  sult column is t
27770 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
27780 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72 0a  "AS" clause for.
27790 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c 20  ** that column, 
277a0 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20 41  if there is an A
277b0 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74 68  S clause.  If th
277c0 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c 61  ere is no AS cla
277d0 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  use.** then the 
277e0 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 75  name of the colu
277f0 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69 65  mn is unspecifie
27800 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67 65  d and may change
27810 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65 6c   from.** one rel
27820 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20 74  ease of SQLite t
27830 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a 63  o the next..*/.c
27840 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74  onst char *sqlit
27850 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28 73  e3_column_name(s
27860 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
27870 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  t N);.const void
27880 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
27890 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
278a0 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 0a  stmt*, int N);..
278b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
278c0 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20 49  Source Of Data I
278d0 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c 74  n A Query Result
278e0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
278f0 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20 61  utines provide a
27900 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72 6d   means to determ
27910 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ine the database
27920 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a 20  , table, and.** 
27930 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61  table column tha
27940 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e 20  t is the origin 
27950 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  of a particular 
27960 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 6e  result column in
27970 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  .** [SELECT] sta
27980 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  tement..** ^The 
27990 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74 61  name of the data
279a0 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f 72  base or table or
279b0 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20 72   column can be r
279c0 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65 69  eturned as.** ei
279d0 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72 20  ther a UTF-8 or 
279e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20 20  UTF-16 string.  
279f0 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f 20  ^The _database_ 
27a00 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 0a  routines return.
27a10 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
27a20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c 65  name, the _table
27a30 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
27a40 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d 65  n the table name
27a50 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72 69  , and.** the ori
27a60 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72 65  gin_ routines re
27a70 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e 20  turn the column 
27a80 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72 65  name..** ^The re
27a90 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
27aa0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68 65   valid until the
27ab0 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
27ac0 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f 79  ment] is destroy
27ad0 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ed.** using [sql
27ae0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
27af0 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73 74   or until the st
27b00 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d  atement is autom
27b10 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72  atically.** repr
27b20 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66 69  epared by the fi
27b30 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  rst call to [sql
27b40 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f 72  ite3_step()] for
27b50 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72 75   a particular ru
27b60 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68  n.** or until th
27b70 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74 69  e same informati
27b80 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64 0a  on is requested.
27b90 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64 69  ** again in a di
27ba0 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e 67  fferent encoding
27bb0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d  ..**.** ^The nam
27bc0 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20  es returned are 
27bd0 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e 2d  the original un-
27be0 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f 66  aliased names of
27bf0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
27c00 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f 6c  , table, and col
27c10 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  umn..**.** ^The 
27c20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
27c30 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61 63  o these interfac
27c40 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72 65  es is a [prepare
27c50 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a  d statement]..**
27c60 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
27c70 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d 61  s return informa
27c80 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20 4e  tion about the N
27c90 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  th result column
27ca0 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
27cb0 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20 77  the statement, w
27cc0 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73 65  here N is the se
27cd0 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61 72  cond function ar
27ce0 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20  gument..** ^The 
27cf0 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d 6e  left-most column
27d00 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f 72   is column 0 for
27d10 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e   these routines.
27d20 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 4e  .**.** ^If the N
27d30 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72 6e  th column return
27d40 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65 6d  ed by the statem
27d50 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65 73  ent is an expres
27d60 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71 75  sion or.** subqu
27d70 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20 61  ery and is not a
27d80 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20 74   column value, t
27d90 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73 65  hen all of these
27da0 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75 72   functions retur
27db0 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68 65  n.** NULL.  ^The
27dc0 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68 74  se routine might
27dd0 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55 4c   also return NUL
27de0 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c  L if a memory al
27df0 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a 2a  location error.*
27e00 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68 65  * occurs.  ^Othe
27e10 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74 75  rwise, they retu
27e20 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  rn the name of t
27e30 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74 61  he attached data
27e40 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a 20  base, table,.** 
27e50 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20 71  or column that q
27e60 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c 75  uery result colu
27e70 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65 64  mn was extracted
27e80 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41 73   from..**.** ^As
27e90 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72 20   with all other 
27ea0 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68 6f  SQLite APIs, tho
27eb0 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20 65  se whose names e
27ec0 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65 74  nd with "16" ret
27ed0 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65 6e  urn.** UTF-16 en
27ee0 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61 6e  coded strings an
27ef0 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e 63  d the other func
27f00 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54 46  tions return UTF
27f10 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  -8..**.** ^These
27f20 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20 61   APIs are only a
27f30 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65 20  vailable if the 
27f40 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d 70  library was comp
27f50 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a  iled with the.**
27f60 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
27f70 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41 5d  COLUMN_METADATA]
27f80 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72 20   C-preprocessor 
27f90 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49 66  symbol..**.** If
27fa0 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68 72   two or more thr
27fb0 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f 72  eads call one or
27fc0 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20 72   more of these r
27fd0 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74 20  outines against 
27fe0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65 70  the same.** prep
27ff0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
28000 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68 65  nd column at the
28010 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e 20   same time then 
28020 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 0a  the results are.
28030 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  ** undefined..**
28040 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d 6f  .** If two or mo
28050 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c 20  re threads call 
28060 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 5b  one or more.** [
28070 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
28080 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20 63  atabase_name | c
28090 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20 69  olumn metadata i
280a0 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66 6f  nterfaces].** fo
280b0 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65 70  r the same [prep
280c0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
280d0 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  and result colum
280e0 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d 65  n.** at the same
280f0 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20 72   time then the r
28100 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
28110 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63  ined..*/.const c
28120 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c  har *sqlite3_col
28130 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d  umn_database_nam
28140 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28150 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28160 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28170 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31 36  _database_name16
28180 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28190 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72 20  nt);.const char 
281a0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
281b0 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69 74  table_name(sqlit
281c0 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63  e3_stmt*,int);.c
281d0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
281e0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65 5f  e3_column_table_
281f0 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f 73  name16(sqlite3_s
28200 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28210 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
28220 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d  olumn_origin_nam
28230 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  e(sqlite3_stmt*,
28240 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  int);.const void
28250 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
28260 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28 73  _origin_name16(s
28270 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74  qlite3_stmt*,int
28280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
28290 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61 74  EF: Declared Dat
282a0 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72 79  atype Of A Query
282b0 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e 28   Result.**.** ^(
282c0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
282d0 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61 72  ter is a [prepar
282e0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
282f0 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65 6d  * If this statem
28300 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43 54  ent is a [SELECT
28310 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64 20  ] statement and 
28320 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 6f  the Nth column o
28330 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e 65  f the.** returne
28340 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  d result set of 
28350 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69 73  that [SELECT] is
28360 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20   a table column 
28370 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72 65  (not an.** expre
28380 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65 72  ssion or subquer
28390 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63 6c  y) then the decl
283a0 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68 65  ared type of the
283b0 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d 6e   table.** column
283c0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 20   is returned.)^ 
283d0 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f 6c   ^If the Nth col
283e0 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75 6c  umn of the resul
283f0 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20 65  t set is an.** e
28400 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62  xpression or sub
28410 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e 55  query, then a NU
28420 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72 65  LL pointer is re
28430 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  turned..** ^The 
28440 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
28450 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38 20  is always UTF-8 
28460 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  encoded..**.** ^
28470 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67 69  (For example, gi
28480 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  ven the database
28490 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20 43   schema:.**.** C
284a0 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28 63  REATE TABLE t1(c
284b0 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a 2a  1 VARIANT);.**.*
284c0 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f 77  * and the follow
284d0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74 6f  ing statement to
284e0 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a 2a   be compiled:.**
284f0 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b 20  .** SELECT c1 + 
28500 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a 2a  1, c1 FROM t1;.*
28510 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69 6e  *.** this routin
28520 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20 74  e would return t
28530 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49 41  he string "VARIA
28540 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63 6f  NT" for the seco
28550 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f 6c  nd result.** col
28560 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64 20  umn (i==1), and 
28570 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 66  a NULL pointer f
28580 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65 73  or the first res
28590 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d 30  ult column (i==0
285a0 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69  ).)^.**.** ^SQLi
285b0 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63 20  te uses dynamic 
285c0 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67 2e  run-time typing.
285d0 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61 75    ^So just becau
285e0 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69  se a column.** i
285f0 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63 6f  s declared to co
28600 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75 6c  ntain a particul
28610 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f 74  ar type does not
28620 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a 2a   mean that the.*
28630 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69 6e  * data stored in
28640 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73 20   that column is 
28650 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64 20  of the declared 
28660 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69 73  type.  SQLite is
28670 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79 70  .** strongly typ
28680 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70 69  ed, but the typi
28690 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e 6f  ng is dynamic no
286a0 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70 65  t static.  ^Type
286b0 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74 65  .** is associate
286c0 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75 61  d with individua
286d0 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77 69  l values, not wi
286e0 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65 72  th the container
286f0 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f 6c  s.** used to hol
28700 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e 0a  d those values..
28710 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73  */.const char *s
28720 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64 65  qlite3_column_de
28730 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73  cltype(sqlite3_s
28740 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74  tmt*,int);.const
28750 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
28760 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31 36  olumn_decltype16
28770 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
28780 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
28790 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20 41  3REF: Evaluate A
287a0 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 0a  n SQL Statement.
287b0 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b 70  **.** After a [p
287c0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
287d0 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65 70  t] has been prep
287e0 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68 65  ared using eithe
287f0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  r.** [sqlite3_pr
28800 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 5b  epare_v2()] or [
28810 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31  sqlite3_prepare1
28820 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f  6_v2()] or one o
28830 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a 20  f the legacy.** 
28840 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c 69  interfaces [sqli
28850 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20 6f  te3_prepare()] o
28860 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  r [sqlite3_prepa
28870 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66 75  re16()], this fu
28880 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20 62  nction.** must b
28890 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72 20  e called one or 
288a0 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65 76  more times to ev
288b0 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74 65  aluate the state
288c0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  ment..**.** The 
288d0 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20 62  details of the b
288e0 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20 73  ehavior of the s
288f0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e  qlite3_step() in
28900 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a 2a  terface depend.*
28910 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68 65  * on whether the
28920 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20 70   statement was p
28930 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74 68  repared using th
28940 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e 74  e newer "v2" int
28950 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69 74  erface.** [sqlit
28960 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
28970 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
28980 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f 72  epare16_v2()] or
28990 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61 63   the older legac
289a0 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 5b  y.** interface [
289b0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28  sqlite3_prepare(
289c0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
289d0 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20 54  prepare16()].  T
289e0 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a 2a  he use of the.**
289f0 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72 66   new "v2" interf
28a00 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64  ace is recommend
28a10 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c 69  ed for new appli
28a20 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65 20  cations but the 
28a30 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66  legacy.** interf
28a40 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e 75  ace will continu
28a50 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65  e to be supporte
28a60 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68 65  d..**.** ^In the
28a70 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61 63   legacy interfac
28a80 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  e, the return va
28a90 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74 68  lue will be eith
28aa0 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  er [SQLITE_BUSY]
28ab0 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f 4e  ,.** [SQLITE_DON
28ac0 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  E], [SQLITE_ROW]
28ad0 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d  , [SQLITE_ERROR]
28ae0 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49 53  , or [SQLITE_MIS
28af0 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20 74  USE]..** ^With t
28b00 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
28b10 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f 74  e, any of the ot
28b20 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64 65  her [result code
28b30 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64  s] or.** [extend
28b40 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d  ed result codes]
28b50 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72 6e   might be return
28b60 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a 2a  ed as well..**.*
28b70 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  * ^[SQLITE_BUSY]
28b80 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
28b90 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65 20  database engine 
28ba0 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 63  was unable to ac
28bb0 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61 74  quire the.** dat
28bc0 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20 6e  abase locks it n
28bd0 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20 6a  eeds to do its j
28be0 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74 61  ob.  ^If the sta
28bf0 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f 4d  tement is a [COM
28c00 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75 72  MIT].** or occur
28c10 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 20  s outside of an 
28c20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61 63  explicit transac
28c30 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20 63  tion, then you c
28c40 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a 20  an retry the.** 
28c50 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20 74  statement.  If t
28c60 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
28c70 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 61  not a [COMMIT] a
28c80 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e  nd occurs within
28c90 20 61 6e 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20   an.** explicit 
28ca0 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
28cb0 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
28cc0 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
28cd0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
28ce0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
28cf0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
28d00 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
28d10 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
28d20 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
28d30 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
28d40 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
28d50 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
28d60 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
28d70 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
28d80 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
28d90 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
28da0 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
28db0 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
28dc0 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
28dd0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
28de0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
28df0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
28e00 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
28e10 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
28e20 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
28e30 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
28e40 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
28e50 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
28e60 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
28e70 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
28e80 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
28e90 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
28ea0 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
28eb0 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
28ec0 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
28ed0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
28ee0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
28ef0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
28f00 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
28f10 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
28f20 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
28f30 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
28f40 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
28f50 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
28f60 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
28f70 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
28f80 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
28f90 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
28fa0 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
28fb0 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
28fc0 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
28fd0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
28fe0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
28ff0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
29000 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
29010 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
29020 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
29030 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
29040 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
29050 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
29060 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
29070 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
29080 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
29090 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
290a0 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
290b0 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
290c0 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
290d0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
290e0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
290f0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
29100 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
29110 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
29120 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
29130 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
29140 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
29150 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
29160 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
29170 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
29180 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
29190 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
291a0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
291b0 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
291c0 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
291d0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
291e0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
291f0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
29200 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
29210 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
29220 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
29230 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
29240 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
29250 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
29260 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
29270 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
29280 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
29290 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
292a0 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
292b0 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
292c0 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
292d0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
292e0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
292f0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
29300 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
29310 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
29320 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
29330 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
29340 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
29350 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
29360 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
29370 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
29380 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
29390 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
293a0 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
293b0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
293c0 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
293d0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
293e0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
293f0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
29400 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
29410 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
29420 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
29430 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
29440 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
29450 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
29460 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
29470 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
29480 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
29490 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
294a0 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
294b0 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
294c0 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
294d0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
294e0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
294f0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
29500 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
29510 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
29520 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
29530 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
29540 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
29550 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
29560 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
29570 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
29580 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
29590 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
295a0 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
295b0 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
295c0 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
295d0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
295e0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
295f0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
29600 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
29610 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
29620 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
29630 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
29640 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
29650 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
29660 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
29670 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
29680 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
29690 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
296a0 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
296b0 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
296c0 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
296d0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
296e0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
296f0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
29700 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
29710 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
29720 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
29730 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
29740 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
29750 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
29760 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
29770 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
29780 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
29790 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
297a0 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
297b0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
297c0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
297d0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
297e0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
297f0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
29800 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
29810 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
29820 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
29830 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
29840 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
29850 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
29860 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
29870 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
29880 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
29890 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
298a0 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
298b0 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
298c0 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
298d0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
298e0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
298f0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
29900 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
29910 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
29920 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
29930 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
29940 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
29950 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
29960 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
29970 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
29980 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29990 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
299a0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
299b0 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
299c0 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
299d0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
299e0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
299f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
29a00 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
29a10 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
29a20 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
29a30 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
29a40 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
29a50 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29a60 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
29a70 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
29a80 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
29a90 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 20 5e 54  L pointer..** ^T
29aa0 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  he sqlite3_data_
29ab0 63 6f 75 6e 74 28 50 29 20 72 6f 75 74 69 6e 65  count(P) routine
29ac0 20 72 65 74 75 72 6e 73 20 30 20 69 66 20 74 68   returns 0 if th
29ad0 65 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20  e previous call 
29ae0 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  to.** [sqlite3_s
29af0 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e 65 64  tep](P) returned
29b00 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e 20   [SQLITE_DONE]. 
29b10 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
29b20 74 61 5f 63 6f 75 6e 74 28 50 29 0a 2a 2a 20 77  ta_count(P).** w
29b30 69 6c 6c 20 72 65 74 75 72 6e 20 6e 6f 6e 2d 7a  ill return non-z
29b40 65 72 6f 20 69 66 20 70 72 65 76 69 6f 75 73 20  ero if previous 
29b50 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29b60 5f 73 74 65 70 5d 28 50 29 20 72 65 74 75 72 6e  _step](P) return
29b70 65 64 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 52 4f  ed.** [SQLITE_RO
29b80 57 5d 2c 20 65 78 63 65 70 74 20 69 6e 20 74 68  W], except in th
29b90 65 20 63 61 73 65 20 6f 66 20 74 68 65 20 5b 50  e case of the [P
29ba0 52 41 47 4d 41 20 69 6e 63 72 65 6d 65 6e 74 61  RAGMA incrementa
29bb0 6c 5f 76 61 63 75 75 6d 5d 0a 2a 2a 20 77 68 65  l_vacuum].** whe
29bc0 72 65 20 69 74 20 61 6c 77 61 79 73 20 72 65 74  re it always ret
29bd0 75 72 6e 73 20 7a 65 72 6f 20 73 69 6e 63 65 20  urns zero since 
29be0 65 61 63 68 20 73 74 65 70 20 6f 66 20 74 68 61  each step of tha
29bf0 74 20 6d 75 6c 74 69 2d 73 74 65 70 0a 2a 2a 20  t multi-step.** 
29c00 70 72 61 67 6d 61 20 72 65 74 75 72 6e 73 20 30  pragma returns 0
29c10 20 63 6f 6c 75 6d 6e 73 20 6f 66 20 64 61 74 61   columns of data
29c20 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
29c30 3a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  : [sqlite3_colum
29c40 6e 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  n_count()].*/.in
29c50 74 20 73 71 6c 69 74 65 33 5f 64 61 74 61 5f 63  t sqlite3_data_c
29c60 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
29c70 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a  t *pStmt);../*.*
29c80 2a 20 43 41 50 49 33 52 45 46 3a 20 46 75 6e 64  * CAPI3REF: Fund
29c90 61 6d 65 6e 74 61 6c 20 44 61 74 61 74 79 70 65  amental Datatype
29ca0 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 53  s.** KEYWORDS: S
29cb0 51 4c 49 54 45 5f 54 45 58 54 0a 2a 2a 0a 2a 2a  QLITE_TEXT.**.**
29cc0 20 5e 28 45 76 65 72 79 20 76 61 6c 75 65 20 69   ^(Every value i
29cd0 6e 20 53 51 4c 69 74 65 20 68 61 73 20 6f 6e 65  n SQLite has one
29ce0 20 6f 66 20 66 69 76 65 20 66 75 6e 64 61 6d 65   of five fundame
29cf0 6e 74 61 6c 20 64 61 74 61 74 79 70 65 73 3a 0a  ntal datatypes:.
29d00 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
29d10 69 3e 20 36 34 2d 62 69 74 20 73 69 67 6e 65 64  i> 64-bit signed
29d20 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 6c 69 3e   integer.** <li>
29d30 20 36 34 2d 62 69 74 20 49 45 45 45 20 66 6c 6f   64-bit IEEE flo
29d40 61 74 69 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62  ating point numb
29d50 65 72 0a 2a 2a 20 3c 6c 69 3e 20 73 74 72 69 6e  er.** <li> strin
29d60 67 0a 2a 2a 20 3c 6c 69 3e 20 42 4c 4f 42 0a 2a  g.** <li> BLOB.*
29d70 2a 20 3c 6c 69 3e 20 4e 55 4c 4c 0a 2a 2a 20 3c  * <li> NULL.** <
29d80 2f 75 6c 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  /ul>)^.**.** The
29d90 73 65 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65  se constants are
29da0 20 63 6f 64 65 73 20 66 6f 72 20 65 61 63 68 20   codes for each 
29db0 6f 66 20 74 68 6f 73 65 20 74 79 70 65 73 2e 0a  of those types..
29dc0 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  **.** Note that 
29dd0 74 68 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  the SQLITE_TEXT 
29de0 63 6f 6e 73 74 61 6e 74 20 77 61 73 20 61 6c 73  constant was als
29df0 6f 20 75 73 65 64 20 69 6e 20 53 51 4c 69 74 65  o used in SQLite
29e00 20 76 65 72 73 69 6f 6e 20 32 0a 2a 2a 20 66 6f   version 2.** fo
29e10 72 20 61 20 63 6f 6d 70 6c 65 74 65 6c 79 20 64  r a completely d
29e20 69 66 66 65 72 65 6e 74 20 6d 65 61 6e 69 6e 67  ifferent meaning
29e30 2e 20 20 53 6f 66 74 77 61 72 65 20 74 68 61 74  .  Software that
29e40 20 6c 69 6e 6b 73 20 61 67 61 69 6e 73 74 20 62   links against b
29e50 6f 74 68 0a 2a 2a 20 53 51 4c 69 74 65 20 76 65  oth.** SQLite ve
29e60 72 73 69 6f 6e 20 32 20 61 6e 64 20 53 51 4c 69  rsion 2 and SQLi
29e70 74 65 20 76 65 72 73 69 6f 6e 20 33 20 73 68 6f  te version 3 sho
29e80 75 6c 64 20 75 73 65 20 53 51 4c 49 54 45 33 5f  uld use SQLITE3_
29e90 54 45 58 54 2c 20 6e 6f 74 0a 2a 2a 20 53 51 4c  TEXT, not.** SQL
29ea0 49 54 45 5f 54 45 58 54 2e 0a 2a 2f 0a 23 64 65  ITE_TEXT..*/.#de
29eb0 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45  fine SQLITE_INTE
29ec0 47 45 52 20 20 31 0a 23 64 65 66 69 6e 65 20 53  GER  1.#define S
29ed0 51 4c 49 54 45 5f 46 4c 4f 41 54 20 20 20 20 32  QLITE_FLOAT    2
29ee0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
29ef0 42 4c 4f 42 20 20 20 20 20 34 0a 23 64 65 66 69  BLOB     4.#defi
29f00 6e 65 20 53 51 4c 49 54 45 5f 4e 55 4c 4c 20 20  ne SQLITE_NULL  
29f10 20 20 20 35 0a 23 69 66 64 65 66 20 53 51 4c 49     5.#ifdef SQLI
29f20 54 45 5f 54 45 58 54 0a 23 20 75 6e 64 65 66 20  TE_TEXT.# undef 
29f30 53 51 4c 49 54 45 5f 54 45 58 54 0a 23 65 6c 73  SQLITE_TEXT.#els
29f40 65 0a 23 20 64 65 66 69 6e 65 20 53 51 4c 49 54  e.# define SQLIT
29f50 45 5f 54 45 58 54 20 20 20 20 20 33 0a 23 65 6e  E_TEXT     3.#en
29f60 64 69 66 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  dif.#define SQLI
29f70 54 45 33 5f 54 45 58 54 20 20 20 20 20 33 0a 0a  TE3_TEXT     3..
29f80 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
29f90 52 65 73 75 6c 74 20 56 61 6c 75 65 73 20 46 72  Result Values Fr
29fa0 6f 6d 20 41 20 51 75 65 72 79 0a 2a 2a 20 4b 45  om A Query.** KE
29fb0 59 57 4f 52 44 53 3a 20 7b 63 6f 6c 75 6d 6e 20  YWORDS: {column 
29fc0 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
29fd0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  }.**.** These ro
29fe0 75 74 69 6e 65 73 20 66 6f 72 6d 20 74 68 65 20  utines form the 
29ff0 22 72 65 73 75 6c 74 20 73 65 74 22 20 69 6e 74  "result set" int
2a000 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54  erface..**.** ^T
2a010 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65  hese routines re
2a020 74 75 72 6e 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  turn information
2a030 20 61 62 6f 75 74 20 61 20 73 69 6e 67 6c 65 20   about a single 
2a040 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 63 75  column of the cu
2a050 72 72 65 6e 74 0a 2a 2a 20 72 65 73 75 6c 74 20  rrent.** result 
2a060 72 6f 77 20 6f 66 20 61 20 71 75 65 72 79 2e 20  row of a query. 
2a070 20 5e 49 6e 20 65 76 65 72 79 20 63 61 73 65 20   ^In every case 
2a080 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
2a090 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72 0a  nt is a pointer.
2a0a0 2a 2a 20 74 6f 20 74 68 65 20 5b 70 72 65 70 61  ** to the [prepa
2a0b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
2a0c0 68 61 74 20 69 73 20 62 65 69 6e 67 20 65 76 61  hat is being eva
2a0d0 6c 75 61 74 65 64 20 28 74 68 65 20 5b 73 71 6c  luated (the [sql
2a0e0 69 74 65 33 5f 73 74 6d 74 2a 5d 0a 2a 2a 20 74  ite3_stmt*].** t
2a0f0 68 61 74 20 77 61 73 20 72 65 74 75 72 6e 65 64  hat was returned
2a100 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 70   from [sqlite3_p
2a110 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
2a120 6f 6e 65 20 6f 66 20 69 74 73 20 76 61 72 69 61  one of its varia
2a130 6e 74 73 29 0a 2a 2a 20 61 6e 64 20 74 68 65 20  nts).** and the 
2a140 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
2a150 69 73 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20  is the index of 
2a160 74 68 65 20 63 6f 6c 75 6d 6e 20 66 6f 72 20 77  the column for w
2a170 68 69 63 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  hich information
2a180 0a 2a 2a 20 73 68 6f 75 6c 64 20 62 65 20 72 65  .** should be re
2a190 74 75 72 6e 65 64 2e 20 5e 54 68 65 20 6c 65 66  turned. ^The lef
2a1a0 74 6d 6f 73 74 20 63 6f 6c 75 6d 6e 20 6f 66 20  tmost column of 
2a1b0 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 68  the result set h
2a1c0 61 73 20 74 68 65 20 69 6e 64 65 78 20 30 2e 0a  as the index 0..
2a1d0 2a 2a 20 5e 54 68 65 20 6e 75 6d 62 65 72 20 6f  ** ^The number o
2a1e0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74 68 65  f columns in the
2a1f0 20 72 65 73 75 6c 74 20 63 61 6e 20 62 65 20 64   result can be d
2a200 65 74 65 72 6d 69 6e 65 64 20 75 73 69 6e 67 0a  etermined using.
2a210 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2a220 6d 6e 5f 63 6f 75 6e 74 28 29 5d 2e 0a 2a 2a 0a  mn_count()]..**.
2a230 2a 2a 20 49 66 20 74 68 65 20 53 51 4c 20 73 74  ** If the SQL st
2a240 61 74 65 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74  atement does not
2a250 20 63 75 72 72 65 6e 74 6c 79 20 70 6f 69 6e 74   currently point
2a260 20 74 6f 20 61 20 76 61 6c 69 64 20 72 6f 77 2c   to a valid row,
2a270 20 6f 72 20 69 66 20 74 68 65 0a 2a 2a 20 63 6f   or if the.** co
2a280 6c 75 6d 6e 20 69 6e 64 65 78 20 69 73 20 6f 75  lumn index is ou
2a290 74 20 6f 66 20 72 61 6e 67 65 2c 20 74 68 65 20  t of range, the 
2a2a0 72 65 73 75 6c 74 20 69 73 20 75 6e 64 65 66 69  result is undefi
2a2b0 6e 65 64 2e 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ned..** These ro
2a2c0 75 74 69 6e 65 73 20 6d 61 79 20 6f 6e 6c 79 20  utines may only 
2a2d0 62 65 20 63 61 6c 6c 65 64 20 77 68 65 6e 20 74  be called when t
2a2e0 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2a2f0 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74  all to.** [sqlit
2a300 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
2a310 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2a320 52 4f 57 5d 20 61 6e 64 20 6e 65 69 74 68 65 72  ROW] and neither
2a330 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  .** [sqlite3_res
2a340 65 74 28 29 5d 20 6e 6f 72 20 5b 73 71 6c 69 74  et()] nor [sqlit
2a350 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 68  e3_finalize()] h
2a360 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
2a370 73 75 62 73 65 71 75 65 6e 74 6c 79 2e 0a 2a 2a  subsequently..**
2a380 20 49 66 20 61 6e 79 20 6f 66 20 74 68 65 73 65   If any of these
2a390 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61   routines are ca
2a3a0 6c 6c 65 64 20 61 66 74 65 72 20 5b 73 71 6c 69  lled after [sqli
2a3b0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a  te3_reset()] or.
2a3c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  ** [sqlite3_fina
2a3d0 6c 69 7a 65 28 29 5d 20 6f 72 20 61 66 74 65 72  lize()] or after
2a3e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
2a3f0 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64 0a 2a  ] has returned.*
2a400 2a 20 73 6f 6d 65 74 68 69 6e 67 20 6f 74 68 65  * something othe
2a410 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52  r than [SQLITE_R
2a420 4f 57 5d 2c 20 74 68 65 20 72 65 73 75 6c 74 73  OW], the results
2a430 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
2a440 2a 2a 20 49 66 20 5b 73 71 6c 69 74 65 33 5f 73  ** If [sqlite3_s
2a450 74 65 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74  tep()] or [sqlit
2a460 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72 20 5b  e3_reset()] or [
2a470 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a480 28 29 5d 0a 2a 2a 20 61 72 65 20 63 61 6c 6c 65  ()].** are calle
2a490 64 20 66 72 6f 6d 20 61 20 64 69 66 66 65 72 65  d from a differe
2a4a0 6e 74 20 74 68 72 65 61 64 20 77 68 69 6c 65 20  nt thread while 
2a4b0 61 6e 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75  any of these rou
2a4c0 74 69 6e 65 73 0a 2a 2a 20 61 72 65 20 70 65 6e  tines.** are pen
2a4d0 64 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ding, then the r
2a4e0 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66  esults are undef
2a4f0 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ined..**.** ^The
2a500 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2a510 74 79 70 65 28 29 20 72 6f 75 74 69 6e 65 20 72  type() routine r
2a520 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 5b 53  eturns the.** [S
2a530 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2a540 64 61 74 61 74 79 70 65 20 63 6f 64 65 5d 20 66  datatype code] f
2a550 6f 72 20 74 68 65 20 69 6e 69 74 69 61 6c 20 64  or the initial d
2a560 61 74 61 20 74 79 70 65 0a 2a 2a 20 6f 66 20 74  ata type.** of t
2a570 68 65 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e  he result column
2a580 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 65 64  .  ^The returned
2a590 20 76 61 6c 75 65 20 69 73 20 6f 6e 65 20 6f 66   value is one of
2a5a0 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52   [SQLITE_INTEGER
2a5b0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 46 4c  ],.** [SQLITE_FL
2a5c0 4f 41 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 54 45  OAT], [SQLITE_TE
2a5d0 58 54 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 4c 4f  XT], [SQLITE_BLO
2a5e0 42 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4e  B], or [SQLITE_N
2a5f0 55 4c 4c 5d 2e 20 20 54 68 65 20 76 61 6c 75 65  ULL].  The value
2a600 0a 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20  .** returned by 
2a610 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2a620 79 70 65 28 29 20 69 73 20 6f 6e 6c 79 20 6d 65  ype() is only me
2a630 61 6e 69 6e 67 66 75 6c 20 69 66 20 6e 6f 20 74  aningful if no t
2a640 79 70 65 0a 2a 2a 20 63 6f 6e 76 65 72 73 69 6f  ype.** conversio
2a650 6e 73 20 68 61 76 65 20 6f 63 63 75 72 72 65 64  ns have occurred
2a660 20 61 73 20 64 65 73 63 72 69 62 65 64 20 62 65   as described be
2a670 6c 6f 77 2e 20 20 41 66 74 65 72 20 61 20 74 79  low.  After a ty
2a680 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e 2c 0a 2a  pe conversion,.*
2a690 2a 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75  * the value retu
2a6a0 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  rned by sqlite3_
2a6b0 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69 73  column_type() is
2a6c0 20 75 6e 64 65 66 69 6e 65 64 2e 20 20 46 75 74   undefined.  Fut
2a6d0 75 72 65 0a 2a 2a 20 76 65 72 73 69 6f 6e 73 20  ure.** versions 
2a6e0 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 63 68  of SQLite may ch
2a6f0 61 6e 67 65 20 74 68 65 20 62 65 68 61 76 69 6f  ange the behavio
2a700 72 20 6f 66 20 73 71 6c 69 74 65 33 5f 63 6f 6c  r of sqlite3_col
2a710 75 6d 6e 5f 74 79 70 65 28 29 0a 2a 2a 20 66 6f  umn_type().** fo
2a720 6c 6c 6f 77 69 6e 67 20 61 20 74 79 70 65 20 63  llowing a type c
2a730 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  onversion..**.**
2a740 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74 20   ^If the result 
2a750 69 73 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46  is a BLOB or UTF
2a760 2d 38 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74  -8 string then t
2a770 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  he sqlite3_colum
2a780 6e 5f 62 79 74 65 73 28 29 0a 2a 2a 20 72 6f 75  n_bytes().** rou
2a790 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
2a7a0 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
2a7b0 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
2a7c0 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
2a7d0 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
2a7e0 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2c 20 74  UTF-16 string, t
2a7f0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2a800 6d 6e 5f 62 79 74 65 73 28 29 20 63 6f 6e 76 65  mn_bytes() conve
2a810 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e  rts.** the strin
2a820 67 20 74 6f 20 55 54 46 2d 38 20 61 6e 64 20 74  g to UTF-8 and t
2a830 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20  hen returns the 
2a840 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 2e  number of bytes.
2a850 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75  .** ^If the resu
2a860 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69 63 20  lt is a numeric 
2a870 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c 69 74  value then sqlit
2a880 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
2a890 29 20 75 73 65 73 0a 2a 2a 20 5b 73 71 6c 69 74  ) uses.** [sqlit
2a8a0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 20 74  e3_snprintf()] t
2a8b0 6f 20 63 6f 6e 76 65 72 74 20 74 68 61 74 20 76  o convert that v
2a8c0 61 6c 75 65 20 74 6f 20 61 20 55 54 46 2d 38 20  alue to a UTF-8 
2a8d0 73 74 72 69 6e 67 20 61 6e 64 20 72 65 74 75 72  string and retur
2a8e0 6e 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72  ns.** the number
2a8f0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
2a900 74 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  t string..** ^If
2a910 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 4e   the result is N
2a920 55 4c 4c 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ULL, then sqlite
2a930 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2a940 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a   returns zero..*
2a950 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  *.** ^If the res
2a960 75 6c 74 20 69 73 20 61 20 42 4c 4f 42 20 6f 72  ult is a BLOB or
2a970 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 74   UTF-16 string t
2a980 68 65 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f  hen the sqlite3_
2a990 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
2a9a0 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75  .** routine retu
2a9b0 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
2a9c0 66 20 62 79 74 65 73 20 69 6e 20 74 68 61 74 20  f bytes in that 
2a9d0 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67 2e 0a  BLOB or string..
2a9e0 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
2a9f0 74 20 69 73 20 61 20 55 54 46 2d 38 20 73 74 72  t is a UTF-8 str
2aa00 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c 69 74 65  ing, then sqlite
2aa10 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2aa20 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20 74  () converts.** t
2aa30 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54 46  he string to UTF
2aa40 2d 31 36 20 61 6e 64 20 74 68 65 6e 20 72 65 74  -16 and then ret
2aa50 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
2aa60 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
2aa70 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
2aa80 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
2aa90 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
2aaa0 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 75 73 65  mn_bytes16() use
2aab0 73 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e  s.** [sqlite3_sn
2aac0 70 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e  printf()] to con
2aad0 76 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20  vert that value 
2aae0 74 6f 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  to a UTF-16 stri
2aaf0 6e 67 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a  ng and returns.*
2ab00 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  * the number of 
2ab10 62 79 74 65 73 20 69 6e 20 74 68 61 74 20 73 74  bytes in that st
2ab20 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ring..** ^If the
2ab30 20 72 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c   result is NULL,
2ab40 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f   then sqlite3_co
2ab50 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 72  lumn_bytes16() r
2ab60 65 74 75 72 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a  eturns zero..**.
2ab70 2a 2a 20 5e 54 68 65 20 76 61 6c 75 65 73 20 72  ** ^The values r
2ab80 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2ab90 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
2aba0 28 29 5d 20 61 6e 64 20 0a 2a 2a 20 5b 73 71 6c  ()] and .** [sql
2abb0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2abc0 73 31 36 28 29 5d 20 64 6f 20 6e 6f 74 20 69 6e  s16()] do not in
2abd0 63 6c 75 64 65 20 74 68 65 20 7a 65 72 6f 20 74  clude the zero t
2abe0 65 72 6d 69 6e 61 74 6f 72 73 20 61 74 20 74 68  erminators at th
2abf0 65 20 65 6e 64 0a 2a 2a 20 6f 66 20 74 68 65 20  e end.** of the 
2ac00 73 74 72 69 6e 67 2e 20 20 5e 46 6f 72 20 63 6c  string.  ^For cl
2ac10 61 72 69 74 79 3a 20 74 68 65 20 76 61 6c 75 65  arity: the value
2ac20 73 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  s returned by.**
2ac30 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
2ac40 5f 62 79 74 65 73 28 29 5d 20 61 6e 64 20 5b 73  _bytes()] and [s
2ac50 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2ac60 74 65 73 31 36 28 29 5d 20 61 72 65 20 74 68 65  tes16()] are the
2ac70 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 62 79   number of.** by
2ac80 74 65 73 20 69 6e 20 74 68 65 20 73 74 72 69 6e  tes in the strin
2ac90 67 2c 20 6e 6f 74 20 74 68 65 20 6e 75 6d 62 65  g, not the numbe
2aca0 72 20 6f 66 20 63 68 61 72 61 63 74 65 72 73 2e  r of characters.
2acb0 0a 2a 2a 0a 2a 2a 20 5e 53 74 72 69 6e 67 73 20  .**.** ^Strings 
2acc0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
2acd0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
2ace0 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f  ) and sqlite3_co
2acf0 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 2c 0a 2a  lumn_text16(),.*
2ad00 2a 20 65 76 65 6e 20 65 6d 70 74 79 20 73 74 72  * even empty str
2ad10 69 6e 67 73 2c 20 61 72 65 20 61 6c 77 61 79 73  ings, are always
2ad20 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64   zero-terminated
2ad30 2e 20 20 5e 54 68 65 20 72 65 74 75 72 6e 0a 2a  .  ^The return.*
2ad40 2a 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  * value from sql
2ad50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2ad60 28 29 20 66 6f 72 20 61 20 7a 65 72 6f 2d 6c 65  () for a zero-le
2ad70 6e 67 74 68 20 42 4c 4f 42 20 69 73 20 61 20 4e  ngth BLOB is a N
2ad80 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a  ULL pointer..**.
2ad90 2a 2a 20 5e 54 68 65 20 6f 62 6a 65 63 74 20 72  ** ^The object r
2ada0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
2adb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
2adc0 28 29 5d 20 69 73 20 61 6e 0a 2a 2a 20 5b 75 6e  ()] is an.** [un
2add0 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2ade0 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 2e  3_value] object.
2adf0 20 20 41 6e 20 75 6e 70 72 6f 74 65 63 74 65 64    An unprotected
2ae00 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
2ae10 62 6a 65 63 74 0a 2a 2a 20 6d 61 79 20 6f 6e 6c  bject.** may onl
2ae20 79 20 62 65 20 75 73 65 64 20 77 69 74 68 20 5b  y be used with [
2ae30 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
2ae40 75 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  ue()] and [sqlit
2ae50 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
2ae60 29 5d 2e 0a 2a 2a 20 49 66 20 74 68 65 20 5b 75  )]..** If the [u
2ae70 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ae80 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ae90 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a 20   returned by.** 
2aea0 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
2aeb0 76 61 6c 75 65 28 29 5d 20 69 73 20 75 73 65 64  value()] is used
2aec0 20 69 6e 20 61 6e 79 20 6f 74 68 65 72 20 77 61   in any other wa
2aed0 79 2c 20 69 6e 63 6c 75 64 69 6e 67 20 63 61 6c  y, including cal
2aee0 6c 73 0a 2a 2a 20 74 6f 20 72 6f 75 74 69 6e 65  ls.** to routine
2aef0 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2af00 76 61 6c 75 65 5f 69 6e 74 28 29 5d 2c 20 5b 73  value_int()], [s
2af10 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2af20 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71 6c  t()],.** or [sql
2af30 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2af40 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20 62 65  ()], then the be
2af50 68 61 76 69 6f 72 20 69 73 20 75 6e 64 65 66 69  havior is undefi
2af60 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ned..**.** These
2af70 20 72 6f 75 74 69 6e 65 73 20 61 74 74 65 6d 70   routines attemp
2af80 74 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68 65  t to convert the
2af90 20 76 61 6c 75 65 20 77 68 65 72 65 20 61 70 70   value where app
2afa0 72 6f 70 72 69 61 74 65 2e 20 20 5e 46 6f 72 0a  ropriate.  ^For.
2afb0 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 69 66 20 74  ** example, if t
2afc0 68 65 20 69 6e 74 65 72 6e 61 6c 20 72 65 70 72  he internal repr
2afd0 65 73 65 6e 74 61 74 69 6f 6e 20 69 73 20 46 4c  esentation is FL
2afe0 4f 41 54 20 61 6e 64 20 61 20 74 65 78 74 20 72  OAT and a text r
2aff0 65 73 75 6c 74 0a 2a 2a 20 69 73 20 72 65 71 75  esult.** is requ
2b000 65 73 74 65 64 2c 20 5b 73 71 6c 69 74 65 33 5f  ested, [sqlite3_
2b010 73 6e 70 72 69 6e 74 66 28 29 5d 20 69 73 20 75  snprintf()] is u
2b020 73 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 74  sed internally t
2b030 6f 20 70 65 72 66 6f 72 6d 20 74 68 65 0a 2a 2a  o perform the.**
2b040 20 63 6f 6e 76 65 72 73 69 6f 6e 20 61 75 74 6f   conversion auto
2b050 6d 61 74 69 63 61 6c 6c 79 2e 20 20 5e 28 54 68  matically.  ^(Th
2b060 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 61 62 6c  e following tabl
2b070 65 20 64 65 74 61 69 6c 73 20 74 68 65 20 63 6f  e details the co
2b080 6e 76 65 72 73 69 6f 6e 73 0a 2a 2a 20 74 68 61  nversions.** tha
2b090 74 20 61 72 65 20 61 70 70 6c 69 65 64 3a 0a 2a  t are applied:.*
2b0a0 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
2b0b0 3e 0a 2a 2a 20 3c 74 61 62 6c 65 20 62 6f 72 64  >.** <table bord
2b0c0 65 72 3d 22 31 22 3e 0a 2a 2a 20 3c 74 72 3e 3c  er="1">.** <tr><
2b0d0 74 68 3e 20 49 6e 74 65 72 6e 61 6c 3c 62 72 3e  th> Internal<br>
2b0e0 54 79 70 65 20 3c 74 68 3e 20 52 65 71 75 65 73  Type <th> Reques
2b0f0 74 65 64 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  ted<br>Type <th>
2b100 20 20 43 6f 6e 76 65 72 73 69 6f 6e 0a 2a 2a 0a    Conversion.**.
2b110 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c  ** <tr><td>  NUL
2b120 4c 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45  L    <td> INTEGE
2b130 52 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20  R   <td> Result 
2b140 69 73 20 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  is 0.** <tr><td>
2b150 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
2b160 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 52 65  FLOAT    <td> Re
2b170 73 75 6c 74 20 69 73 20 30 2e 30 0a 2a 2a 20 3c  sult is 0.0.** <
2b180 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b190 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
2b1a0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2b1b0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2b1c0 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20  tr><td>  NULL   
2b1d0 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b1e0 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73 20 4e  <td> Result is N
2b1f0 55 4c 4c 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 3c  ULL pointer.** <
2b200 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
2b210 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 20   <td>  FLOAT    
2b220 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f  <td> Convert fro
2b230 6d 20 69 6e 74 65 67 65 72 20 74 6f 20 66 6c 6f  m integer to flo
2b240 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 49  at.** <tr><td> I
2b250 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20 54  NTEGER  <td>   T
2b260 45 58 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49  EXT    <td> ASCI
2b270 49 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  I rendering of t
2b280 68 65 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  he integer.** <t
2b290 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20  r><td> INTEGER  
2b2a0 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20 3c  <td>   BLOB    <
2b2b0 74 64 3e 20 53 61 6d 65 20 61 73 20 49 4e 54 45  td> Same as INTE
2b2c0 47 45 52 2d 3e 54 45 58 54 0a 2a 2a 20 3c 74 72  GER->TEXT.** <tr
2b2d0 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
2b2e0 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
2b2f0 64 3e 20 43 6f 6e 76 65 72 74 20 66 72 6f 6d 20  d> Convert from 
2b300 66 6c 6f 61 74 20 74 6f 20 69 6e 74 65 67 65 72  float to integer
2b310 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
2b320 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OAT   <td>   TEX
2b330 54 20 20 20 20 3c 74 64 3e 20 41 53 43 49 49 20  T    <td> ASCII 
2b340 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65  rendering of the
2b350 20 66 6c 6f 61 74 0a 2a 2a 20 3c 74 72 3e 3c 74   float.** <tr><t
2b360 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e  d>  FLOAT   <td>
2b370 20 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20     BLOB    <td> 
2b380 53 61 6d 65 20 61 73 20 46 4c 4f 41 54 2d 3e 54  Same as FLOAT->T
2b390 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
2b3a0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 49 4e   TEXT    <td> IN
2b3b0 54 45 47 45 52 20 20 20 3c 74 64 3e 20 55 73 65  TEGER   <td> Use
2b3c0 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2b3d0 74 64 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64  td>  TEXT    <td
2b3e0 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b3f0 20 55 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c   Use atof().** <
2b400 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20 20  tr><td>  TEXT   
2b410 20 3c 74 64 3e 20 20 20 42 4c 4f 42 20 20 20 20   <td>   BLOB    
2b420 3c 74 64 3e 20 4e 6f 20 63 68 61 6e 67 65 0a 2a  <td> No change.*
2b430 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c 4f 42  * <tr><td>  BLOB
2b440 20 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52      <td> INTEGER
2b450 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72 74 20     <td> Convert 
2b460 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75 73 65  to TEXT then use
2b470 20 61 74 6f 69 28 29 0a 2a 2a 20 3c 74 72 3e 3c   atoi().** <tr><
2b480 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
2b490 3e 20 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e  >  FLOAT    <td>
2b4a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
2b4b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 66 28 29   then use atof()
2b4c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
2b4d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 20 54 45 58  OB    <td>   TEX
2b4e0 54 20 20 20 20 3c 74 64 3e 20 41 64 64 20 61 20  T    <td> Add a 
2b4f0 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 20  zero terminator 
2b500 69 66 20 6e 65 65 64 65 64 0a 2a 2a 20 3c 2f 74  if needed.** </t
2b510 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62 6c 6f 63 6b  able>.** </block
2b520 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54  quote>)^.**.** T
2b530 68 65 20 74 61 62 6c 65 20 61 62 6f 76 65 20 6d  he table above m
2b540 61 6b 65 73 20 72 65 66 65 72 65 6e 63 65 20 74  akes reference t
2b550 6f 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  o standard C lib
2b560 72 61 72 79 20 66 75 6e 63 74 69 6f 6e 73 20 61  rary functions a
2b570 74 6f 69 28 29 0a 2a 2a 20 61 6e 64 20 61 74 6f  toi().** and ato
2b580 66 28 29 2e 20 20 53 51 4c 69 74 65 20 64 6f 65  f().  SQLite doe
2b590 73 20 6e 6f 74 20 72 65 61 6c 6c 79 20 75 73 65  s not really use
2b5a0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2b5b0 2e 20 20 49 74 20 68 61 73 20 69 74 73 0a 2a 2a  .  It has its.**
2b5c0 20 6f 77 6e 20 65 71 75 69 76 61 6c 65 6e 74 20   own equivalent 
2b5d0 69 6e 74 65 72 6e 61 6c 20 72 6f 75 74 69 6e 65  internal routine
2b5e0 73 2e 20 20 54 68 65 20 61 74 6f 69 28 29 20 61  s.  The atoi() a
2b5f0 6e 64 20 61 74 6f 66 28 29 20 6e 61 6d 65 73 20  nd atof() names 
2b600 61 72 65 0a 2a 2a 20 75 73 65 64 20 69 6e 20 74  are.** used in t
2b610 68 65 20 74 61 62 6c 65 20 66 6f 72 20 62 72 65  he table for bre
2b620 76 69 74 79 20 61 6e 64 20 62 65 63 61 75 73 65  vity and because
2b630 20 74 68 65 79 20 61 72 65 20 66 61 6d 69 6c 69   they are famili
2b640 61 72 20 74 6f 20 6d 6f 73 74 0a 2a 2a 20 43 20  ar to most.** C 
2b650 70 72 6f 67 72 61 6d 6d 65 72 73 2e 0a 2a 2a 0a  programmers..**.
2b660 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 77 68 65  ** Note that whe
2b670 6e 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  n type conversio
2b680 6e 73 20 6f 63 63 75 72 2c 20 70 6f 69 6e 74 65  ns occur, pointe
2b690 72 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 70  rs returned by p
2b6a0 72 69 6f 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  rior.** calls to
2b6b0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2b6c0 62 6c 6f 62 28 29 2c 20 73 71 6c 69 74 65 33 5f  blob(), sqlite3_
2b6d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 20 61  column_text(), a
2b6e0 6e 64 2f 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  nd/or.** sqlite3
2b6f0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
2b700 20 6d 61 79 20 62 65 20 69 6e 76 61 6c 69 64 61   may be invalida
2b710 74 65 64 2e 0a 2a 2a 20 54 79 70 65 20 63 6f 6e  ted..** Type con
2b720 76 65 72 73 69 6f 6e 73 20 61 6e 64 20 70 6f 69  versions and poi
2b730 6e 74 65 72 20 69 6e 76 61 6c 69 64 61 74 69 6f  nter invalidatio
2b740 6e 73 20 6d 69 67 68 74 20 6f 63 63 75 72 0a 2a  ns might occur.*
2b750 2a 20 69 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69  * in the followi
2b760 6e 67 20 63 61 73 65 73 3a 0a 2a 2a 0a 2a 2a 20  ng cases:.**.** 
2b770 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
2b780 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2b790 20 69 73 20 61 20 42 4c 4f 42 20 61 6e 64 20 73   is a BLOB and s
2b7a0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2b7b0 78 74 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  xt() or.**      
2b7c0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
2b7d0 65 78 74 31 36 28 29 20 69 73 20 63 61 6c 6c 65  ext16() is calle
2b7e0 64 2e 20 20 41 20 7a 65 72 6f 2d 74 65 72 6d 69  d.  A zero-termi
2b7f0 6e 61 74 6f 72 20 6d 69 67 68 74 0a 2a 2a 20 20  nator might.**  
2b800 20 20 20 20 6e 65 65 64 20 74 6f 20 62 65 20 61      need to be a
2b810 64 64 65 64 20 74 6f 20 74 68 65 20 73 74 72 69  dded to the stri
2b820 6e 67 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e  ng.</li>.** <li>
2b830 20 54 68 65 20 69 6e 69 74 69 61 6c 20 63 6f 6e   The initial con
2b840 74 65 6e 74 20 69 73 20 55 54 46 2d 38 20 74 65  tent is UTF-8 te
2b850 78 74 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 63  xt and sqlite3_c
2b860 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 20  olumn_bytes16() 
2b870 6f 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74  or.**      sqlit
2b880 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36  e3_column_text16
2b890 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 54  () is called.  T
2b8a0 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73 74 20  he content must 
2b8b0 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a 2a 20  be converted.** 
2b8c0 20 20 20 20 20 74 6f 20 55 54 46 2d 31 36 2e 3c       to UTF-16.<
2b8d0 2f 6c 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  /li>.** <li> The
2b8e0 20 69 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74   initial content
2b8f0 20 69 73 20 55 54 46 2d 31 36 20 74 65 78 74 20   is UTF-16 text 
2b900 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
2b910 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a 2a 2a  mn_bytes() or.**
2b920 20 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f        sqlite3_co
2b930 6c 75 6d 6e 5f 74 65 78 74 28 29 20 69 73 20 63  lumn_text() is c
2b940 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
2b950 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
2b960 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
2b970 20 55 54 46 2d 38 2e 3c 2f 6c 69 3e 0a 2a 2a 20   UTF-8.</li>.** 
2b980 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e  </ul>.**.** ^Con
2b990 76 65 72 73 69 6f 6e 73 20 62 65 74 77 65 65 6e  versions between
2b9a0 20 55 54 46 2d 31 36 62 65 20 61 6e 64 20 55 54   UTF-16be and UT
2b9b0 46 2d 31 36 6c 65 20 61 72 65 20 61 6c 77 61 79  F-16le are alway
2b9c0 73 20 64 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20  s done in place 
2b9d0 61 6e 64 20 64 6f 0a 2a 2a 20 6e 6f 74 20 69 6e  and do.** not in
2b9e0 76 61 6c 69 64 61 74 65 20 61 20 70 72 69 6f 72  validate a prior
2b9f0 20 70 6f 69 6e 74 65 72 2c 20 74 68 6f 75 67 68   pointer, though
2ba00 20 6f 66 20 63 6f 75 72 73 65 20 74 68 65 20 63   of course the c
2ba10 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 62 75  ontent of the bu
2ba20 66 66 65 72 0a 2a 2a 20 74 68 61 74 20 74 68 65  ffer.** that the
2ba30 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 20 72   prior pointer r
2ba40 65 66 65 72 65 6e 63 65 73 20 77 69 6c 6c 20 68  eferences will h
2ba50 61 76 65 20 62 65 65 6e 20 6d 6f 64 69 66 69 65  ave been modifie
2ba60 64 2e 20 20 4f 74 68 65 72 20 6b 69 6e 64 73 0a  d.  Other kinds.
2ba70 2a 2a 20 6f 66 20 63 6f 6e 76 65 72 73 69 6f 6e  ** of conversion
2ba80 20 61 72 65 20 64 6f 6e 65 20 69 6e 20 70 6c 61   are done in pla
2ba90 63 65 20 77 68 65 6e 20 69 74 20 69 73 20 70 6f  ce when it is po
2baa0 73 73 69 62 6c 65 2c 20 62 75 74 20 73 6f 6d 65  ssible, but some
2bab0 74 69 6d 65 73 20 74 68 65 79 0a 2a 2a 20 61 72  times they.** ar
2bac0 65 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 61  e not possible a
2bad0 6e 64 20 69 6e 20 74 68 6f 73 65 20 63 61 73 65  nd in those case
2bae0 73 20 70 72 69 6f 72 20 70 6f 69 6e 74 65 72 73  s prior pointers
2baf0 20 61 72 65 20 69 6e 76 61 6c 69 64 61 74 65 64   are invalidated
2bb00 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 61 66 65  ..**.** The safe
2bb10 73 74 20 61 6e 64 20 65 61 73 69 65 73 74 20 74  st and easiest t
2bb20 6f 20 72 65 6d 65 6d 62 65 72 20 70 6f 6c 69 63  o remember polic
2bb30 79 20 69 73 20 74 6f 20 69 6e 76 6f 6b 65 20 74  y is to invoke t
2bb40 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a 2a  hese routines.**
2bb50 20 69 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 66   in one of the f
2bb60 6f 6c 6c 6f 77 69 6e 67 20 77 61 79 73 3a 0a 2a  ollowing ways:.*
2bb70 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 20 3c 6c  *.** <ul>.**  <l
2bb80 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
2bb90 5f 74 65 78 74 28 29 20 66 6f 6c 6c 6f 77 65 64  _text() followed
2bba0 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
2bbb0 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
2bbc0 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
2bbd0 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f  column_blob() fo
2bbe0 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74 65  llowed by sqlite
2bbf0 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29  3_column_bytes()
2bc00 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71  </li>.**  <li>sq
2bc10 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2bc20 74 31 36 28 29 20 66 6f 6c 6c 6f 77 65 64 20 62  t16() followed b
2bc30 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
2bc40 5f 62 79 74 65 73 31 36 28 29 3c 2f 6c 69 3e 0a  _bytes16()</li>.
2bc50 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49  ** </ul>.**.** I
2bc60 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 79  n other words, y
2bc70 6f 75 20 73 68 6f 75 6c 64 20 63 61 6c 6c 20 73  ou should call s
2bc80 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
2bc90 78 74 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  xt(),.** sqlite3
2bca0 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c 20  _column_blob(), 
2bcb0 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  or sqlite3_colum
2bcc0 6e 5f 74 65 78 74 31 36 28 29 20 66 69 72 73 74  n_text16() first
2bcd0 20 74 6f 20 66 6f 72 63 65 20 74 68 65 20 72 65   to force the re
2bce0 73 75 6c 74 0a 2a 2a 20 69 6e 74 6f 20 74 68 65  sult.** into the
2bcf0 20 64 65 73 69 72 65 64 20 66 6f 72 6d 61 74 2c   desired format,
2bd00 20 74 68 65 6e 20 69 6e 76 6f 6b 65 20 73 71 6c   then invoke sql
2bd10 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2bd20 73 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  s() or.** sqlite
2bd30 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36  3_column_bytes16
2bd40 28 29 20 74 6f 20 66 69 6e 64 20 74 68 65 20 73  () to find the s
2bd50 69 7a 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c  ize of the resul
2bd60 74 2e 20 20 44 6f 20 6e 6f 74 20 6d 69 78 20 63  t.  Do not mix c
2bd70 61 6c 6c 73 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  alls.** to sqlit
2bd80 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2bd90 20 6f 72 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   or sqlite3_colu
2bda0 6d 6e 5f 62 6c 6f 62 28 29 20 77 69 74 68 20 63  mn_blob() with c
2bdb0 61 6c 6c 73 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  alls to.** sqlit
2bdc0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2bdd0 36 28 29 2c 20 61 6e 64 20 64 6f 20 6e 6f 74 20  6(), and do not 
2bde0 6d 69 78 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c  mix calls to sql
2bdf0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2be00 31 36 28 29 0a 2a 2a 20 77 69 74 68 20 63 61 6c  16().** with cal
2be10 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2be20 6c 75 6d 6e 5f 62 79 74 65 73 28 29 2e 0a 2a 2a  lumn_bytes()..**
2be30 0a 2a 2a 20 5e 54 68 65 20 70 6f 69 6e 74 65 72  .** ^The pointer
2be40 73 20 72 65 74 75 72 6e 65 64 20 61 72 65 20 76  s returned are v
2be50 61 6c 69 64 20 75 6e 74 69 6c 20 61 20 74 79 70  alid until a typ
2be60 65 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f 63 63  e conversion occ
2be70 75 72 73 20 61 73 0a 2a 2a 20 64 65 73 63 72 69  urs as.** descri
2be80 62 65 64 20 61 62 6f 76 65 2c 20 6f 72 20 75 6e  bed above, or un
2be90 74 69 6c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  til [sqlite3_ste
2bea0 70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  p()] or [sqlite3
2beb0 5f 72 65 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20  _reset()] or.** 
2bec0 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a  [sqlite3_finaliz
2bed0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 2e 20  e()] is called. 
2bee0 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 73 70 61   ^The memory spa
2bef0 63 65 20 75 73 65 64 20 74 6f 20 68 6f 6c 64 20  ce used to hold 
2bf00 73 74 72 69 6e 67 73 0a 2a 2a 20 61 6e 64 20 42  strings.** and B
2bf10 4c 4f 42 73 20 69 73 20 66 72 65 65 64 20 61 75  LOBs is freed au
2bf20 74 6f 6d 61 74 69 63 61 6c 6c 79 2e 20 20 44 6f  tomatically.  Do
2bf30 20 3c 62 3e 6e 6f 74 3c 2f 62 3e 20 70 61 73 73   <b>not</b> pass
2bf40 20 74 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65   the pointers re
2bf50 74 75 72 6e 65 64 0a 2a 2a 20 5b 73 71 6c 69 74  turned.** [sqlit
2bf60 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
2bf70 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ], [sqlite3_colu
2bf80 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 65 74 63 2e  mn_text()], etc.
2bf90 20 69 6e 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65   into.** [sqlite
2bfa0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
2bfb0 20 5e 28 49 66 20 61 20 6d 65 6d 6f 72 79 20 61   ^(If a memory a
2bfc0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 20  llocation error 
2bfd0 6f 63 63 75 72 73 20 64 75 72 69 6e 67 20 74 68  occurs during th
2bfe0 65 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  e evaluation of 
2bff0 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 73 65 20  any.** of these 
2c000 72 6f 75 74 69 6e 65 73 2c 20 61 20 64 65 66 61  routines, a defa
2c010 75 6c 74 20 76 61 6c 75 65 20 69 73 20 72 65 74  ult value is ret
2c020 75 72 6e 65 64 2e 20 20 54 68 65 20 64 65 66 61  urned.  The defa
2c030 75 6c 74 20 76 61 6c 75 65 0a 2a 2a 20 69 73 20  ult value.** is 
2c040 65 69 74 68 65 72 20 74 68 65 20 69 6e 74 65 67  either the integ
2c050 65 72 20 30 2c 20 74 68 65 20 66 6c 6f 61 74 69  er 0, the floati
2c060 6e 67 20 70 6f 69 6e 74 20 6e 75 6d 62 65 72 20  ng point number 
2c070 30 2e 30 2c 20 6f 72 20 61 20 4e 55 4c 4c 0a 2a  0.0, or a NULL.*
2c080 2a 20 70 6f 69 6e 74 65 72 2e 20 20 53 75 62 73  * pointer.  Subs
2c090 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
2c0a0 5b 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65  [sqlite3_errcode
2c0b0 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 0a  ()] will return.
2c0c0 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  ** [SQLITE_NOMEM
2c0d0 5d 2e 29 5e 0a 2a 2f 0a 63 6f 6e 73 74 20 76 6f  ].)^.*/.const vo
2c0e0 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
2c0f0 6d 6e 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  mn_blob(sqlite3_
2c100 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c110 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  ;.int sqlite3_co
2c120 6c 75 6d 6e 5f 62 79 74 65 73 28 73 71 6c 69 74  lumn_bytes(sqlit
2c130 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43  e3_stmt*, int iC
2c140 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ol);.int sqlite3
2c150 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
2c160 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2c170 6e 74 20 69 43 6f 6c 29 3b 0a 64 6f 75 62 6c 65  nt iCol);.double
2c180 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
2c190 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73  double(sqlite3_s
2c1a0 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b  tmt*, int iCol);
2c1b0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c  .int sqlite3_col
2c1c0 75 6d 6e 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  umn_int(sqlite3_
2c1d0 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c1e0 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2c1f0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69  sqlite3_column_i
2c200 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 73 74 6d  nt64(sqlite3_stm
2c210 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63  t*, int iCol);.c
2c220 6f 6e 73 74 20 75 6e 73 69 67 6e 65 64 20 63 68  onst unsigned ch
2c230 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ar *sqlite3_colu
2c240 6d 6e 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f  mn_text(sqlite3_
2c250 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29  stmt*, int iCol)
2c260 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
2c270 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
2c280 74 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  t16(sqlite3_stmt
2c290 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2c2a0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2c2b0 5f 74 79 70 65 28 73 71 6c 69 74 65 33 5f 73 74  _type(sqlite3_st
2c2c0 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a  mt*, int iCol);.
2c2d0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 2a 73  sqlite3_value *s
2c2e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61  qlite3_column_va
2c2f0 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  lue(sqlite3_stmt
2c300 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 0a 2f  *, int iCol);../
2c310 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2c320 65 73 74 72 6f 79 20 41 20 50 72 65 70 61 72 65  estroy A Prepare
2c330 64 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65  d Statement Obje
2c340 63 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ct.**.** ^The sq
2c350 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2c360 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2c370 6c 65 64 20 74 6f 20 64 65 6c 65 74 65 20 61 20  led to delete a 
2c380 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c390 65 6e 74 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  ent]..** ^If the
2c3a0 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76 61   most recent eva
2c3b0 6c 75 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 73  luation of the s
2c3c0 74 61 74 65 6d 65 6e 74 20 65 6e 63 6f 75 6e 74  tatement encount
2c3d0 65 72 65 64 20 6e 6f 20 65 72 72 6f 72 73 0a 2a  ered no errors.*
2c3e0 2a 20 6f 72 20 69 66 20 74 68 65 20 73 74 61 74  * or if the stat
2c3f0 65 6d 65 6e 74 20 69 73 20 6e 65 76 65 72 20 62  ement is never b
2c400 65 65 6e 20 65 76 61 6c 75 61 74 65 64 2c 20 74  een evaluated, t
2c410 68 65 6e 20 73 71 6c 69 74 65 33 5f 66 69 6e 61  hen sqlite3_fina
2c420 6c 69 7a 65 28 29 20 72 65 74 75 72 6e 73 0a 2a  lize() returns.*
2c430 2a 20 53 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49  * SQLITE_OK.  ^I
2c440 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  f the most recen
2c450 74 20 65 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20  t evaluation of 
2c460 73 74 61 74 65 6d 65 6e 74 20 53 20 66 61 69 6c  statement S fail
2c470 65 64 2c 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69  ed, then.** sqli
2c480 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20  te3_finalize(S) 
2c490 72 65 74 75 72 6e 73 20 74 68 65 20 61 70 70 72  returns the appr
2c4a0 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72 20 63  opriate [error c
2c4b0 6f 64 65 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  ode] or.** [exte
2c4c0 6e 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 5d  nded error code]
2c4d0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2c4e0 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29  ite3_finalize(S)
2c4f0 20 72 6f 75 74 69 6e 65 20 63 61 6e 20 62 65 20   routine can be 
2c500 63 61 6c 6c 65 64 20 61 74 20 61 6e 79 20 70 6f  called at any po
2c510 69 6e 74 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68  int during.** th
2c520 65 20 6c 69 66 65 20 63 79 63 6c 65 20 6f 66 20  e life cycle of 
2c530 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2c540 65 6e 74 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72  ent] S:.** befor
2c550 65 20 73 74 61 74 65 6d 65 6e 74 20 53 20 69 73  e statement S is
2c560 20 65 76 65 72 20 65 76 61 6c 75 61 74 65 64 2c   ever evaluated,
2c570 20 61 66 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72   after.** one or
2c580 20 6d 6f 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b   more calls to [
2c590 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
2c5a0 2c 20 6f 72 20 61 66 74 65 72 20 61 6e 79 20 63  , or after any c
2c5b0 61 6c 6c 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  all.** to [sqlit
2c5c0 65 33 5f 73 74 65 70 28 29 5d 20 72 65 67 61 72  e3_step()] regar
2c5d0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
2c5e0 20 6f 72 20 6e 6f 74 20 74 68 65 20 73 74 61 74   or not the stat
2c5f0 65 6d 65 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d  ement has.** com
2c600 70 6c 65 74 65 64 20 65 78 65 63 75 74 69 6f 6e  pleted execution
2c610 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e  ..**.** ^Invokin
2c620 67 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69  g sqlite3_finali
2c630 7a 65 28 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70  ze() on a NULL p
2c640 6f 69 6e 74 65 72 20 69 73 20 61 20 68 61 72 6d  ointer is a harm
2c650 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a  less no-op..**.*
2c660 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
2c670 6e 20 6d 75 73 74 20 66 69 6e 61 6c 69 7a 65 20  n must finalize 
2c680 65 76 65 72 79 20 5b 70 72 65 70 61 72 65 64 20  every [prepared 
2c690 73 74 61 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72  statement] in or
2c6a0 64 65 72 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20  der to avoid.** 
2c6b0 72 65 73 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20  resource leaks. 
2c6c0 20 49 74 20 69 73 20 61 20 67 72 69 65 76 6f 75   It is a grievou
2c6d0 73 20 65 72 72 6f 72 20 66 6f 72 20 74 68 65 20  s error for the 
2c6e0 61 70 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74  application to t
2c6f0 72 79 20 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70  ry to use.** a p
2c700 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
2c710 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62  t after it has b
2c720 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20  een finalized.  
2c730 41 6e 79 20 75 73 65 20 6f 66 20 61 20 70 72 65  Any use of a pre
2c740 70 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65  pared.** stateme
2c750 6e 74 20 61 66 74 65 72 20 69 74 20 68 61 73 20  nt after it has 
2c760 62 65 65 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63  been finalized c
2c770 61 6e 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64  an result in und
2c780 65 66 69 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e  efined and.** un
2c790 64 65 73 69 72 61 62 6c 65 20 62 65 68 61 76 69  desirable behavi
2c7a0 6f 72 20 73 75 63 68 20 61 73 20 73 65 67 66 61  or such as segfa
2c7b0 75 6c 74 73 20 61 6e 64 20 68 65 61 70 20 63 6f  ults and heap co
2c7c0 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74  rruption..*/.int
2c7d0 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
2c7e0 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a  e(sqlite3_stmt *
2c7f0 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  pStmt);../*.** C
2c800 41 50 49 33 52 45 46 3a 20 52 65 73 65 74 20 41  API3REF: Reset A
2c810 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d   Prepared Statem
2c820 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a  ent Object.**.**
2c830 20 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73   The sqlite3_res
2c840 65 74 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73  et() function is
2c850 20 63 61 6c 6c 65 64 20 74 6f 20 72 65 73 65 74   called to reset
2c860 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
2c870 74 65 6d 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63  tement].** objec
2c880 74 20 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e  t back to its in
2c890 69 74 69 61 6c 20 73 74 61 74 65 2c 20 72 65 61  itial state, rea
2c8a0 64 79 20 74 6f 20 62 65 20 72 65 2d 65 78 65 63  dy to be re-exec
2c8b0 75 74 65 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51  uted..** ^Any SQ
2c8c0 4c 20 73 74 61 74 65 6d 65 6e 74 20 76 61 72 69  L statement vari
2c8d0 61 62 6c 65 73 20 74 68 61 74 20 68 61 64 20 76  ables that had v
2c8e0 61 6c 75 65 73 20 62 6f 75 6e 64 20 74 6f 20 74  alues bound to t
2c8f0 68 65 6d 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65  hem using.** the
2c900 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62   [sqlite3_bind_b
2c910 6c 6f 62 20 7c 20 73 71 6c 69 74 65 33 5f 62 69  lob | sqlite3_bi
2c920 6e 64 5f 2a 28 29 20 41 50 49 5d 20 72 65 74 61  nd_*() API] reta
2c930 69 6e 20 74 68 65 69 72 20 76 61 6c 75 65 73 2e  in their values.
2c940 0a 2a 2a 20 55 73 65 20 5b 73 71 6c 69 74 65 33  .** Use [sqlite3
2c950 5f 63 6c 65 61 72 5f 62 69 6e 64 69 6e 67 73 28  _clear_bindings(
2c960 29 5d 20 74 6f 20 72 65 73 65 74 20 74 68 65 20  )] to reset the 
2c970 62 69 6e 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20  bindings..**.** 
2c980 5e 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65  ^The [sqlite3_re
2c990 73 65 74 28 53 29 5d 20 69 6e 74 65 72 66 61 63  set(S)] interfac
2c9a0 65 20 72 65 73 65 74 73 20 74 68 65 20 5b 70 72  e resets the [pr
2c9b0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
2c9c0 5d 20 53 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74  ] S.** back to t
2c9d0 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20  he beginning of 
2c9e0 69 74 73 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a  its program..**.
2c9f0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
2ca00 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b  recent call to [
2ca10 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29 5d  sqlite3_step(S)]
2ca20 20 66 6f 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65   for the.** [pre
2ca30 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2ca40 20 53 20 72 65 74 75 72 6e 65 64 20 5b 53 51 4c   S returned [SQL
2ca50 49 54 45 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c  ITE_ROW] or [SQL
2ca60 49 54 45 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72  ITE_DONE],.** or
2ca70 20 69 66 20 5b 73 71 6c 69 74 65 33 5f 73 74 65   if [sqlite3_ste
2ca80 70 28 53 29 5d 20 68 61 73 20 6e 65 76 65 72 20  p(S)] has never 
2ca90 62 65 66 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c  before been call
2caa0 65 64 20 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e  ed on S,.** then
2cab0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2cac0 53 29 5d 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  S)] returns [SQL
2cad0 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  ITE_OK]..**.** ^
2cae0 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2caf0 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2cb00 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2cb10 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2cb20 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 69  d statement] S i
2cb30 6e 64 69 63 61 74 65 64 20 61 6e 20 65 72 72 6f  ndicated an erro
2cb40 72 2c 20 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69  r, then.** [sqli
2cb50 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 72 65  te3_reset(S)] re
2cb60 74 75 72 6e 73 20 61 6e 20 61 70 70 72 6f 70 72  turns an appropr
2cb70 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
2cb80 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  ]..**.** ^The [s
2cb90 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
2cba0 20 69 6e 74 65 72 66 61 63 65 20 64 6f 65 73 20   interface does 
2cbb0 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76  not change the v
2cbc0 61 6c 75 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20  alues.** of any 
2cbd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
2cbe0 6f 62 7c 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20  ob|bindings] on 
2cbf0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
2cc00 61 74 65 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69  atement] S..*/.i
2cc10 6e 74 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74  nt sqlite3_reset
2cc20 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70  (sqlite3_stmt *p
2cc30 53 74 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  Stmt);../*.** CA
2cc40 50 49 33 52 45 46 3a 20 43 72 65 61 74 65 20 4f  PI3REF: Create O
2cc50 72 20 52 65 64 65 66 69 6e 65 20 53 51 4c 20 46  r Redefine SQL F
2cc60 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57  unctions.** KEYW
2cc70 4f 52 44 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20  ORDS: {function 
2cc80 63 72 65 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  creation routine
2cc90 73 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  s}.** KEYWORDS: 
2cca0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2ccb0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2ccc0 6e 7d 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20  n}.** KEYWORDS: 
2ccd0 7b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66  {application-def
2cce0 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
2ccf0 6e 73 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  ns}.**.** ^These
2cd00 20 66 75 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c   functions (coll
2cd10 65 63 74 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61  ectively known a
2cd20 73 20 22 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  s "function crea
2cd30 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a  tion routines").
2cd40 2a 2a 20 61 72 65 20 75 73 65 64 20 74 6f 20 61  ** are used to a
2cd50 64 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  dd SQL functions
2cd60 20 6f 72 20 61 67 67 72 65 67 61 74 65 73 20 6f   or aggregates o
2cd70 72 20 74 6f 20 72 65 64 65 66 69 6e 65 20 74 68  r to redefine th
2cd80 65 20 62 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66  e behavior.** of
2cd90 20 65 78 69 73 74 69 6e 67 20 53 51 4c 20 66 75   existing SQL fu
2cda0 6e 63 74 69 6f 6e 73 20 6f 72 20 61 67 67 72 65  nctions or aggre
2cdb0 67 61 74 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79  gates.  The only
2cdc0 20 64 69 66 66 65 72 65 6e 63 65 73 20 62 65 74   differences bet
2cdd0 77 65 65 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f  ween.** these ro
2cde0 75 74 69 6e 65 73 20 61 72 65 20 74 68 65 20 74  utines are the t
2cdf0 65 78 74 20 65 6e 63 6f 64 69 6e 67 20 65 78 70  ext encoding exp
2ce00 65 63 74 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65  ected for.** the
2ce10 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2ce20 72 20 28 74 68 65 20 6e 61 6d 65 20 6f 66 20 74  r (the name of t
2ce30 68 65 20 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e  he function bein
2ce40 67 20 63 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e  g created).** an
2ce50 64 20 74 68 65 20 70 72 65 73 65 6e 63 65 20 6f  d the presence o
2ce60 72 20 61 62 73 65 6e 63 65 20 6f 66 20 61 20 64  r absence of a d
2ce70 65 73 74 72 75 63 74 6f 72 20 63 61 6c 6c 62 61  estructor callba
2ce80 63 6b 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70  ck for.** the ap
2ce90 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20 70  plication data p
2cea0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2ceb0 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2cec0 65 72 20 69 73 20 74 68 65 20 5b 64 61 74 61 62  er is the [datab
2ced0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
2cee0 74 6f 20 77 68 69 63 68 20 74 68 65 20 53 51 4c  to which the SQL
2cef0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  .** function is 
2cf00 74 6f 20 62 65 20 61 64 64 65 64 2e 20 20 5e 49  to be added.  ^I
2cf10 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
2cf20 20 75 73 65 73 20 6d 6f 72 65 20 74 68 61 6e 20   uses more than 
2cf30 6f 6e 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  one database.** 
2cf40 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20  connection then 
2cf50 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2cf60 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ned SQL function
2cf70 73 20 6d 75 73 74 20 62 65 20 61 64 64 65 64 0a  s must be added.
2cf80 2a 2a 20 74 6f 20 65 61 63 68 20 64 61 74 61 62  ** to each datab
2cf90 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73  ase connection s
2cfa0 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
2cfb0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
2cfc0 61 6d 65 74 65 72 20 69 73 20 74 68 65 20 6e 61  ameter is the na
2cfd0 6d 65 20 6f 66 20 74 68 65 20 53 51 4c 20 66 75  me of the SQL fu
2cfe0 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 63 72 65  nction to be cre
2cff0 61 74 65 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66  ated or.** redef
2d000 69 6e 65 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67  ined.  ^The leng
2d010 74 68 20 6f 66 20 74 68 65 20 6e 61 6d 65 20 69  th of the name i
2d020 73 20 6c 69 6d 69 74 65 64 20 74 6f 20 32 35 35  s limited to 255
2d030 20 62 79 74 65 73 20 69 6e 20 61 20 55 54 46 2d   bytes in a UTF-
2d040 38 0a 2a 2a 20 72 65 70 72 65 73 65 6e 74 61 74  8.** representat
2d050 69 6f 6e 2c 20 65 78 63 6c 75 73 69 76 65 20 6f  ion, exclusive o
2d060 66 20 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69  f the zero-termi
2d070 6e 61 74 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68  nator.  ^Note th
2d080 61 74 20 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c  at the name.** l
2d090 65 6e 67 74 68 20 6c 69 6d 69 74 20 69 73 20 69  ength limit is i
2d0a0 6e 20 55 54 46 2d 38 20 62 79 74 65 73 2c 20 6e  n UTF-8 bytes, n
2d0b0 6f 74 20 63 68 61 72 61 63 74 65 72 73 20 6e 6f  ot characters no
2d0c0 72 20 55 54 46 2d 31 36 20 62 79 74 65 73 2e 20  r UTF-16 bytes. 
2d0d0 20 0a 2a 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70   .** ^Any attemp
2d0e0 74 20 74 6f 20 63 72 65 61 74 65 20 61 20 66 75  t to create a fu
2d0f0 6e 63 74 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f  nction with a lo
2d100 6e 67 65 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c  nger name.** wil
2d110 6c 20 72 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c  l result in [SQL
2d120 49 54 45 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e  ITE_MISUSE] bein
2d130 67 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a  g returned..**.*
2d140 2a 20 5e 54 68 65 20 74 68 69 72 64 20 70 61 72  * ^The third par
2d150 61 6d 65 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a  ameter (nArg).**
2d160 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   is the number o
2d170 66 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61 74  f arguments that
2d180 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f   the SQL functio
2d190 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65 67 61 74  n or.** aggregat
2d1a0 65 20 74 61 6b 65 73 2e 20 5e 49 66 20 74 68 69  e takes. ^If thi
2d1b0 73 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 2d  s parameter is -
2d1c0 31 2c 20 74 68 65 6e 20 74 68 65 20 53 51 4c 20  1, then the SQL 
2d1d0 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61  function or.** a
2d1e0 67 67 72 65 67 61 74 65 20 6d 61 79 20 74 61 6b  ggregate may tak
2d1f0 65 20 61 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20  e any number of 
2d200 61 72 67 75 6d 65 6e 74 73 20 62 65 74 77 65 65  arguments betwee
2d210 6e 20 30 20 61 6e 64 20 74 68 65 20 6c 69 6d 69  n 0 and the limi
2d220 74 0a 2a 2a 20 73 65 74 20 62 79 20 5b 73 71 6c  t.** set by [sql
2d230 69 74 65 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c  ite3_limit]([SQL
2d240 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49  ITE_LIMIT_FUNCTI
2d250 4f 4e 5f 41 52 47 5d 29 2e 20 20 49 66 20 74 68  ON_ARG]).  If th
2d260 65 20 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d  e third.** param
2d270 65 74 65 72 20 69 73 20 6c 65 73 73 20 74 68 61  eter is less tha
2d280 6e 20 2d 31 20 6f 72 20 67 72 65 61 74 65 72 20  n -1 or greater 
2d290 74 68 61 6e 20 31 32 37 20 74 68 65 6e 20 74 68  than 127 then th
2d2a0 65 20 62 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a  e behavior is.**
2d2b0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
2d2c0 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 70 61  * ^The fourth pa
2d2d0 72 61 6d 65 74 65 72 2c 20 65 54 65 78 74 52 65  rameter, eTextRe
2d2e0 70 2c 20 73 70 65 63 69 66 69 65 73 20 77 68 61  p, specifies wha
2d2f0 74 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46  t.** [SQLITE_UTF
2d300 38 20 7c 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  8 | text encodin
2d310 67 5d 20 74 68 69 73 20 53 51 4c 20 66 75 6e 63  g] this SQL func
2d320 74 69 6f 6e 20 70 72 65 66 65 72 73 20 66 6f 72  tion prefers for
2d330 0a 2a 2a 20 69 74 73 20 70 61 72 61 6d 65 74 65  .** its paramete
2d340 72 73 2e 20 20 45 76 65 72 79 20 53 51 4c 20 66  rs.  Every SQL f
2d350 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2d360 74 61 74 69 6f 6e 20 6d 75 73 74 20 62 65 20 61  tation must be a
2d370 62 6c 65 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77  ble to work.** w
2d380 69 74 68 20 55 54 46 2d 38 2c 20 55 54 46 2d 31  ith UTF-8, UTF-1
2d390 36 6c 65 2c 20 6f 72 20 55 54 46 2d 31 36 62 65  6le, or UTF-16be
2d3a0 2e 20 20 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c  .  But some impl
2d3b0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20  ementations may 
2d3c0 62 65 0a 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63  be.** more effic
2d3d0 69 65 6e 74 20 77 69 74 68 20 6f 6e 65 20 65 6e  ient with one en
2d3e0 63 6f 64 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74  coding than anot
2d3f0 68 65 72 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63  her.  ^An applic
2d400 61 74 69 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76  ation may.** inv
2d410 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61  oke sqlite3_crea
2d420 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72  te_function() or
2d430 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2d440 66 75 6e 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c  function16() mul
2d450 74 69 70 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77  tiple.** times w
2d460 69 74 68 20 74 68 65 20 73 61 6d 65 20 66 75 6e  ith the same fun
2d470 63 74 69 6f 6e 20 62 75 74 20 77 69 74 68 20 64  ction but with d
2d480 69 66 66 65 72 65 6e 74 20 76 61 6c 75 65 73 20  ifferent values 
2d490 6f 66 20 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20  of eTextRep..** 
2d4a0 5e 57 68 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69  ^When multiple i
2d4b0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2d4c0 66 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74  f the same funct
2d4d0 69 6f 6e 20 61 72 65 20 61 76 61 69 6c 61 62 6c  ion are availabl
2d4e0 65 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c  e, SQLite.** wil
2d4f0 6c 20 70 69 63 6b 20 74 68 65 20 6f 6e 65 20 74  l pick the one t
2d500 68 61 74 20 69 6e 76 6f 6c 76 65 73 20 74 68 65  hat involves the
2d510 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66   least amount of
2d520 20 64 61 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e   data conversion
2d530 2e 0a 2a 2a 20 49 66 20 74 68 65 72 65 20 69 73  ..** If there is
2d540 20 6f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 69   only a single i
2d550 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68  mplementation wh
2d560 69 63 68 20 64 6f 65 73 20 6e 6f 74 20 63 61 72  ich does not car
2d570 65 20 77 68 61 74 20 74 65 78 74 0a 2a 2a 20 65  e what text.** e
2d580 6e 63 6f 64 69 6e 67 20 69 73 20 75 73 65 64 2c  ncoding is used,
2d590 20 74 68 65 6e 20 74 68 65 20 66 6f 75 72 74 68   then the fourth
2d5a0 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64   argument should
2d5b0 20 62 65 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d   be [SQLITE_ANY]
2d5c0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69  ..**.** ^(The fi
2d5d0 66 74 68 20 70 61 72 61 6d 65 74 65 72 20 69 73  fth parameter is
2d5e0 20 61 6e 20 61 72 62 69 74 72 61 72 79 20 70 6f   an arbitrary po
2d5f0 69 6e 74 65 72 2e 20 20 54 68 65 20 69 6d 70 6c  inter.  The impl
2d600 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68  ementation of th
2d610 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61  e.** function ca
2d620 6e 20 67 61 69 6e 20 61 63 63 65 73 73 20 74 6f  n gain access to
2d630 20 74 68 69 73 20 70 6f 69 6e 74 65 72 20 75 73   this pointer us
2d640 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 75 73 65  ing [sqlite3_use
2d650 72 5f 64 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a  r_data()].)^.**.
2d660 2a 2a 20 5e 54 68 65 20 73 69 78 74 68 2c 20 73  ** ^The sixth, s
2d670 65 76 65 6e 74 68 20 61 6e 64 20 65 69 67 68 74  eventh and eight
2d680 68 20 70 61 72 61 6d 65 74 65 72 73 2c 20 78 46  h parameters, xF
2d690 75 6e 63 2c 20 78 53 74 65 70 20 61 6e 64 20 78  unc, xStep and x
2d6a0 46 69 6e 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f  Final, are.** po
2d6b0 69 6e 74 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67  inters to C-lang
2d6c0 75 61 67 65 20 66 75 6e 63 74 69 6f 6e 73 20 74  uage functions t
2d6d0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2d6e0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2d6f0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 2e 20  r.** aggregate. 
2d700 5e 41 20 73 63 61 6c 61 72 20 53 51 4c 20 66 75  ^A scalar SQL fu
2d710 6e 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20  nction requires 
2d720 61 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  an implementatio
2d730 6e 20 6f 66 20 74 68 65 20 78 46 75 6e 63 0a 2a  n of the xFunc.*
2d740 2a 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b  * callback only;
2d750 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d   NULL pointers m
2d760 75 73 74 20 62 65 20 70 61 73 73 65 64 20 61 73  ust be passed as
2d770 20 74 68 65 20 78 53 74 65 70 20 61 6e 64 20 78   the xStep and x
2d780 46 69 6e 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74  Final.** paramet
2d790 65 72 73 2e 20 5e 41 6e 20 61 67 67 72 65 67 61  ers. ^An aggrega
2d7a0 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  te SQL function 
2d7b0 72 65 71 75 69 72 65 73 20 61 6e 20 69 6d 70 6c  requires an impl
2d7c0 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53  ementation of xS
2d7d0 74 65 70 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61  tep.** and xFina
2d7e0 6c 20 61 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74  l and NULL point
2d7f0 65 72 20 6d 75 73 74 20 62 65 20 70 61 73 73 65  er must be passe
2d800 64 20 66 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f  d for xFunc. ^To
2d810 20 64 65 6c 65 74 65 20 61 6e 20 65 78 69 73 74   delete an exist
2d820 69 6e 67 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74  ing.** SQL funct
2d830 69 6f 6e 20 6f 72 20 61 67 67 72 65 67 61 74 65  ion or aggregate
2d840 2c 20 70 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e  , pass NULL poin
2d850 74 65 72 73 20 66 6f 72 20 61 6c 6c 20 74 68 72  ters for all thr
2d860 65 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63  ee function.** c
2d870 61 6c 6c 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20  allbacks..**.** 
2d880 5e 28 49 66 20 74 68 65 20 6e 69 6e 74 68 20 70  ^(If the ninth p
2d890 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
2d8a0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2d8b0 69 6f 6e 5f 76 32 28 29 20 69 73 20 6e 6f 74 20  ion_v2() is not 
2d8c0 4e 55 4c 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74  NULL,.** then it
2d8d0 20 69 73 20 64 65 73 74 72 75 63 74 6f 72 20 66   is destructor f
2d8e0 6f 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  or the applicati
2d8f0 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e  on data pointer.
2d900 20 0a 2a 2a 20 54 68 65 20 64 65 73 74 72 75 63   .** The destruc
2d910 74 6f 72 20 69 73 20 69 6e 76 6f 6b 65 64 20 77  tor is invoked w
2d920 68 65 6e 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  hen the function
2d930 20 69 73 20 64 65 6c 65 74 65 64 2c 20 65 69 74   is deleted, eit
2d940 68 65 72 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20  her by being.** 
2d950 6f 76 65 72 6c 6f 61 64 65 64 20 6f 72 20 77 68  overloaded or wh
2d960 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
2d970 63 6f 6e 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65  connection close
2d980 73 2e 29 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73  s.)^.** ^The des
2d990 74 72 75 63 74 6f 72 20 69 73 20 61 6c 73 6f 20  tructor is also 
2d9a0 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20 63  invoked if the c
2d9b0 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  all to.** sqlite
2d9c0 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f  3_create_functio
2d9d0 6e 5f 76 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a  n_v2() fails..**
2d9e0 20 5e 57 68 65 6e 20 74 68 65 20 64 65 73 74 72   ^When the destr
2d9f0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f  uctor callback o
2da00 66 20 74 68 65 20 74 65 6e 74 68 20 70 61 72 61  f the tenth para
2da10 6d 65 74 65 72 20 69 73 20 69 6e 76 6f 6b 65 64  meter is invoked
2da20 2c 20 69 74 0a 2a 2a 20 69 73 20 70 61 73 73 65  , it.** is passe
2da30 64 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  d a single argum
2da40 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 63  ent which is a c
2da50 6f 70 79 20 6f 66 20 74 68 65 20 61 70 70 6c 69  opy of the appli
2da60 63 61 74 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20  cation data .** 
2da70 70 6f 69 6e 74 65 72 20 77 68 69 63 68 20 77 61  pointer which wa
2da80 73 20 74 68 65 20 66 69 66 74 68 20 70 61 72 61  s the fifth para
2da90 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2daa0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2dab0 5f 76 32 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74  _v2()..**.** ^It
2dac0 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f   is permitted to
2dad0 20 72 65 67 69 73 74 65 72 20 6d 75 6c 74 69 70   register multip
2dae0 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  le implementatio
2daf0 6e 73 20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a  ns of the same.*
2db00 2a 20 66 75 6e 63 74 69 6f 6e 73 20 77 69 74 68  * functions with
2db10 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 62   the same name b
2db20 75 74 20 77 69 74 68 20 65 69 74 68 65 72 20 64  ut with either d
2db30 69 66 66 65 72 69 6e 67 20 6e 75 6d 62 65 72 73  iffering numbers
2db40 20 6f 66 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73   of.** arguments
2db50 20 6f 72 20 64 69 66 66 65 72 69 6e 67 20 70 72   or differing pr
2db60 65 66 65 72 72 65 64 20 74 65 78 74 20 65 6e 63  eferred text enc
2db70 6f 64 69 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65  odings.  ^SQLite
2db80 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65   will use.** the
2db90 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2dba0 74 68 61 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c  that most closel
2dbb0 79 20 6d 61 74 63 68 65 73 20 74 68 65 20 77 61  y matches the wa
2dbc0 79 20 69 6e 20 77 68 69 63 68 20 74 68 65 0a 2a  y in which the.*
2dbd0 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69  * SQL function i
2dbe0 73 20 75 73 65 64 2e 20 20 5e 41 20 66 75 6e 63  s used.  ^A func
2dbf0 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2dc00 69 6f 6e 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e  ion with a non-n
2dc10 65 67 61 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20  egative.** nArg 
2dc20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 20 62  parameter is a b
2dc30 65 74 74 65 72 20 6d 61 74 63 68 20 74 68 61 6e  etter match than
2dc40 20 61 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c   a function impl
2dc50 65 6d 65 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a  ementation with.
2dc60 2a 2a 20 61 20 6e 65 67 61 74 69 76 65 20 6e 41  ** a negative nA
2dc70 72 67 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  rg.  ^A function
2dc80 20 77 68 65 72 65 20 74 68 65 20 70 72 65 66 65   where the prefe
2dc90 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2dca0 6e 67 0a 2a 2a 20 6d 61 74 63 68 65 73 20 74 68  ng.** matches th
2dcb0 65 20 64 61 74 61 62 61 73 65 20 65 6e 63 6f 64  e database encod
2dcc0 69 6e 67 20 69 73 20 61 20 62 65 74 74 65 72 0a  ing is a better.
2dcd0 2a 2a 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  ** match than a 
2dce0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2dcf0 68 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64  he encoding is d
2dd00 69 66 66 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e  ifferent.  .** ^
2dd10 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65  A function where
2dd20 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69   the encoding di
2dd30 66 66 65 72 65 6e 63 65 20 69 73 20 62 65 74 77  fference is betw
2dd40 65 65 6e 20 55 54 46 31 36 6c 65 20 61 6e 64 20  een UTF16le and 
2dd50 55 54 46 31 36 62 65 0a 2a 2a 20 69 73 20 61 20  UTF16be.** is a 
2dd60 63 6c 6f 73 65 72 20 6d 61 74 63 68 20 74 68 61  closer match tha
2dd70 6e 20 61 20 66 75 6e 63 74 69 6f 6e 20 77 68 65  n a function whe
2dd80 72 65 20 74 68 65 20 65 6e 63 6f 64 69 6e 67 20  re the encoding 
2dd90 64 69 66 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a  difference is.**
2dda0 20 62 65 74 77 65 65 6e 20 55 54 46 38 20 61 6e   between UTF8 an
2ddb0 64 20 55 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e  d UTF16..**.** ^
2ddc0 42 75 69 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f  Built-in functio
2ddd0 6e 73 20 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f  ns may be overlo
2dde0 61 64 65 64 20 62 79 20 6e 65 77 20 61 70 70 6c  aded by new appl
2ddf0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2de00 66 75 6e 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  functions..**.**
2de10 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e   ^An application
2de20 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2de30 6e 20 69 73 20 70 65 72 6d 69 74 74 65 64 20 74  n is permitted t
2de40 6f 20 63 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20  o call other.** 
2de50 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
2de60 73 2e 20 20 48 6f 77 65 76 65 72 2c 20 73 75 63  s.  However, suc
2de70 68 20 63 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74  h calls must not
2de80 0a 2a 2a 20 63 6c 6f 73 65 20 74 68 65 20 64 61  .** close the da
2de90 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
2dea0 6e 20 6e 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f  n nor finalize o
2deb0 72 20 72 65 73 65 74 20 74 68 65 20 70 72 65 70  r reset the prep
2dec0 61 72 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e  ared.** statemen
2ded0 74 20 69 6e 20 77 68 69 63 68 20 74 68 65 20 66  t in which the f
2dee0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2def0 6e 67 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ng..*/.int sqlit
2df00 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2df10 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  on(.  sqlite3 *d
2df20 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2df30 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2df40 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2df50 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2df60 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2df70 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2df80 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2df90 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2dfa0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2dfb0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2dfc0 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2dfd0 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2dfe0 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2dff0 5f 63 6f 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e  _context*).);.in
2e000 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
2e010 5f 66 75 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73  _function16(.  s
2e020 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f  qlite3 *db,.  co
2e030 6e 73 74 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74  nst void *zFunct
2e040 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e  ionName,.  int n
2e050 41 72 67 2c 0a 20 20 69 6e 74 20 65 54 65 78 74  Arg,.  int eText
2e060 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70  Rep,.  void *pAp
2e070 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 75 6e  p,.  void (*xFun
2e080 63 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  c)(sqlite3_conte
2e090 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f  xt*,int,sqlite3_
2e0a0 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64  value**),.  void
2e0b0 20 28 2a 78 53 74 65 70 29 28 73 71 6c 69 74 65   (*xStep)(sqlite
2e0c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2e0d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2e0e0 0a 20 20 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c  .  void (*xFinal
2e0f0 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  )(sqlite3_contex
2e100 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  t*).);.int sqlit
2e110 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e120 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
2e130 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68   *db,.  const ch
2e140 61 72 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d  ar *zFunctionNam
2e150 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20  e,.  int nArg,. 
2e160 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 0a 20   int eTextRep,. 
2e170 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20 20 76   void *pApp,.  v
2e180 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73 71 6c  oid (*xFunc)(sql
2e190 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2e1a0 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2e1b0 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 53 74  *),.  void (*xSt
2e1c0 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ep)(sqlite3_cont
2e1d0 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33  ext*,int,sqlite3
2e1e0 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69  _value**),.  voi
2e1f0 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69  d (*xFinal)(sqli
2e200 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20  te3_context*),. 
2e210 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
2e220 28 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a  (void*).);../*.*
2e230 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 78 74  * CAPI3REF: Text
2e240 20 45 6e 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a   Encodings.**.**
2e250 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 20   These constant 
2e260 64 65 66 69 6e 65 20 69 6e 74 65 67 65 72 20 63  define integer c
2e270 6f 64 65 73 20 74 68 61 74 20 72 65 70 72 65 73  odes that repres
2e280 65 6e 74 20 74 68 65 20 76 61 72 69 6f 75 73 0a  ent the various.
2e290 2a 2a 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67  ** text encoding
2e2a0 73 20 73 75 70 70 6f 72 74 65 64 20 62 79 20 53  s supported by S
2e2b0 51 4c 69 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e  QLite..*/.#defin
2e2c0 65 20 53 51 4c 49 54 45 5f 55 54 46 38 20 20 20  e SQLITE_UTF8   
2e2d0 20 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e          1.#defin
2e2e0 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45  e SQLITE_UTF16LE
2e2f0 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
2e300 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45  e SQLITE_UTF16BE
2e310 20 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e          3.#defin
2e320 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 20 20  e SQLITE_UTF16  
2e330 20 20 20 20 20 20 20 20 34 20 20 20 20 2f 2a 20          4    /* 
2e340 55 73 65 20 6e 61 74 69 76 65 20 62 79 74 65 20  Use native byte 
2e350 6f 72 64 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65  order */.#define
2e360 20 53 51 4c 49 54 45 5f 41 4e 59 20 20 20 20 20   SQLITE_ANY     
2e370 20 20 20 20 20 20 20 35 20 20 20 20 2f 2a 20 73         5    /* s
2e380 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2e390 6e 63 74 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23  nction only */.#
2e3a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 54  define SQLITE_UT
2e3b0 46 31 36 5f 41 4c 49 47 4e 45 44 20 20 38 20 20  F16_ALIGNED  8  
2e3c0 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 63 72 65    /* sqlite3_cre
2e3d0 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e  ate_collation on
2e3e0 6c 79 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ly */../*.** CAP
2e3f0 49 33 52 45 46 3a 20 44 65 70 72 65 63 61 74 65  I3REF: Deprecate
2e400 64 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44  d Functions.** D
2e410 45 50 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20  EPRECATED.**.** 
2e420 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  These functions 
2e430 61 72 65 20 5b 64 65 70 72 65 63 61 74 65 64 5d  are [deprecated]
2e440 2e 20 20 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d  .  In order to m
2e450 61 69 6e 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77  aintain.** backw
2e460 61 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69  ards compatibili
2e470 74 79 20 77 69 74 68 20 6f 6c 64 65 72 20 63 6f  ty with older co
2e480 64 65 2c 20 74 68 65 73 65 20 66 75 6e 63 74 69  de, these functi
2e490 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a  ons continue .**
2e4a0 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74 65 64   to be supported
2e4b0 2e 20 20 48 6f 77 65 76 65 72 2c 20 6e 65 77 20  .  However, new 
2e4c0 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f  applications sho
2e4d0 75 6c 64 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65  uld avoid.** the
2e4e0 20 75 73 65 20 6f 66 20 74 68 65 73 65 20 66 75   use of these fu
2e4f0 6e 63 74 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c  nctions.  To hel
2e500 70 20 65 6e 63 6f 75 72 61 67 65 20 70 65 6f 70  p encourage peop
2e510 6c 65 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75  le to avoid.** u
2e520 73 69 6e 67 20 74 68 65 73 65 20 66 75 6e 63 74  sing these funct
2e530 69 6f 6e 73 2c 20 77 65 20 61 72 65 20 6e 6f 74  ions, we are not
2e540 20 67 6f 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79   going to tell y
2e550 6f 75 20 77 68 61 74 20 74 68 65 79 20 64 6f 2e  ou what they do.
2e560 0a 2a 2f 0a 23 69 66 6e 64 65 66 20 53 51 4c 49  .*/.#ifndef SQLI
2e570 54 45 5f 4f 4d 49 54 5f 44 45 50 52 45 43 41 54  TE_OMIT_DEPRECAT
2e580 45 44 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43  ED.SQLITE_DEPREC
2e590 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33  ATED int sqlite3
2e5a0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 75 6e 74  _aggregate_count
2e5b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2e5c0 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  *);.SQLITE_DEPRE
2e5d0 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65  CATED int sqlite
2e5e0 33 5f 65 78 70 69 72 65 64 28 73 71 6c 69 74 65  3_expired(sqlite
2e5f0 33 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45  3_stmt*);.SQLITE
2e600 5f 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20  _DEPRECATED int 
2e610 73 71 6c 69 74 65 33 5f 74 72 61 6e 73 66 65 72  sqlite3_transfer
2e620 5f 62 69 6e 64 69 6e 67 73 28 73 71 6c 69 74 65  _bindings(sqlite
2e630 33 5f 73 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33  3_stmt*, sqlite3
2e640 5f 73 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f  _stmt*);.SQLITE_
2e650 44 45 50 52 45 43 41 54 45 44 20 69 6e 74 20 73  DEPRECATED int s
2e660 71 6c 69 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65  qlite3_global_re
2e670 63 6f 76 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c  cover(void);.SQL
2e680 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20 76  ITE_DEPRECATED v
2e690 6f 69 64 20 73 71 6c 69 74 65 33 5f 74 68 72 65  oid sqlite3_thre
2e6a0 61 64 5f 63 6c 65 61 6e 75 70 28 76 6f 69 64 29  ad_cleanup(void)
2e6b0 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41  ;.SQLITE_DEPRECA
2e6c0 54 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f  TED int sqlite3_
2e6d0 6d 65 6d 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69  memory_alarm(voi
2e6e0 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74  d(*)(void*,sqlit
2e6f0 65 33 5f 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f  e3_int64,int),vo
2e700 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36  id*,sqlite3_int6
2e710 34 29 3b 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a  4);.#endif../*.*
2e720 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
2e730 69 6e 69 6e 67 20 53 51 4c 20 46 75 6e 63 74 69  ining SQL Functi
2e740 6f 6e 20 50 61 72 61 6d 65 74 65 72 20 56 61 6c  on Parameter Val
2e750 75 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d  ues.**.** The C-
2e760 6c 61 6e 67 75 61 67 65 20 69 6d 70 6c 65 6d 65  language impleme
2e770 6e 74 61 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66  ntation of SQL f
2e780 75 6e 63 74 69 6f 6e 73 20 61 6e 64 20 61 67 67  unctions and agg
2e790 72 65 67 61 74 65 73 20 75 73 65 73 0a 2a 2a 20  regates uses.** 
2e7a0 74 68 69 73 20 73 65 74 20 6f 66 20 69 6e 74 65  this set of inte
2e7b0 72 66 61 63 65 20 72 6f 75 74 69 6e 65 73 20 74  rface routines t
2e7c0 6f 20 61 63 63 65 73 73 20 74 68 65 20 70 61 72  o access the par
2e7d0 61 6d 65 74 65 72 20 76 61 6c 75 65 73 20 6f 6e  ameter values on
2e7e0 0a 2a 2a 20 74 68 65 20 66 75 6e 63 74 69 6f 6e  .** the function
2e7f0 20 6f 72 20 61 67 67 72 65 67 61 74 65 2e 0a 2a   or aggregate..*
2e800 2a 0a 2a 2a 20 54 68 65 20 78 46 75 6e 63 20 28  *.** The xFunc (
2e810 66 6f 72 20 73 63 61 6c 61 72 20 66 75 6e 63 74  for scalar funct
2e820 69 6f 6e 73 29 20 6f 72 20 78 53 74 65 70 20 28  ions) or xStep (
2e830 66 6f 72 20 61 67 67 72 65 67 61 74 65 73 29 20  for aggregates) 
2e840 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
2e850 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e860 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64  _function()] and
2e870 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2e880 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a  _function16()].*
2e890 2a 20 64 65 66 69 6e 65 20 63 61 6c 6c 62 61 63  * define callbac
2e8a0 6b 73 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e  ks that implemen
2e8b0 74 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  t the SQL functi
2e8c0 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74  ons and aggregat
2e8d0 65 73 2e 0a 2a 2a 20 54 68 65 20 33 72 64 20 70  es..** The 3rd p
2e8e0 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 73  arameter to thes
2e8f0 65 20 63 61 6c 6c 62 61 63 6b 73 20 69 73 20 61  e callbacks is a
2e900 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74  n array of point
2e910 65 72 73 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65  ers to.** [prote
2e920 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
2e930 75 65 5d 20 6f 62 6a 65 63 74 73 2e 20 20 54 68  ue] objects.  Th
2e940 65 72 65 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69  ere is one [sqli
2e950 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2e960 74 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61  t for.** each pa
2e970 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 53  rameter to the S
2e980 51 4c 20 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68  QL function.  Th
2e990 65 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65  ese routines are
2e9a0 20 75 73 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72   used to.** extr
2e9b0 61 63 74 20 76 61 6c 75 65 73 20 66 72 6f 6d 20  act values from 
2e9c0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  the [sqlite3_val
2e9d0 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a  ue] objects..**.
2e9e0 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
2e9f0 73 20 77 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68  s work only with
2ea00 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
2ea10 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
2ea20 74 73 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ts..** Any attem
2ea30 70 74 20 74 6f 20 75 73 65 20 74 68 65 73 65 20  pt to use these 
2ea40 72 6f 75 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b  routines on an [
2ea50 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  unprotected sqli
2ea60 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62  te3_value].** ob
2ea70 6a 65 63 74 20 72 65 73 75 6c 74 73 20 69 6e 20  ject results in 
2ea80 75 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69  undefined behavi
2ea90 6f 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65  or..**.** ^These
2eaa0 20 72 6f 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a   routines work j
2eab0 75 73 74 20 6c 69 6b 65 20 74 68 65 20 63 6f 72  ust like the cor
2eac0 72 65 73 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75  responding [colu
2ead0 6d 6e 20 61 63 63 65 73 73 20 66 75 6e 63 74 69  mn access functi
2eae0 6f 6e 73 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74  ons].** except t
2eaf0 68 61 74 20 20 74 68 65 73 65 20 72 6f 75 74 69  hat  these routi
2eb00 6e 65 73 20 74 61 6b 65 20 61 20 73 69 6e 67 6c  nes take a singl
2eb10 65 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  e [protected sql
2eb20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2eb30 63 74 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e  ct.** pointer in
2eb40 73 74 65 61 64 20 6f 66 20 61 20 5b 73 71 6c 69  stead of a [sqli
2eb50 74 65 33 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74  te3_stmt*] point
2eb60 65 72 20 61 6e 64 20 61 6e 20 69 6e 74 65 67 65  er and an intege
2eb70 72 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  r column number.
2eb80 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2eb90 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2eba0 28 29 20 69 6e 74 65 72 66 61 63 65 20 65 78 74  () interface ext
2ebb0 72 61 63 74 73 20 61 20 55 54 46 2d 31 36 20 73  racts a UTF-16 s
2ebc0 74 72 69 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20  tring.** in the 
2ebd0 6e 61 74 69 76 65 20 62 79 74 65 2d 6f 72 64 65  native byte-orde
2ebe0 72 20 6f 66 20 74 68 65 20 68 6f 73 74 20 6d 61  r of the host ma
2ebf0 63 68 69 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20  chine.  ^The.** 
2ec00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2ec10 78 74 31 36 62 65 28 29 20 61 6e 64 20 73 71 6c  xt16be() and sql
2ec20 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2ec30 36 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 73  6le() interfaces
2ec40 0a 2a 2a 20 65 78 74 72 61 63 74 20 55 54 46 2d  .** extract UTF-
2ec50 31 36 20 73 74 72 69 6e 67 73 20 61 73 20 62 69  16 strings as bi
2ec60 67 2d 65 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74  g-endian and lit
2ec70 74 6c 65 2d 65 6e 64 69 61 6e 20 72 65 73 70 65  tle-endian respe
2ec80 63 74 69 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e  ctively..**.** ^
2ec90 28 54 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  (The sqlite3_val
2eca0 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28  ue_numeric_type(
2ecb0 29 20 69 6e 74 65 72 66 61 63 65 20 61 74 74 65  ) interface atte
2ecc0 6d 70 74 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a  mpts to apply.**
2ecd0 20 6e 75 6d 65 72 69 63 20 61 66 66 69 6e 69 74   numeric affinit
2ece0 79 20 74 6f 20 74 68 65 20 76 61 6c 75 65 2e 20  y to the value. 
2ecf0 20 54 68 69 73 20 6d 65 61 6e 73 20 74 68 61 74   This means that
2ed00 20 61 6e 20 61 74 74 65 6d 70 74 20 69 73 0a 2a   an attempt is.*
2ed10 2a 20 6d 61 64 65 20 74 6f 20 63 6f 6e 76 65 72  * made to conver
2ed20 74 20 74 68 65 20 76 61 6c 75 65 20 74 6f 20 61  t the value to a
2ed30 6e 20 69 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f  n integer or flo
2ed40 61 74 69 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66  ating point.  If
2ed50 0a 2a 2a 20 73 75 63 68 20 61 20 63 6f 6e 76 65  .** such a conve
2ed60 72 73 69 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c  rsion is possibl
2ed70 65 20 77 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f  e without loss o
2ed80 66 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69  f information (i
2ed90 6e 20 6f 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73  n other.** words
2eda0 2c 20 69 66 20 74 68 65 20 76 61 6c 75 65 20 69  , if the value i
2edb0 73 20 61 20 73 74 72 69 6e 67 20 74 68 61 74 20  s a string that 
2edc0 6c 6f 6f 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d  looks like a num
2edd0 62 65 72 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ber).** then the
2ede0 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 70   conversion is p
2edf0 65 72 66 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72  erformed.  Other
2ee00 77 69 73 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69  wise no conversi
2ee10 6f 6e 20 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68  on occurs..** Th
2ee20 65 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 47 45  e [SQLITE_INTEGE
2ee30 52 20 7c 20 64 61 74 61 74 79 70 65 5d 20 61 66  R | datatype] af
2ee40 74 65 72 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69  ter conversion i
2ee50 73 20 72 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a  s returned.)^.**
2ee60 0a 2a 2a 20 50 6c 65 61 73 65 20 70 61 79 20 70  .** Please pay p
2ee70 61 72 74 69 63 75 6c 61 72 20 61 74 74 65 6e 74  articular attent
2ee80 69 6f 6e 20 74 6f 20 74 68 65 20 66 61 63 74 20  ion to the fact 
2ee90 74 68 61 74 20 74 68 65 20 70 6f 69 6e 74 65 72  that the pointer
2eea0 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f   returned.** fro
2eeb0 6d 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  m [sqlite3_value
2eec0 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74  _blob()], [sqlit
2eed0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d  e3_value_text()]
2eee0 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  , or.** [sqlite3
2eef0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 5d  _value_text16()]
2ef00 20 63 61 6e 20 62 65 20 69 6e 76 61 6c 69 64 61   can be invalida
2ef10 74 65 64 20 62 79 20 61 20 73 75 62 73 65 71 75  ted by a subsequ
2ef20 65 6e 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  ent call to.** [
2ef30 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79  sqlite3_value_by
2ef40 74 65 73 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  tes()], [sqlite3
2ef50 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28 29  _value_bytes16()
2ef60 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75  ], [sqlite3_valu
2ef70 65 5f 74 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72  e_text()],.** or
2ef80 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
2ef90 74 65 78 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a  text16()]..**.**
2efa0 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
2efb0 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2efc0 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2efd0 65 61 64 20 61 73 0a 2a 2a 20 74 68 65 20 53 51  ead as.** the SQ
2efe0 4c 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  L function that 
2eff0 73 75 70 70 6c 69 65 64 20 74 68 65 20 5b 73 71  supplied the [sq
2f000 6c 69 74 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61  lite3_value*] pa
2f010 72 61 6d 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e  rameters..*/.con
2f020 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2f030 5f 76 61 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69  _value_blob(sqli
2f040 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74  te3_value*);.int
2f050 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62   sqlite3_value_b
2f060 79 74 65 73 28 73 71 6c 69 74 65 33 5f 76 61 6c  ytes(sqlite3_val
2f070 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  ue*);.int sqlite
2f080 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 31 36 28  3_value_bytes16(
2f090 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f0a0 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65 33 5f  .double sqlite3_
2f0b0 76 61 6c 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c  value_double(sql
2f0c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e  ite3_value*);.in
2f0d0 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  t sqlite3_value_
2f0e0 69 6e 74 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  int(sqlite3_valu
2f0f0 65 2a 29 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74  e*);.sqlite3_int
2f100 36 34 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64 sqlite3_value
2f110 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f 76  _int64(sqlite3_v
2f120 61 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e  alue*);.const un
2f130 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2f140 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 28  ite3_value_text(
2f150 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2f160 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2f170 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2f180 36 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  6(sqlite3_value*
2f190 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2f1a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2f1b0 74 31 36 6c 65 28 73 71 6c 69 74 65 33 5f 76 61  t16le(sqlite3_va
2f1c0 6c 75 65 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  lue*);.const voi
2f1d0 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  d *sqlite3_value
2f1e0 5f 74 65 78 74 31 36 62 65 28 73 71 6c 69 74 65  _text16be(sqlite
2f1f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2f200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70  qlite3_value_typ
2f210 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f220 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2f230 61 6c 75 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70  alue_numeric_typ
2f240 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2f250 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2f260 45 46 3a 20 4f 62 74 61 69 6e 20 41 67 67 72 65  EF: Obtain Aggre
2f270 67 61 74 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f  gate Function Co
2f280 6e 74 65 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c  ntext.**.** Impl
2f290 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61  ementations of a
2f2a0 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75 6e  ggregate SQL fun
2f2b0 63 74 69 6f 6e 73 20 75 73 65 20 74 68 69 73 0a  ctions use this.
2f2c0 2a 2a 20 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c  ** routine to al
2f2d0 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f  locate memory fo
2f2e0 72 20 73 74 6f 72 69 6e 67 20 74 68 65 69 72 20  r storing their 
2f2f0 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  state..**.** ^Th
2f300 65 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 65  e first time the
2f310 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61   sqlite3_aggrega
2f320 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20  te_context(C,N) 
2f330 72 6f 75 74 69 6e 65 20 69 73 20 63 61 6c 6c 65  routine is calle
2f340 64 20 0a 2a 2a 20 66 6f 72 20 61 20 70 61 72 74  d .** for a part
2f350 69 63 75 6c 61 72 20 61 67 67 72 65 67 61 74 65  icular aggregate
2f360 20 66 75 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74   function, SQLit
2f370 65 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e  e.** allocates N
2f380 20 6f 66 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f   of memory, zero
2f390 65 73 20 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f  es out that memo
2f3a0 72 79 2c 20 61 6e 64 20 72 65 74 75 72 6e 73 20  ry, and returns 
2f3b0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
2f3c0 74 68 65 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20  the new memory. 
2f3d0 5e 4f 6e 20 73 65 63 6f 6e 64 20 61 6e 64 20 73  ^On second and s
2f3e0 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73 20  ubsequent calls 
2f3f0 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67  to.** sqlite3_ag
2f400 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2f410 29 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 61  ) for the same a
2f420 67 67 72 65 67 61 74 65 20 66 75 6e 63 74 69 6f  ggregate functio
2f430 6e 20 69 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74  n instance,.** t
2f440 68 65 20 73 61 6d 65 20 62 75 66 66 65 72 20 69  he same buffer i
2f450 73 20 72 65 74 75 72 6e 65 64 2e 20 20 53 71 6c  s returned.  Sql
2f460 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2f470 6f 6e 74 65 78 74 28 29 20 69 73 20 6e 6f 72 6d  ontext() is norm
2f480 61 6c 6c 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f  ally.** called o
2f490 6e 63 65 20 66 6f 72 20 65 61 63 68 20 69 6e 76  nce for each inv
2f4a0 6f 63 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 78  ocation of the x
2f4b0 53 74 65 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e  Step callback an
2f4c0 64 20 74 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61  d then one.** la
2f4d0 73 74 20 74 69 6d 65 20 77 68 65 6e 20 74 68 65  st time when the
2f4e0 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2f4f0 20 69 73 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28   is invoked.  ^(
2f500 57 68 65 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74  When no rows mat
2f510 63 68 0a 2a 2a 20 61 6e 20 61 67 67 72 65 67 61  ch.** an aggrega
2f520 74 65 20 71 75 65 72 79 2c 20 74 68 65 20 78 53  te query, the xS
2f530 74 65 70 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f  tep() callback o
2f540 66 20 74 68 65 20 61 67 67 72 65 67 61 74 65 20  f the aggregate 
2f550 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c  function.** impl
2f560 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65  ementation is ne
2f570 76 65 72 20 63 61 6c 6c 65 64 20 61 6e 64 20 78  ver called and x
2f580 46 69 6e 61 6c 28 29 20 69 73 20 63 61 6c 6c 65  Final() is calle
2f590 64 20 65 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a  d exactly once..
2f5a0 2a 2a 20 49 6e 20 74 68 6f 73 65 20 63 61 73 65  ** In those case
2f5b0 73 2c 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  s, sqlite3_aggre
2f5c0 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d  gate_context() m
2f5d0 69 67 68 74 20 62 65 20 63 61 6c 6c 65 64 20 66  ight be called f
2f5e0 6f 72 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20  or the.** first 
2f5f0 74 69 6d 65 20 66 72 6f 6d 20 77 69 74 68 69 6e  time from within
2f600 20 78 46 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a   xFinal().)^.**.
2f610 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2f620 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2f630 74 28 43 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72  t(C,N) routine r
2f640 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2f650 69 6e 74 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a  inter if N is.**
2f660 20 6c 65 73 73 20 74 68 61 6e 20 6f 72 20 65 71   less than or eq
2f670 75 61 6c 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69  ual to zero or i
2f680 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
2f690 61 74 65 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ate error occurs
2f6a0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d  ..**.** ^(The am
2f6b0 6f 75 6e 74 20 6f 66 20 73 70 61 63 65 20 61 6c  ount of space al
2f6c0 6c 6f 63 61 74 65 64 20 62 79 20 73 71 6c 69 74  located by sqlit
2f6d0 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2f6e0 74 65 78 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20  text(C,N) is.** 
2f6f0 64 65 74 65 72 6d 69 6e 65 64 20 62 79 20 74 68  determined by th
2f700 65 20 4e 20 70 61 72 61 6d 65 74 65 72 20 6f 6e  e N parameter on
2f710 20 66 69 72 73 74 20 73 75 63 63 65 73 73 66 75   first successfu
2f720 6c 20 63 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e  l call.  Changin
2f730 67 20 74 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f  g the.** value o
2f740 66 20 4e 20 69 6e 20 73 75 62 73 65 71 75 65 6e  f N in subsequen
2f750 74 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65  t call to sqlite
2f760 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2f770 65 78 74 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20  ext() within.** 
2f780 74 68 65 20 73 61 6d 65 20 61 67 67 72 65 67 61  the same aggrega
2f790 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74  te function inst
2f7a0 61 6e 63 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65  ance will not re
2f7b0 73 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a  size the memory.
2f7c0 2a 2a 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e  ** allocation.)^
2f7d0 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61  .**.** ^SQLite a
2f7e0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 66 72 65  utomatically fre
2f7f0 65 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c  es the memory al
2f800 6c 6f 63 61 74 65 64 20 62 79 20 0a 2a 2a 20 73  located by .** s
2f810 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2f820 5f 63 6f 6e 74 65 78 74 28 29 20 77 68 65 6e 20  _context() when 
2f830 74 68 65 20 61 67 67 72 65 67 61 74 65 20 71 75  the aggregate qu
2f840 65 72 79 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a  ery concludes..*
2f850 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20 70  *.** The first p
2f860 61 72 61 6d 65 74 65 72 20 6d 75 73 74 20 62 65  arameter must be
2f870 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
2f880 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  * [sqlite3_conte
2f890 78 74 20 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f  xt | SQL functio
2f8a0 6e 20 63 6f 6e 74 65 78 74 5d 20 74 68 61 74 20  n context] that 
2f8b0 69 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72  is the first par
2f8c0 61 6d 65 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ameter.** to the
2f8d0 20 78 53 74 65 70 20 6f 72 20 78 46 69 6e 61 6c   xStep or xFinal
2f8e0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
2f8f0 65 20 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74  e that implement
2f900 73 20 74 68 65 20 61 67 67 72 65 67 61 74 65 0a  s the aggregate.
2f910 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a  ** function..**.
2f920 2a 2a 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20  ** This routine 
2f930 6d 75 73 74 20 62 65 20 63 61 6c 6c 65 64 20 66  must be called f
2f940 72 6f 6d 20 74 68 65 20 73 61 6d 65 20 74 68 72  rom the same thr
2f950 65 61 64 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20  ead in which.** 
2f960 74 68 65 20 61 67 67 72 65 67 61 74 65 20 53 51  the aggregate SQ
2f970 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75  L function is ru
2f980 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a  nning..*/.void *
2f990 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2f9a0 65 5f 63 6f 6e 74 65 78 74 28 73 71 6c 69 74 65  e_context(sqlite
2f9b0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20  3_context*, int 
2f9c0 6e 42 79 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  nBytes);../*.** 
2f9d0 43 41 50 49 33 52 45 46 3a 20 55 73 65 72 20 44  CAPI3REF: User D
2f9e0 61 74 61 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ata For Function
2f9f0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2fa00 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
2fa10 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
2fa20 6e 73 20 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20  ns a copy of.** 
2fa30 74 68 65 20 70 6f 69 6e 74 65 72 20 74 68 61 74  the pointer that
2fa40 20 77 61 73 20 74 68 65 20 70 55 73 65 72 44 61   was the pUserDa
2fa50 74 61 20 70 61 72 61 6d 65 74 65 72 20 28 74 68  ta parameter (th
2fa60 65 20 35 74 68 20 70 61 72 61 6d 65 74 65 72 29  e 5th parameter)
2fa70 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71 6c 69  .** of the [sqli
2fa80 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2fa90 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73  ion()].** and [s
2faa0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2fab0 6e 63 74 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74  nction16()] rout
2fac0 69 6e 65 73 20 74 68 61 74 20 6f 72 69 67 69 6e  ines that origin
2fad0 61 6c 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72  ally.** register
2fae0 65 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ed the applicati
2faf0 6f 6e 20 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on defined funct
2fb00 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ion..**.** This 
2fb10 72 6f 75 74 69 6e 65 20 6d 75 73 74 20 62 65 20  routine must be 
2fb20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2fb30 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2fb40 68 69 63 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c  hich.** the appl
2fb50 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2fb60 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2fb70 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2fb80 6c 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28  lite3_user_data(
2fb90 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2fba0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2fbb0 45 46 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e  EF: Database Con
2fbc0 6e 65 63 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63  nection For Func
2fbd0 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tions.**.** ^The
2fbe0 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74   sqlite3_context
2fbf0 5f 64 62 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74  _db_handle() int
2fc00 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2fc10 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2fc20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 5b  pointer to the [
2fc30 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
2fc40 69 6f 6e 5d 20 28 74 68 65 20 31 73 74 20 70 61  ion] (the 1st pa
2fc50 72 61 6d 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74  rameter).** of t
2fc60 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  he [sqlite3_crea
2fc70 74 65 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a  te_function()].*
2fc80 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63  * and [sqlite3_c
2fc90 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36  reate_function16
2fca0 28 29 5d 20 72 6f 75 74 69 6e 65 73 20 74 68 61  ()] routines tha
2fcb0 74 20 6f 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20  t originally.** 
2fcc0 72 65 67 69 73 74 65 72 65 64 20 74 68 65 20 61  registered the a
2fcd0 70 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e  pplication defin
2fce0 65 64 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a  ed function..*/.
2fcf0 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65 33  sqlite3 *sqlite3
2fd00 5f 63 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64  _context_db_hand
2fd10 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  le(sqlite3_conte
2fd20 78 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  xt*);../*.** CAP
2fd30 49 33 52 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20  I3REF: Function 
2fd40 41 75 78 69 6c 69 61 72 79 20 44 61 74 61 0a 2a  Auxiliary Data.*
2fd50 2a 0a 2a 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69  *.** The followi
2fd60 6e 67 20 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73  ng two functions
2fd70 20 6d 61 79 20 62 65 20 75 73 65 64 20 62 79 20   may be used by 
2fd80 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2fd90 69 6f 6e 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63  ions to.** assoc
2fda0 69 61 74 65 20 6d 65 74 61 64 61 74 61 20 77 69  iate metadata wi
2fdb0 74 68 20 61 72 67 75 6d 65 6e 74 20 76 61 6c 75  th argument valu
2fdc0 65 73 2e 20 49 66 20 74 68 65 20 73 61 6d 65 20  es. If the same 
2fdd0 76 61 6c 75 65 20 69 73 20 70 61 73 73 65 64 20  value is passed 
2fde0 74 6f 0a 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69  to.** multiple i
2fdf0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
2fe00 65 20 73 61 6d 65 20 53 51 4c 20 66 75 6e 63 74  e same SQL funct
2fe10 69 6f 6e 20 64 75 72 69 6e 67 20 71 75 65 72 79  ion during query
2fe20 20 65 78 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65   execution, unde
2fe30 72 0a 2a 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d  r.** some circum
2fe40 73 74 61 6e 63 65 73 20 74 68 65 20 61 73 73 6f  stances the asso
2fe50 63 69 61 74 65 64 20 6d 65 74 61 64 61 74 61 20  ciated metadata 
2fe60 6d 61 79 20 62 65 20 70 72 65 73 65 72 76 65 64  may be preserved
2fe70 2e 20 54 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65  . This may.** be
2fe80 20 75 73 65 64 2c 20 66 6f 72 20 65 78 61 6d 70   used, for examp
2fe90 6c 65 2c 20 74 6f 20 61 64 64 20 61 20 72 65 67  le, to add a reg
2fea0 75 6c 61 72 2d 65 78 70 72 65 73 73 69 6f 6e 20  ular-expression 
2feb0 6d 61 74 63 68 69 6e 67 20 73 63 61 6c 61 72 0a  matching scalar.
2fec0 2a 2a 20 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65  ** function. The
2fed0 20 63 6f 6d 70 69 6c 65 64 20 76 65 72 73 69 6f   compiled versio
2fee0 6e 20 6f 66 20 74 68 65 20 72 65 67 75 6c 61 72  n of the regular
2fef0 20 65 78 70 72 65 73 73 69 6f 6e 20 69 73 20 73   expression is s
2ff00 74 6f 72 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61  tored as.** meta
2ff10 64 61 74 61 20 61 73 73 6f 63 69 61 74 65 64 20  data associated 
2ff20 77 69 74 68 20 74 68 65 20 53 51 4c 20 76 61 6c  with the SQL val
2ff30 75 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  ue passed as the
2ff40 20 72 65 67 75 6c 61 72 20 65 78 70 72 65 73 73   regular express
2ff50 69 6f 6e 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20  ion.** pattern. 
2ff60 20 54 68 65 20 63 6f 6d 70 69 6c 65 64 20 72 65   The compiled re
2ff70 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2ff80 20 63 61 6e 20 62 65 20 72 65 75 73 65 64 20 6f   can be reused o
2ff90 6e 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e  n multiple.** in
2ffa0 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65  vocations of the
2ffb0 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73   same function s
2ffc0 6f 20 74 68 61 74 20 74 68 65 20 6f 72 69 67 69  o that the origi
2ffd0 6e 61 6c 20 70 61 74 74 65 72 6e 20 73 74 72 69  nal pattern stri
2ffe0 6e 67 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e  ng.** does not n
2fff0 65 65 64 20 74 6f 20 62 65 20 72 65 63 6f 6d 70  eed to be recomp
30000 69 6c 65 64 20 6f 6e 20 65 61 63 68 20 69 6e 76  iled on each inv
30010 6f 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  ocation..**.** ^
30020 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
30030 61 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66  auxdata() interf
30040 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
30050 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6d 65 74  inter to the met
30060 61 64 61 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61  adata.** associa
30070 74 65 64 20 62 79 20 74 68 65 20 73 71 6c 69 74  ted by the sqlit
30080 65 33 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29  e3_set_auxdata()
30090 20 66 75 6e 63 74 69 6f 6e 20 77 69 74 68 20 74   function with t
300a0 68 65 20 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a  he Nth argument.
300b0 2a 2a 20 76 61 6c 75 65 20 74 6f 20 74 68 65 20  ** value to the 
300c0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
300d0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49  ned function. ^I
300e0 66 20 6e 6f 20 6d 65 74 61 64 61 74 61 20 68 61  f no metadata ha
300f0 73 20 62 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62  s been ever.** b
30100 65 65 6e 20 73 65 74 20 66 6f 72 20 74 68 65 20  een set for the 
30110 4e 74 68 20 61 72 67 75 6d 65 6e 74 20 6f 66 20  Nth argument of 
30120 74 68 65 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72  the function, or
30130 20 69 66 20 74 68 65 20 63 6f 72 72 65 73 70 6f   if the correspo
30140 6e 64 69 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f  nding.** functio
30150 6e 20 70 61 72 61 6d 65 74 65 72 20 68 61 73 20  n parameter has 
30160 63 68 61 6e 67 65 64 20 73 69 6e 63 65 20 74 68  changed since th
30170 65 20 6d 65 74 61 2d 64 61 74 61 20 77 61 73 20  e meta-data was 
30180 73 65 74 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c  set,.** then sql
30190 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74 61  ite3_get_auxdata
301a0 28 29 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c  () returns a NUL
301b0 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
301c0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 65   ^The sqlite3_se
301d0 74 5f 61 75 78 64 61 74 61 28 29 20 69 6e 74 65  t_auxdata() inte
301e0 72 66 61 63 65 20 73 61 76 65 73 20 74 68 65 20  rface saves the 
301f0 6d 65 74 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e  metadata.** poin
30200 74 65 64 20 74 6f 20 62 79 20 69 74 73 20 33 72  ted to by its 3r
30210 64 20 70 61 72 61 6d 65 74 65 72 20 61 73 20 74  d parameter as t
30220 68 65 20 6d 65 74 61 64 61 74 61 20 66 6f 72 20  he metadata for 
30230 74 68 65 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75  the N-th.** argu
30240 6d 65 6e 74 20 6f 66 20 74 68 65 20 61 70 70 6c  ment of the appl
30250 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30260 66 75 6e 63 74 69 6f 6e 2e 20 20 53 75 62 73 65  function.  Subse
30270 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
30280 6f 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75  o sqlite3_get_au
30290 78 64 61 74 61 28 29 20 6d 69 67 68 74 20 72 65  xdata() might re
302a0 74 75 72 6e 20 74 68 69 73 20 64 61 74 61 2c 20  turn this data, 
302b0 69 66 20 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74  if it has.** not
302c0 20 62 65 65 6e 20 64 65 73 74 72 6f 79 65 64 2e   been destroyed.
302d0 0a 2a 2a 20 5e 49 66 20 69 74 20 69 73 20 6e 6f  .** ^If it is no
302e0 74 20 4e 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77  t NULL, SQLite w
302f0 69 6c 6c 20 69 6e 76 6f 6b 65 20 74 68 65 20 64  ill invoke the d
30300 65 73 74 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e  estructor.** fun
30310 63 74 69 6f 6e 20 67 69 76 65 6e 20 62 79 20 74  ction given by t
30320 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
30330 20 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f   to sqlite3_set_
30340 61 75 78 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20  auxdata() on.** 
30350 74 68 65 20 6d 65 74 61 64 61 74 61 20 77 68 65  the metadata whe
30360 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
30370 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 70 61 72  ing function par
30380 61 6d 65 74 65 72 20 63 68 61 6e 67 65 73 0a 2a  ameter changes.*
30390 2a 20 6f 72 20 77 68 65 6e 20 74 68 65 20 53 51  * or when the SQ
303a0 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70  L statement comp
303b0 6c 65 74 65 73 2c 20 77 68 69 63 68 65 76 65 72  letes, whichever
303c0 20 63 6f 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a   comes first..**
303d0 0a 2a 2a 20 53 51 4c 69 74 65 20 69 73 20 66 72  .** SQLite is fr
303e0 65 65 20 74 6f 20 63 61 6c 6c 20 74 68 65 20 64  ee to call the d
303f0 65 73 74 72 75 63 74 6f 72 20 61 6e 64 20 64 72  estructor and dr
30400 6f 70 20 6d 65 74 61 64 61 74 61 20 6f 6e 20 61  op metadata on a
30410 6e 79 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20  ny.** parameter 
30420 6f 66 20 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20  of any function 
30430 61 74 20 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54  at any time.  ^T
30440 68 65 20 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65  he only guarante
30450 65 20 69 73 20 74 68 61 74 0a 2a 2a 20 74 68 65  e is that.** the
30460 20 64 65 73 74 72 75 63 74 6f 72 20 77 69 6c 6c   destructor will
30470 20 62 65 20 63 61 6c 6c 65 64 20 62 65 66 6f 72   be called befor
30480 65 20 74 68 65 20 6d 65 74 61 64 61 74 61 20 69  e the metadata i
30490 73 20 64 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a  s dropped..**.**
304a0 20 5e 28 49 6e 20 70 72 61 63 74 69 63 65 2c 20   ^(In practice, 
304b0 6d 65 74 61 64 61 74 61 20 69 73 20 70 72 65 73  metadata is pres
304c0 65 72 76 65 64 20 62 65 74 77 65 65 6e 20 66 75  erved between fu
304d0 6e 63 74 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72  nction calls for
304e0 0a 2a 2a 20 65 78 70 72 65 73 73 69 6f 6e 73 20  .** expressions 
304f0 74 68 61 74 20 61 72 65 20 63 6f 6e 73 74 61 6e  that are constan
30500 74 20 61 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d  t at compile tim
30510 65 2e 20 54 68 69 73 20 69 6e 63 6c 75 64 65 73  e. This includes
30520 20 6c 69 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75   literal.** valu
30530 65 73 20 61 6e 64 20 5b 70 61 72 61 6d 65 74 65  es and [paramete
30540 72 73 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  rs].)^.**.** The
30550 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
30560 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
30570 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
30580 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
30590 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  SQL function is 
305a0 72 75 6e 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64  running..*/.void
305b0 20 2a 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75   *sqlite3_get_au
305c0 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
305d0 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  ntext*, int N);.
305e0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 73 65 74  void sqlite3_set
305f0 5f 61 75 78 64 61 74 61 28 73 71 6c 69 74 65 33  _auxdata(sqlite3
30600 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e  _context*, int N
30610 2c 20 76 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a  , void*, void (*
30620 29 28 76 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a  )(void*));.../*.
30630 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
30640 73 74 61 6e 74 73 20 44 65 66 69 6e 69 6e 67 20  stants Defining 
30650 53 70 65 63 69 61 6c 20 44 65 73 74 72 75 63 74  Special Destruct
30660 6f 72 20 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a  or Behavior.**.*
30670 2a 20 54 68 65 73 65 20 61 72 65 20 73 70 65 63  * These are spec
30680 69 61 6c 20 76 61 6c 75 65 73 20 66 6f 72 20 74  ial values for t
30690 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 74 68  he destructor th
306a0 61 74 20 69 73 20 70 61 73 73 65 64 20 69 6e 20  at is passed in 
306b0 61 73 20 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20  as the.** final 
306c0 61 72 67 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74  argument to rout
306d0 69 6e 65 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74  ines like [sqlit
306e0 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29  e3_result_blob()
306f0 5d 2e 20 20 5e 49 66 20 74 68 65 20 64 65 73 74  ].  ^If the dest
30700 72 75 63 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65  ructor.** argume
30710 6e 74 20 69 73 20 53 51 4c 49 54 45 5f 53 54 41  nt is SQLITE_STA
30720 54 49 43 2c 20 69 74 20 6d 65 61 6e 73 20 74 68  TIC, it means th
30730 61 74 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 70  at the content p
30740 6f 69 6e 74 65 72 20 69 73 20 63 6f 6e 73 74 61  ointer is consta
30750 6e 74 0a 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e  nt.** and will n
30760 65 76 65 72 20 63 68 61 6e 67 65 2e 20 20 49 74  ever change.  It
30770 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20 74   does not need t
30780 6f 20 62 65 20 64 65 73 74 72 6f 79 65 64 2e 20  o be destroyed. 
30790 20 5e 54 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f   ^The.** SQLITE_
307a0 54 52 41 4e 53 49 45 4e 54 20 76 61 6c 75 65 20  TRANSIENT value 
307b0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 63  means that the c
307c0 6f 6e 74 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65  ontent will like
307d0 6c 79 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20  ly change in.** 
307e0 74 68 65 20 6e 65 61 72 20 66 75 74 75 72 65 20  the near future 
307f0 61 6e 64 20 74 68 61 74 20 53 51 4c 69 74 65 20  and that SQLite 
30800 73 68 6f 75 6c 64 20 6d 61 6b 65 20 69 74 73 20  should make its 
30810 6f 77 6e 20 70 72 69 76 61 74 65 20 63 6f 70 79  own private copy
30820 20 6f 66 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   of.** the conte
30830 6e 74 20 62 65 66 6f 72 65 20 72 65 74 75 72 6e  nt before return
30840 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74  ing..**.** The t
30850 79 70 65 64 65 66 20 69 73 20 6e 65 63 65 73 73  ypedef is necess
30860 61 72 79 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75  ary to work arou
30870 6e 64 20 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63  nd problems in c
30880 65 72 74 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f  ertain.** C++ co
30890 6d 70 69 6c 65 72 73 2e 20 20 53 65 65 20 74 69  mpilers.  See ti
308a0 63 6b 65 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74  cket #2191..*/.t
308b0 79 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71  ypedef void (*sq
308c0 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72  lite3_destructor
308d0 5f 74 79 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23  _type)(void*);.#
308e0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 54  define SQLITE_ST
308f0 41 54 49 43 20 20 20 20 20 20 28 28 73 71 6c 69  ATIC      ((sqli
30900 74 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74  te3_destructor_t
30910 79 70 65 29 30 29 0a 23 64 65 66 69 6e 65 20 53  ype)0).#define S
30920 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 20  QLITE_TRANSIENT 
30930 20 20 28 28 73 71 6c 69 74 65 33 5f 64 65 73 74    ((sqlite3_dest
30940 72 75 63 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a  ructor_type)-1).
30950 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
30960 20 53 65 74 74 69 6e 67 20 54 68 65 20 52 65 73   Setting The Res
30970 75 6c 74 20 4f 66 20 41 6e 20 53 51 4c 20 46 75  ult Of An SQL Fu
30980 6e 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65  nction.**.** The
30990 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
309a0 75 73 65 64 20 62 79 20 74 68 65 20 78 46 75 6e  used by the xFun
309b0 63 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c  c or xFinal call
309c0 62 61 63 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d  backs that.** im
309d0 70 6c 65 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63  plement SQL func
309e0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
309f0 61 74 65 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73  ates.  See.** [s
30a00 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30a10 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
30a20 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
30a30 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66  nction16()].** f
30a40 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  or additional in
30a50 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a  formation..**.**
30a60 20 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   These functions
30a70 20 77 6f 72 6b 20 76 65 72 79 20 6d 75 63 68 20   work very much 
30a80 6c 69 6b 65 20 74 68 65 20 5b 70 61 72 61 6d 65  like the [parame
30a90 74 65 72 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d  ter binding] fam
30aa0 69 6c 79 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69  ily of.** functi
30ab0 6f 6e 73 20 75 73 65 64 20 74 6f 20 62 69 6e 64  ons used to bind
30ac0 20 76 61 6c 75 65 73 20 74 6f 20 68 6f 73 74 20   values to host 
30ad0 70 61 72 61 6d 65 74 65 72 73 20 69 6e 20 70 72  parameters in pr
30ae0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
30af0 73 2e 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20 74  s..** Refer to t
30b00 68 65 20 5b 53 51 4c 20 70 61 72 61 6d 65 74 65  he [SQL paramete
30b10 72 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  r] documentation
30b20 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
30b30 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a  information..**.
30b40 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
30b50 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e  result_blob() in
30b60 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68 65  terface sets the
30b70 20 72 65 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20   result from.** 
30b80 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
30b90 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20  efined function 
30ba0 74 6f 20 62 65 20 74 68 65 20 42 4c 4f 42 20 77  to be the BLOB w
30bb0 68 6f 73 65 20 63 6f 6e 74 65 6e 74 20 69 73 20  hose content is 
30bc0 70 6f 69 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79  pointed.** to by
30bd0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
30be0 6d 65 74 65 72 20 61 6e 64 20 77 68 69 63 68 20  meter and which 
30bf0 69 73 20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20  is N bytes long 
30c00 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 0a 2a  where N is the.*
30c10 2a 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  * third paramete
30c20 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
30c30 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72  lite3_result_zer
30c40 6f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66 61 63  oblob() interfac
30c50 65 73 20 73 65 74 20 74 68 65 20 72 65 73 75 6c  es set the resul
30c60 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
30c70 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
30c80 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30c90 20 42 4c 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67   BLOB containing
30ca0 20 61 6c 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74   all zero.** byt
30cb0 65 73 20 61 6e 64 20 4e 20 62 79 74 65 73 20 69  es and N bytes i
30cc0 6e 20 73 69 7a 65 2c 20 77 68 65 72 65 20 4e 20  n size, where N 
30cd0 69 73 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  is the value of 
30ce0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
30cf0 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  r..**.** ^The sq
30d00 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75  lite3_result_dou
30d10 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
30d20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c 74 20  sets the result 
30d30 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69  from.** an appli
30d40 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
30d50 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20  unction to be a 
30d60 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e 74 20 76  floating point v
30d70 61 6c 75 65 20 73 70 65 63 69 66 69 65 64 0a 2a  alue specified.*
30d80 2a 20 62 79 20 69 74 73 20 32 6e 64 20 61 72 67  * by its 2nd arg
30d90 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
30da0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
30db0 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
30dc0 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
30dd0 72 31 36 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a  r16() functions.
30de0 2a 2a 20 63 61 75 73 65 20 74 68 65 20 69 6d 70  ** cause the imp
30df0 6c 65 6d 65 6e 74 65 64 20 53 51 4c 20 66 75 6e  lemented SQL fun
30e00 63 74 69 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61  ction to throw a
30e10 6e 20 65 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20  n exception..** 
30e20 5e 53 51 4c 69 74 65 20 75 73 65 73 20 74 68 65  ^SQLite uses the
30e30 20 73 74 72 69 6e 67 20 70 6f 69 6e 74 65 64 20   string pointed 
30e40 74 6f 20 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64  to by the.** 2nd
30e50 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 73 71   parameter of sq
30e60 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
30e70 6f 72 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  or() or sqlite3_
30e80 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29  result_error16()
30e90 0a 2a 2a 20 61 73 20 74 68 65 20 74 65 78 74 20  .** as the text 
30ea0 6f 66 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73  of an error mess
30eb0 61 67 65 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e  age.  ^SQLite in
30ec0 74 65 72 70 72 65 74 73 20 74 68 65 20 65 72 72  terprets the err
30ed0 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65 20 73 74  or.** message st
30ee0 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c 69 74 65  ring from sqlite
30ef0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
30f00 20 61 73 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69   as UTF-8. ^SQLi
30f10 74 65 0a 2a 2a 20 69 6e 74 65 72 70 72 65 74 73  te.** interprets
30f20 20 74 68 65 20 73 74 72 69 6e 67 20 66 72 6f 6d   the string from
30f30 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
30f40 65 72 72 6f 72 31 36 28 29 20 61 73 20 55 54 46  error16() as UTF
30f50 2d 31 36 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a  -16 in native.**
30f60 20 62 79 74 65 20 6f 72 64 65 72 2e 20 20 5e 49   byte order.  ^I
30f70 66 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61  f the third para
30f80 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
30f90 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a  _result_error().
30fa0 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  ** or sqlite3_re
30fb0 73 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 20 69  sult_error16() i
30fc0 73 20 6e 65 67 61 74 69 76 65 20 74 68 65 6e 20  s negative then 
30fd0 53 51 4c 69 74 65 20 74 61 6b 65 73 20 61 73 20  SQLite takes as 
30fe0 74 68 65 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73  the error.** mes
30ff0 73 61 67 65 20 61 6c 6c 20 74 65 78 74 20 75 70  sage all text up
31000 20 74 68 72 6f 75 67 68 20 74 68 65 20 66 69 72   through the fir
31010 73 74 20 7a 65 72 6f 20 63 68 61 72 61 63 74 65  st zero characte
31020 72 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 74 68  r..** ^If the th
31030 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
31040 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
31050 65 72 72 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71  error() or.** sq
31060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
31070 6f 72 31 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65  or16() is non-ne
31080 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
31090 74 65 20 74 61 6b 65 73 20 74 68 61 74 20 6d 61  te takes that ma
310a0 6e 79 0a 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74  ny.** bytes (not
310b0 20 63 68 61 72 61 63 74 65 72 73 29 20 66 72 6f   characters) fro
310c0 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65  m the 2nd parame
310d0 74 65 72 20 61 73 20 74 68 65 20 65 72 72 6f 72  ter as the error
310e0 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68   message..** ^Th
310f0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31100 5f 65 72 72 6f 72 28 29 20 61 6e 64 20 73 71 6c  _error() and sql
31110 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
31120 72 31 36 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65  r16().** routine
31130 73 20 6d 61 6b 65 20 61 20 70 72 69 76 61 74 65  s make a private
31140 20 63 6f 70 79 20 6f 66 20 74 68 65 20 65 72 72   copy of the err
31150 6f 72 20 6d 65 73 73 61 67 65 20 74 65 78 74 20  or message text 
31160 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72  before.** they r
31170 65 74 75 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74  eturn.  Hence, t
31180 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
31190 69 6f 6e 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61  ion can dealloca
311a0 74 65 20 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20  te or.** modify 
311b0 74 68 65 20 74 65 78 74 20 61 66 74 65 72 20 74  the text after t
311c0 68 65 79 20 72 65 74 75 72 6e 20 77 69 74 68 6f  hey return witho
311d0 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65  ut harm..** ^The
311e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
311f0 65 72 72 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e  error_code() fun
31200 63 74 69 6f 6e 20 63 68 61 6e 67 65 73 20 74 68  ction changes th
31210 65 20 65 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20  e error code.** 
31220 72 65 74 75 72 6e 65 64 20 62 79 20 53 51 4c 69  returned by SQLi
31230 74 65 20 61 73 20 61 20 72 65 73 75 6c 74 20 6f  te as a result o
31240 66 20 61 6e 20 65 72 72 6f 72 20 69 6e 20 61 20  f an error in a 
31250 66 75 6e 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64  function.  ^By d
31260 65 66 61 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65  efault,.** the e
31270 72 72 6f 72 20 63 6f 64 65 20 69 73 20 53 51 4c  rror code is SQL
31280 49 54 45 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73  ITE_ERROR.  ^A s
31290 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 20 74  ubsequent call t
312a0 6f 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  o sqlite3_result
312b0 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73  _error().** or s
312c0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
312d0 72 6f 72 31 36 28 29 20 72 65 73 65 74 73 20 74  ror16() resets t
312e0 68 65 20 65 72 72 6f 72 20 63 6f 64 65 20 74 6f  he error code to
312f0 20 53 51 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a   SQLITE_ERROR..*
31300 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
31310 33 5f 72 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28  3_result_toobig(
31320 29 20 69 6e 74 65 72 66 61 63 65 20 63 61 75 73  ) interface caus
31330 65 73 20 53 51 4c 69 74 65 20 74 6f 20 74 68 72  es SQLite to thr
31340 6f 77 20 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69  ow an error.** i
31350 6e 64 69 63 61 74 69 6e 67 20 74 68 61 74 20 61  ndicating that a
31360 20 73 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20   string or BLOB 
31370 69 73 20 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72  is too long to r
31380 65 70 72 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  epresent..**.** 
31390 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
313a0 75 6c 74 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65  ult_nomem() inte
313b0 72 66 61 63 65 20 63 61 75 73 65 73 20 53 51 4c  rface causes SQL
313c0 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61 6e 20  ite to throw an 
313d0 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74  error.** indicat
313e0 69 6e 67 20 74 68 61 74 20 61 20 6d 65 6d 6f 72  ing that a memor
313f0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69  y allocation fai
31400 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  led..**.** ^The 
31410 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69  sqlite3_result_i
31420 6e 74 28 29 20 69 6e 74 65 72 66 61 63 65 20 73  nt() interface s
31430 65 74 73 20 74 68 65 20 72 65 74 75 72 6e 20 76  ets the return v
31440 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61  alue.** of the a
31450 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31460 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31470 65 20 74 68 65 20 33 32 2d 62 69 74 20 73 69 67  e the 32-bit sig
31480 6e 65 64 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76  ned integer.** v
31490 61 6c 75 65 20 67 69 76 65 6e 20 69 6e 20 74 68  alue given in th
314a0 65 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a  e 2nd argument..
314b0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
314c0 72 65 73 75 6c 74 5f 69 6e 74 36 34 28 29 20 69  result_int64() i
314d0 6e 74 65 72 66 61 63 65 20 73 65 74 73 20 74 68  nterface sets th
314e0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a  e return value.*
314f0 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  * of the applica
31500 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
31510 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68 65 20  ction to be the 
31520 36 34 2d 62 69 74 20 73 69 67 6e 65 64 20 69 6e  64-bit signed in
31530 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67  teger.** value g
31540 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e 64 20  iven in the 2nd 
31550 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20  argument..**.** 
31560 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
31570 75 6c 74 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72  ult_null() inter
31580 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
31590 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
315a0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
315b0 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
315c0 6e 20 74 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a  n to be NULL..**
315d0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
315e0 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 29 2c 20  _result_text(), 
315f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31600 65 78 74 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69  ext16(),.** sqli
31610 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
31620 36 6c 65 28 29 2c 20 61 6e 64 20 73 71 6c 69 74  6le(), and sqlit
31630 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
31640 62 65 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a  be() interfaces.
31650 2a 2a 20 73 65 74 20 74 68 65 20 72 65 74 75 72  ** set the retur
31660 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 61  n value of the a
31670 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
31680 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
31690 65 0a 2a 2a 20 61 20 74 65 78 74 20 73 74 72 69  e.** a text stri
316a0 6e 67 20 77 68 69 63 68 20 69 73 20 72 65 70 72  ng which is repr
316b0 65 73 65 6e 74 65 64 20 61 73 20 55 54 46 2d 38  esented as UTF-8
316c0 2c 20 55 54 46 2d 31 36 20 6e 61 74 69 76 65 20  , UTF-16 native 
316d0 62 79 74 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55  byte order,.** U
316e0 54 46 2d 31 36 20 6c 69 74 74 6c 65 20 65 6e 64  TF-16 little end
316f0 69 61 6e 2c 20 6f 72 20 55 54 46 2d 31 36 20 62  ian, or UTF-16 b
31700 69 67 20 65 6e 64 69 61 6e 2c 20 72 65 73 70 65  ig endian, respe
31710 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c  ctively..** ^SQL
31720 69 74 65 20 74 61 6b 65 73 20 74 68 65 20 74 65  ite takes the te
31730 78 74 20 72 65 73 75 6c 74 20 66 72 6f 6d 20 74  xt result from t
31740 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 66  he application f
31750 72 6f 6d 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70  rom.** the 2nd p
31760 61 72 61 6d 65 74 65 72 20 6f 66 20 74 68 65 20  arameter of the 
31770 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74  sqlite3_result_t
31780 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ext* interfaces.
31790 0a 2a 2a 20 5e 49 66 20 74 68 65 20 33 72 64 20  .** ^If the 3rd 
317a0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
317b0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
317c0 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65 73  text* interfaces
317d0 0a 2a 2a 20 69 73 20 6e 65 67 61 74 69 76 65 2c  .** is negative,
317e0 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74 61 6b   then SQLite tak
317f0 65 73 20 72 65 73 75 6c 74 20 74 65 78 74 20 66  es result text f
31800 72 6f 6d 20 74 68 65 20 32 6e 64 20 70 61 72 61  rom the 2nd para
31810 6d 65 74 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68  meter.** through
31820 20 74 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20   the first zero 
31830 63 68 61 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49  character..** ^I
31840 66 20 74 68 65 20 33 72 64 20 70 61 72 61 6d 65  f the 3rd parame
31850 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74  ter to the sqlit
31860 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a 20  e3_result_text* 
31870 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 69 73  interfaces.** is
31880 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74   non-negative, t
31890 68 65 6e 20 61 73 20 6d 61 6e 79 20 62 79 74 65  hen as many byte
318a0 73 20 28 6e 6f 74 20 63 68 61 72 61 63 74 65 72  s (not character
318b0 73 29 20 6f 66 20 74 68 65 20 74 65 78 74 0a 2a  s) of the text.*
318c0 2a 20 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20  * pointed to by 
318d0 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
318e0 72 20 61 72 65 20 74 61 6b 65 6e 20 61 73 20 74  r are taken as t
318f0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
31900 65 66 69 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69  efined.** functi
31910 6f 6e 20 72 65 73 75 6c 74 2e 20 20 49 66 20 74  on result.  If t
31920 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
31930 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65   is non-negative
31940 2c 20 74 68 65 6e 20 69 74 0a 2a 2a 20 6d 75 73  , then it.** mus
31950 74 20 62 65 20 74 68 65 20 62 79 74 65 20 6f 66  t be the byte of
31960 66 73 65 74 20 69 6e 74 6f 20 74 68 65 20 73 74  fset into the st
31970 72 69 6e 67 20 77 68 65 72 65 20 74 68 65 20 4e  ring where the N
31980 55 4c 20 74 65 72 6d 69 6e 61 74 6f 72 20 77 6f  UL terminator wo
31990 75 6c 64 0a 2a 2a 20 61 70 70 65 61 72 20 69 66  uld.** appear if
319a0 20 74 68 65 20 73 74 72 69 6e 67 20 77 68 65 72   the string wher
319b0 65 20 4e 55 4c 20 74 65 72 6d 69 6e 61 74 65 64  e NUL terminated
319c0 2e 20 20 49 66 20 61 6e 79 20 4e 55 4c 20 63 68  .  If any NUL ch
319d0 61 72 61 63 74 65 72 73 20 6f 63 63 75 72 0a 2a  aracters occur.*
319e0 2a 20 69 6e 20 74 68 65 20 73 74 72 69 6e 67 20  * in the string 
319f0 61 74 20 61 20 62 79 74 65 20 6f 66 66 73 65 74  at a byte offset
31a00 20 74 68 61 74 20 69 73 20 6c 65 73 73 20 74 68   that is less th
31a10 61 6e 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20  an the value of 
31a20 74 68 65 20 33 72 64 0a 2a 2a 20 70 61 72 61 6d  the 3rd.** param
31a30 65 74 65 72 2c 20 74 68 65 6e 20 74 68 65 20 72  eter, then the r
31a40 65 73 75 6c 74 69 6e 67 20 73 74 72 69 6e 67 20  esulting string 
31a50 77 69 6c 6c 20 63 6f 6e 74 61 69 6e 20 65 6d 62  will contain emb
31a60 65 64 64 65 64 20 4e 55 4c 73 20 61 6e 64 20 74  edded NULs and t
31a70 68 65 0a 2a 2a 20 72 65 73 75 6c 74 20 6f 66 20  he.** result of 
31a80 65 78 70 72 65 73 73 69 6f 6e 73 20 6f 70 65 72  expressions oper
31a90 61 74 69 6e 67 20 6f 6e 20 73 74 72 69 6e 67 73  ating on strings
31aa0 20 77 69 74 68 20 65 6d 62 65 64 64 65 64 20 4e   with embedded N
31ab0 55 4c 73 20 69 73 20 75 6e 64 65 66 69 6e 65 64  ULs is undefined
31ac0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
31ad0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
31ae0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
31af0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
31b00 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
31b10 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 61  result_blob is a
31b20 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e 74 65   non-NULL pointe
31b30 72 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 20 63  r, then SQLite c
31b40 61 6c 6c 73 20 74 68 61 74 0a 2a 2a 20 66 75 6e  alls that.** fun
31b50 63 74 69 6f 6e 20 61 73 20 74 68 65 20 64 65 73  ction as the des
31b60 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 74  tructor on the t
31b70 65 78 74 20 6f 72 20 42 4c 4f 42 20 72 65 73 75  ext or BLOB resu
31b80 6c 74 20 77 68 65 6e 20 69 74 20 68 61 73 0a 2a  lt when it has.*
31b90 2a 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67  * finished using
31ba0 20 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a   that result..**
31bb0 20 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72   ^If the 4th par
31bc0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
31bd0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
31be0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 20 6f 72  t* interfaces or
31bf0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72   to.** sqlite3_r
31c00 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74 68  esult_blob is th
31c10 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74 61  e special consta
31c20 6e 74 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  nt SQLITE_STATIC
31c30 2c 20 74 68 65 6e 20 53 51 4c 69 74 65 0a 2a 2a  , then SQLite.**
31c40 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 74 68   assumes that th
31c50 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42 20 72  e text or BLOB r
31c60 65 73 75 6c 74 20 69 73 20 69 6e 20 63 6f 6e 73  esult is in cons
31c70 74 61 6e 74 20 73 70 61 63 65 20 61 6e 64 20 64  tant space and d
31c80 6f 65 73 20 6e 6f 74 0a 2a 2a 20 63 6f 70 79 20  oes not.** copy 
31c90 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
31ca0 68 65 20 70 61 72 61 6d 65 74 65 72 20 6e 6f 72  he parameter nor
31cb0 20 63 61 6c 6c 20 61 20 64 65 73 74 72 75 63 74   call a destruct
31cc0 6f 72 20 6f 6e 20 74 68 65 20 63 6f 6e 74 65 6e  or on the conten
31cd0 74 0a 2a 2a 20 77 68 65 6e 20 69 74 20 68 61 73  t.** when it has
31ce0 20 66 69 6e 69 73 68 65 64 20 75 73 69 6e 67 20   finished using 
31cf0 74 68 61 74 20 72 65 73 75 6c 74 2e 0a 2a 2a 20  that result..** 
31d00 5e 49 66 20 74 68 65 20 34 74 68 20 70 61 72 61  ^If the 4th para
31d10 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
31d20 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
31d30 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
31d40 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
31d50 74 5f 62 6c 6f 62 20 69 73 20 74 68 65 20 73 70  t_blob is the sp
31d60 65 63 69 61 6c 20 63 6f 6e 73 74 61 6e 74 20 53  ecial constant S
31d70 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e 54 0a  QLITE_TRANSIENT.
31d80 2a 2a 20 74 68 65 6e 20 53 51 4c 69 74 65 20 6d  ** then SQLite m
31d90 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66 20 74  akes a copy of t
31da0 68 65 20 72 65 73 75 6c 74 20 69 6e 74 6f 20 73  he result into s
31db0 70 61 63 65 20 6f 62 74 61 69 6e 65 64 20 66 72  pace obtained fr
31dc0 6f 6d 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c 69  om.** from [sqli
31dd0 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 62 65  te3_malloc()] be
31de0 66 6f 72 65 20 69 74 20 72 65 74 75 72 6e 73 2e  fore it returns.
31df0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31e00 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
31e10 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
31e20 73 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 0a  s the result of.
31e30 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ** the applicati
31e40 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
31e50 69 6f 6e 20 74 6f 20 62 65 20 61 20 63 6f 70 79  ion to be a copy
31e60 20 74 68 65 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65   the.** [unprote
31e70 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
31e80 75 65 5d 20 6f 62 6a 65 63 74 20 73 70 65 63 69  ue] object speci
31e90 66 69 65 64 20 62 79 20 74 68 65 20 32 6e 64 20  fied by the 2nd 
31ea0 70 61 72 61 6d 65 74 65 72 2e 20 20 5e 54 68 65  parameter.  ^The
31eb0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 72 65 73 75  .** sqlite3_resu
31ec0 6c 74 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72  lt_value() inter
31ed0 66 61 63 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  face makes a cop
31ee0 79 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  y of the [sqlite
31ef0 33 5f 76 61 6c 75 65 5d 0a 2a 2a 20 73 6f 20 74  3_value].** so t
31f00 68 61 74 20 74 68 65 20 5b 73 71 6c 69 74 65 33  hat the [sqlite3
31f10 5f 76 61 6c 75 65 5d 20 73 70 65 63 69 66 69 65  _value] specifie
31f20 64 20 69 6e 20 74 68 65 20 70 61 72 61 6d 65 74  d in the paramet
31f30 65 72 20 6d 61 79 20 63 68 61 6e 67 65 20 6f 72  er may change or
31f40 0a 2a 2a 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  .** be deallocat
31f50 65 64 20 61 66 74 65 72 20 73 71 6c 69 74 65 33  ed after sqlite3
31f60 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
31f70 72 65 74 75 72 6e 73 20 77 69 74 68 6f 75 74 20  returns without 
31f80 68 61 72 6d 2e 0a 2a 2a 20 5e 41 20 5b 70 72 6f  harm..** ^A [pro
31f90 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76  tected sqlite3_v
31fa0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 6d 61 79  alue] object may
31fb0 20 61 6c 77 61 79 73 20 62 65 20 75 73 65 64 20   always be used 
31fc0 77 68 65 72 65 20 61 6e 0a 2a 2a 20 5b 75 6e 70  where an.** [unp
31fd0 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
31fe0 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 69  _value] object i
31ff0 73 20 72 65 71 75 69 72 65 64 2c 20 73 6f 20 65  s required, so e
32000 69 74 68 65 72 0a 2a 2a 20 6b 69 6e 64 20 6f 66  ither.** kind of
32010 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
32020 20 6f 62 6a 65 63 74 20 63 61 6e 20 62 65 20 75   object can be u
32030 73 65 64 20 77 69 74 68 20 74 68 69 73 20 69 6e  sed with this in
32040 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 49  terface..**.** I
32050 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
32060 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
32070 20 77 69 74 68 69 6e 20 74 68 65 20 64 69 66 66   within the diff
32080 65 72 65 6e 74 20 74 68 72 65 61 64 0a 2a 2a 20  erent thread.** 
32090 74 68 61 6e 20 74 68 65 20 6f 6e 65 20 63 6f 6e  than the one con
320a0 74 61 69 6e 69 6e 67 20 74 68 65 20 61 70 70 6c  taining the appl
320b0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
320c0 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 72 65  function that re
320d0 63 65 69 76 65 64 0a 2a 2a 20 74 68 65 20 5b 73  ceived.** the [s
320e0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5d 20  qlite3_context] 
320f0 70 6f 69 6e 74 65 72 2c 20 74 68 65 20 72 65 73  pointer, the res
32100 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69 6e  ults are undefin
32110 65 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  ed..*/.void sqli
32120 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 28  te3_result_blob(
32130 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32140 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
32150 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
32160 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
32170 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
32180 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
32190 2c 20 64 6f 75 62 6c 65 29 3b 0a 76 6f 69 64 20  , double);.void 
321a0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
321b0 72 72 6f 72 28 73 71 6c 69 74 65 33 5f 63 6f 6e  rror(sqlite3_con
321c0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 63 68 61  text*, const cha
321d0 72 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73  r*, int);.void s
321e0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
321f0 72 6f 72 31 36 28 73 71 6c 69 74 65 33 5f 63 6f  ror16(sqlite3_co
32200 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
32210 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
32220 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65  sqlite3_result_e
32230 72 72 6f 72 5f 74 6f 6f 62 69 67 28 73 71 6c 69  rror_toobig(sqli
32240 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 76  te3_context*);.v
32250 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32260 6c 74 5f 65 72 72 6f 72 5f 6e 6f 6d 65 6d 28 73  lt_error_nomem(s
32270 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
32280 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72  ;.void sqlite3_r
32290 65 73 75 6c 74 5f 65 72 72 6f 72 5f 63 6f 64 65  esult_error_code
322a0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
322b0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
322c0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
322d0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
322e0 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20 73 71  *, int);.void sq
322f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74  lite3_result_int
32300 36 34 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  64(sqlite3_conte
32310 78 74 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74  xt*, sqlite3_int
32320 36 34 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  64);.void sqlite
32330 33 5f 72 65 73 75 6c 74 5f 6e 75 6c 6c 28 73 71  3_result_null(sq
32340 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
32350 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
32360 73 75 6c 74 5f 74 65 78 74 28 73 71 6c 69 74 65  sult_text(sqlite
32370 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
32380 74 20 63 68 61 72 2a 2c 20 69 6e 74 2c 20 76 6f  t char*, int, vo
32390 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
323a0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
323b0 6c 74 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65  lt_text16(sqlite
323c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
323d0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
323e0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 76  id(*)(void*));.v
323f0 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
32400 6c 74 5f 74 65 78 74 31 36 6c 65 28 73 71 6c 69  lt_text16le(sqli
32410 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
32420 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 76  nst void*, int,v
32430 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
32440 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
32450 75 6c 74 5f 74 65 78 74 31 36 62 65 28 73 71 6c  ult_text16be(sql
32460 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63  ite3_context*, c
32470 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c  onst void*, int,
32480 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b  void(*)(void*));
32490 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
324a0 73 75 6c 74 5f 76 61 6c 75 65 28 73 71 6c 69 74  sult_value(sqlit
324b0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c  e3_context*, sql
324c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 76 6f  ite3_value*);.vo
324d0 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
324e0 74 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  t_zeroblob(sqlit
324f0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e 74  e3_context*, int
32500 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49   n);../*.** CAPI
32510 33 52 45 46 3a 20 44 65 66 69 6e 65 20 4e 65 77  3REF: Define New
32520 20 43 6f 6c 6c 61 74 69 6e 67 20 53 65 71 75 65   Collating Seque
32530 6e 63 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  nces.**.** ^Thes
32540 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 64 64 2c  e functions add,
32550 20 72 65 6d 6f 76 65 2c 20 6f 72 20 6d 6f 64 69   remove, or modi
32560 66 79 20 61 20 5b 63 6f 6c 6c 61 74 69 6f 6e 5d  fy a [collation]
32570 20 61 73 73 6f 63 69 61 74 65 64 0a 2a 2a 20 77   associated.** w
32580 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61 73  ith the [databas
32590 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
325a0 65 63 69 66 69 65 64 20 61 73 20 74 68 65 20 66  ecified as the f
325b0 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e 0a 2a  irst argument..*
325c0 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61 6d 65 20 6f  *.** ^The name o
325d0 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20  f the collation 
325e0 69 73 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e  is a UTF-8 strin
325f0 67 0a 2a 2a 20 66 6f 72 20 73 71 6c 69 74 65 33  g.** for sqlite3
32600 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
32610 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  n() and sqlite3_
32620 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e  create_collation
32630 5f 76 32 28 29 0a 2a 2a 20 61 6e 64 20 61 20 55  _v2().** and a U
32640 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69 6e 20  TF-16 string in 
32650 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
32660 72 20 66 6f 72 20 73 71 6c 69 74 65 33 5f 63 72  r for sqlite3_cr
32670 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36  eate_collation16
32680 28 29 2e 0a 2a 2a 20 5e 43 6f 6c 6c 61 74 69 6f  ()..** ^Collatio
32690 6e 20 6e 61 6d 65 73 20 74 68 61 74 20 63 6f 6d  n names that com
326a0 70 61 72 65 20 65 71 75 61 6c 20 61 63 63 6f 72  pare equal accor
326b0 64 69 6e 67 20 74 6f 20 5b 73 71 6c 69 74 65 33  ding to [sqlite3
326c0 5f 73 74 72 6e 69 63 6d 70 28 29 5d 20 61 72 65  _strnicmp()] are
326d0 0a 2a 2a 20 63 6f 6e 73 69 64 65 72 65 64 20 74  .** considered t
326e0 6f 20 62 65 20 74 68 65 20 73 61 6d 65 20 6e 61  o be the same na
326f0 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20  me..**.** ^(The 
32700 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 28  third argument (
32710 65 54 65 78 74 52 65 70 29 20 6d 75 73 74 20 62  eTextRep) must b
32720 65 20 6f 6e 65 20 6f 66 20 74 68 65 20 63 6f 6e  e one of the con
32730 73 74 61 6e 74 73 3a 0a 2a 2a 20 3c 75 6c 3e 0a  stants:.** <ul>.
32740 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
32750 55 54 46 38 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  UTF8],.** <li> [
32760 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
32770 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
32780 5f 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 3c 6c  _UTF16BE],.** <l
32790 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
327a0 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  ], or.** <li> [S
327b0 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49 47  QLITE_UTF16_ALIG
327c0 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  NED]..** </ul>)^
327d0 0a 2a 2a 20 5e 54 68 65 20 65 54 65 78 74 52 65  .** ^The eTextRe
327e0 70 20 61 72 67 75 6d 65 6e 74 20 64 65 74 65 72  p argument deter
327f0 6d 69 6e 65 73 20 74 68 65 20 65 6e 63 6f 64 69  mines the encodi
32800 6e 67 20 6f 66 20 73 74 72 69 6e 67 73 20 70 61  ng of strings pa
32810 73 73 65 64 0a 2a 2a 20 74 6f 20 74 68 65 20 63  ssed.** to the c
32820 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
32830 6e 20 63 61 6c 6c 62 61 63 6b 2c 20 78 43 61 6c  n callback, xCal
32840 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 54 68 65 20 5b  lback..** ^The [
32850 53 51 4c 49 54 45 5f 55 54 46 31 36 5d 20 61 6e  SQLITE_UTF16] an
32860 64 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  d [SQLITE_UTF16_
32870 41 4c 49 47 4e 45 44 5d 20 76 61 6c 75 65 73 20  ALIGNED] values 
32880 66 6f 72 20 65 54 65 78 74 52 65 70 0a 2a 2a 20  for eTextRep.** 
32890 66 6f 72 63 65 20 73 74 72 69 6e 67 73 20 74 6f  force strings to
328a0 20 62 65 20 55 54 46 31 36 20 77 69 74 68 20 6e   be UTF16 with n
328b0 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
328c0 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  ..** ^The [SQLIT
328d0 45 5f 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d  E_UTF16_ALIGNED]
328e0 20 76 61 6c 75 65 20 66 6f 72 20 65 54 65 78 74   value for eText
328f0 52 65 70 20 66 6f 72 63 65 73 20 73 74 72 69 6e  Rep forces strin
32900 67 73 20 74 6f 20 62 65 67 69 6e 0a 2a 2a 20 6f  gs to begin.** o
32910 6e 20 61 6e 20 65 76 65 6e 20 62 79 74 65 20 61  n an even byte a
32920 64 64 72 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ddress..**.** ^T
32930 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65  he fourth argume
32940 6e 74 2c 20 70 41 72 67 2c 20 69 73 20 61 6e 20  nt, pArg, is an 
32950 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
32960 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73   pointer that is
32970 20 70 61 73 73 65 64 0a 2a 2a 20 74 68 72 6f 75   passed.** throu
32980 67 68 20 61 73 20 74 68 65 20 66 69 72 73 74 20  gh as the first 
32990 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
329a0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
329b0 6f 6e 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  on callback..**.
329c0 2a 2a 20 5e 54 68 65 20 66 69 66 74 68 20 61 72  ** ^The fifth ar
329d0 67 75 6d 65 6e 74 2c 20 78 43 61 6c 6c 62 61 63  gument, xCallbac
329e0 6b 2c 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  k, is a pointer 
329f0 74 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  to the collating
32a00 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 5e 4d   function..** ^M
32a10 75 6c 74 69 70 6c 65 20 63 6f 6c 6c 61 74 69 6e  ultiple collatin
32a20 67 20 66 75 6e 63 74 69 6f 6e 73 20 63 61 6e 20  g functions can 
32a30 62 65 20 72 65 67 69 73 74 65 72 65 64 20 75 73  be registered us
32a40 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
32a50 65 20 62 75 74 0a 2a 2a 20 77 69 74 68 20 64 69  e but.** with di
32a60 66 66 65 72 65 6e 74 20 65 54 65 78 74 52 65 70  fferent eTextRep
32a70 20 70 61 72 61 6d 65 74 65 72 73 20 61 6e 64 20   parameters and 
32a80 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65 20  SQLite will use 
32a90 77 68 69 63 68 65 76 65 72 0a 2a 2a 20 66 75 6e  whichever.** fun
32aa0 63 74 69 6f 6e 20 72 65 71 75 69 72 65 73 20 74  ction requires t
32ab0 68 65 20 6c 65 61 73 74 20 61 6d 6f 75 6e 74 20  he least amount 
32ac0 6f 66 20 64 61 74 61 20 74 72 61 6e 73 66 6f 72  of data transfor
32ad0 6d 61 74 69 6f 6e 2e 0a 2a 2a 20 5e 49 66 20 74  mation..** ^If t
32ae0 68 65 20 78 43 61 6c 6c 62 61 63 6b 20 61 72 67  he xCallback arg
32af0 75 6d 65 6e 74 20 69 73 20 4e 55 4c 4c 20 74 68  ument is NULL th
32b00 65 6e 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67  en the collating
32b10 20 66 75 6e 63 74 69 6f 6e 20 69 73 0a 2a 2a 20   function is.** 
32b20 64 65 6c 65 74 65 64 2e 20 20 5e 57 68 65 6e 20  deleted.  ^When 
32b30 61 6c 6c 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  all collating fu
32b40 6e 63 74 69 6f 6e 73 20 68 61 76 69 6e 67 20 74  nctions having t
32b50 68 65 20 73 61 6d 65 20 6e 61 6d 65 20 61 72 65  he same name are
32b60 20 64 65 6c 65 74 65 64 2c 0a 2a 2a 20 74 68 61   deleted,.** tha
32b70 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 69 73 20 6e  t collation is n
32b80 6f 20 6c 6f 6e 67 65 72 20 75 73 61 62 6c 65 2e  o longer usable.
32b90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 6c  .**.** ^The coll
32ba0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 63  ating function c
32bb0 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b  allback is invok
32bc0 65 64 20 77 69 74 68 20 61 20 63 6f 70 79 20 6f  ed with a copy o
32bd0 66 20 74 68 65 20 70 41 72 67 20 0a 2a 2a 20 61  f the pArg .** a
32be0 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61 20  pplication data 
32bf0 70 6f 69 6e 74 65 72 20 61 6e 64 20 77 69 74 68  pointer and with
32c00 20 74 77 6f 20 73 74 72 69 6e 67 73 20 69 6e 20   two strings in 
32c10 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 73 70 65  the encoding spe
32c20 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
32c30 20 65 54 65 78 74 52 65 70 20 61 72 67 75 6d 65   eTextRep argume
32c40 6e 74 2e 20 20 54 68 65 20 63 6f 6c 6c 61 74 69  nt.  The collati
32c50 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
32c60 20 72 65 74 75 72 6e 20 61 6e 0a 2a 2a 20 69 6e   return an.** in
32c70 74 65 67 65 72 20 74 68 61 74 20 69 73 20 6e 65  teger that is ne
32c80 67 61 74 69 76 65 2c 20 7a 65 72 6f 2c 20 6f 72  gative, zero, or
32c90 20 70 6f 73 69 74 69 76 65 0a 2a 2a 20 69 66 20   positive.** if 
32ca0 74 68 65 20 66 69 72 73 74 20 73 74 72 69 6e 67  the first string
32cb0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 2c 20 65   is less than, e
32cc0 71 75 61 6c 20 74 6f 2c 20 6f 72 20 67 72 65 61  qual to, or grea
32cd0 74 65 72 20 74 68 61 6e 20 74 68 65 20 73 65 63  ter than the sec
32ce0 6f 6e 64 2c 0a 2a 2a 20 72 65 73 70 65 63 74 69  ond,.** respecti
32cf0 76 65 6c 79 2e 20 20 41 20 63 6f 6c 6c 61 74 69  vely.  A collati
32d00 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
32d10 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 20 74   always return t
32d20 68 65 20 73 61 6d 65 20 61 6e 73 77 65 72 0a 2a  he same answer.*
32d30 2a 20 67 69 76 65 6e 20 74 68 65 20 73 61 6d 65  * given the same
32d40 20 69 6e 70 75 74 73 2e 20 20 49 66 20 74 77 6f   inputs.  If two
32d50 20 6f 72 20 6d 6f 72 65 20 63 6f 6c 6c 61 74 69   or more collati
32d60 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  ng functions are
32d70 20 72 65 67 69 73 74 65 72 65 64 0a 2a 2a 20 74   registered.** t
32d80 6f 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 6c 61  o the same colla
32d90 74 69 6f 6e 20 6e 61 6d 65 20 28 75 73 69 6e 67  tion name (using
32da0 20 64 69 66 66 65 72 65 6e 74 20 65 54 65 78 74   different eText
32db0 52 65 70 20 76 61 6c 75 65 73 29 20 74 68 65 6e  Rep values) then
32dc0 20 61 6c 6c 0a 2a 2a 20 6d 75 73 74 20 67 69 76   all.** must giv
32dd0 65 20 61 6e 20 65 71 75 69 76 61 6c 65 6e 74 20  e an equivalent 
32de0 61 6e 73 77 65 72 20 77 68 65 6e 20 69 6e 76 6f  answer when invo
32df0 6b 65 64 20 77 69 74 68 20 65 71 75 69 76 61 6c  ked with equival
32e00 65 6e 74 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20  ent strings..** 
32e10 54 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  The collating fu
32e20 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6f 62 65 79  nction must obey
32e30 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 70   the following p
32e40 72 6f 70 65 72 74 69 65 73 20 66 6f 72 20 61 6c  roperties for al
32e50 6c 0a 2a 2a 20 73 74 72 69 6e 67 73 20 41 2c 20  l.** strings A, 
32e60 42 2c 20 61 6e 64 20 43 3a 0a 2a 2a 0a 2a 2a 20  B, and C:.**.** 
32e70 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  <ol>.** <li> If 
32e80 41 3d 3d 42 20 74 68 65 6e 20 42 3d 3d 41 2e 0a  A==B then B==A..
32e90 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 3d 3d 42 20  ** <li> If A==B 
32ea0 61 6e 64 20 42 3d 3d 43 20 74 68 65 6e 20 41 3d  and B==C then A=
32eb0 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41  =C..** <li> If A
32ec0 26 6c 74 3b 42 20 54 48 45 4e 20 42 26 67 74 3b  &lt;B THEN B&gt;
32ed0 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20 41 26  A..** <li> If A&
32ee0 6c 74 3b 42 20 61 6e 64 20 42 26 6c 74 3b 43 20  lt;B and B&lt;C 
32ef0 74 68 65 6e 20 41 26 6c 74 3b 43 2e 0a 2a 2a 20  then A&lt;C..** 
32f00 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 49 66 20 61  </ol>.**.** If a
32f10 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
32f20 69 6f 6e 20 66 61 69 6c 73 20 61 6e 79 20 6f 66  ion fails any of
32f30 20 74 68 65 20 61 62 6f 76 65 20 63 6f 6e 73 74   the above const
32f40 72 61 69 6e 74 73 20 61 6e 64 20 74 68 61 74 0a  raints and that.
32f50 2a 2a 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  ** collating fun
32f60 63 74 69 6f 6e 20 69 73 20 20 72 65 67 69 73 74  ction is  regist
32f70 65 72 65 64 20 61 6e 64 20 75 73 65 64 2c 20 74  ered and used, t
32f80 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
32f90 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 69 73   of SQLite.** is
32fa0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
32fb0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
32fc0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
32fd0 76 32 28 29 20 77 6f 72 6b 73 20 6c 69 6b 65 20  v2() works like 
32fe0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
32ff0 6f 6c 6c 61 74 69 6f 6e 28 29 0a 2a 2a 20 77 69  ollation().** wi
33000 74 68 20 74 68 65 20 61 64 64 69 74 69 6f 6e 20  th the addition 
33010 74 68 61 74 20 74 68 65 20 78 44 65 73 74 72 6f  that the xDestro
33020 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  y callback is in
33030 76 6f 6b 65 64 20 6f 6e 20 70 41 72 67 20 77 68  voked on pArg wh
33040 65 6e 0a 2a 2a 20 74 68 65 20 63 6f 6c 6c 61 74  en.** the collat
33050 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  ing function is 
33060 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 43 6f 6c  deleted..** ^Col
33070 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
33080 20 61 72 65 20 64 65 6c 65 74 65 64 20 77 68 65   are deleted whe
33090 6e 20 74 68 65 79 20 61 72 65 20 6f 76 65 72 72  n they are overr
330a0 69 64 64 65 6e 20 62 79 20 6c 61 74 65 72 0a 2a  idden by later.*
330b0 2a 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 63  * calls to the c
330c0 6f 6c 6c 61 74 69 6f 6e 20 63 72 65 61 74 69 6f  ollation creatio
330d0 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20 77  n functions or w
330e0 68 65 6e 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  hen the.** [data
330f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33100 20 69 73 20 63 6c 6f 73 65 64 20 75 73 69 6e 67   is closed using
33110 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28   [sqlite3_close(
33120 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 78  )]..**.** ^The x
33130 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
33140 20 69 73 20 3c 75 3e 6e 6f 74 3c 2f 75 3e 20 63   is <u>not</u> c
33150 61 6c 6c 65 64 20 69 66 20 74 68 65 20 0a 2a 2a  alled if the .**
33160 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
33170 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 66  collation_v2() f
33180 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 2e 20 20  unction fails.  
33190 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
331a0 74 20 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69  t invoke.** sqli
331b0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
331c0 74 69 6f 6e 5f 76 32 28 29 20 77 69 74 68 20 61  tion_v2() with a
331d0 20 6e 6f 6e 2d 4e 55 4c 4c 20 78 44 65 73 74 72   non-NULL xDestr
331e0 6f 79 20 61 72 67 75 6d 65 6e 74 20 73 68 6f 75  oy argument shou
331f0 6c 64 20 0a 2a 2a 20 63 68 65 63 6b 20 74 68 65  ld .** check the
33200 20 72 65 74 75 72 6e 20 63 6f 64 65 20 61 6e 64   return code and
33210 20 64 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20   dispose of the 
33220 61 70 70 6c 69 63 61 74 69 6f 6e 20 64 61 74 61  application data
33230 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 68 65 6d   pointer.** them
33240 73 65 6c 76 65 73 20 72 61 74 68 65 72 20 74 68  selves rather th
33250 61 6e 20 65 78 70 65 63 74 69 6e 67 20 53 51 4c  an expecting SQL
33260 69 74 65 20 74 6f 20 64 65 61 6c 20 77 69 74 68  ite to deal with
33270 20 69 74 20 66 6f 72 20 74 68 65 6d 2e 0a 2a 2a   it for them..**
33280 20 54 68 69 73 20 69 73 20 64 69 66 66 65 72 65   This is differe
33290 6e 74 20 66 72 6f 6d 20 65 76 65 72 79 20 6f 74  nt from every ot
332a0 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74 65 72  her SQLite inter
332b0 66 61 63 65 2e 20 20 54 68 65 20 69 6e 63 6f 6e  face.  The incon
332c0 73 69 73 74 65 6e 63 79 20 0a 2a 2a 20 69 73 20  sistency .** is 
332d0 75 6e 66 6f 72 74 75 6e 61 74 65 20 62 75 74 20  unfortunate but 
332e0 63 61 6e 6e 6f 74 20 62 65 20 63 68 61 6e 67 65  cannot be change
332f0 64 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69  d without breaki
33300 6e 67 20 62 61 63 6b 77 61 72 64 73 20 0a 2a 2a  ng backwards .**
33310 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
33320 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
33330 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74   [sqlite3_collat
33340 69 6f 6e 5f 6e 65 65 64 65 64 28 29 5d 20 61 6e  ion_needed()] an
33350 64 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  d [sqlite3_colla
33360 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 5d  tion_needed16()]
33370 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
33380 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
33390 6e 28 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a  n(.  sqlite3*, .
333a0 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e    const char *zN
333b0 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78  ame, .  int eTex
333c0 74 52 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70  tRep, .  void *p
333d0 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d  Arg,.  int(*xCom
333e0 70 61 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  pare)(void*,int,
333f0 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c  const void*,int,
33400 63 6f 6e 73 74 20 76 6f 69 64 2a 29 0a 29 3b 0a  const void*).);.
33410 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
33420 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28  te_collation_v2(
33430 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
33440 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
33450 65 2c 20 0a 20 20 69 6e 74 20 65 54 65 78 74 52  e, .  int eTextR
33460 65 70 2c 20 0a 20 20 76 6f 69 64 20 2a 70 41 72  ep, .  void *pAr
33470 67 2c 0a 20 20 69 6e 74 28 2a 78 43 6f 6d 70 61  g,.  int(*xCompa
33480 72 65 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  re)(void*,int,co
33490 6e 73 74 20 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f  nst void*,int,co
334a0 6e 73 74 20 76 6f 69 64 2a 29 2c 0a 20 20 76 6f  nst void*),.  vo
334b0 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
334c0 69 64 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  id*).);.int sqli
334d0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
334e0 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74 65  tion16(.  sqlite
334f0 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 76 6f 69  3*, .  const voi
33500 64 20 2a 7a 4e 61 6d 65 2c 0a 20 20 69 6e 74 20  d *zName,.  int 
33510 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
33520 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
33530 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
33540 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
33550 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
33560 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
33570 52 45 46 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 4e  REF: Collation N
33580 65 65 64 65 64 20 43 61 6c 6c 62 61 63 6b 73 0a  eeded Callbacks.
33590 2a 2a 0a 2a 2a 20 5e 54 6f 20 61 76 6f 69 64 20  **.** ^To avoid 
335a0 68 61 76 69 6e 67 20 74 6f 20 72 65 67 69 73 74  having to regist
335b0 65 72 20 61 6c 6c 20 63 6f 6c 6c 61 74 69 6f 6e  er all collation
335c0 20 73 65 71 75 65 6e 63 65 73 20 62 65 66 6f 72   sequences befor
335d0 65 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  e a database.** 
335e0 63 61 6e 20 62 65 20 75 73 65 64 2c 20 61 20 73  can be used, a s
335f0 69 6e 67 6c 65 20 63 61 6c 6c 62 61 63 6b 20 66  ingle callback f
33600 75 6e 63 74 69 6f 6e 20 6d 61 79 20 62 65 20 72  unction may be r
33610 65 67 69 73 74 65 72 65 64 20 77 69 74 68 20 74  egistered with t
33620 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  he.** [database 
33630 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 62  connection] to b
33640 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
33650 65 72 20 61 6e 20 75 6e 64 65 66 69 6e 65 64 20  er an undefined 
33660 63 6f 6c 6c 61 74 69 6f 6e 0a 2a 2a 20 73 65 71  collation.** seq
33670 75 65 6e 63 65 20 69 73 20 72 65 71 75 69 72 65  uence is require
33680 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
33690 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 65 67   function is reg
336a0 69 73 74 65 72 65 64 20 75 73 69 6e 67 20 74 68  istered using th
336b0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  e sqlite3_collat
336c0 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 41 50 49  ion_needed() API
336d0 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
336e0 70 61 73 73 65 64 20 74 68 65 20 6e 61 6d 65 73  passed the names
336f0 20 6f 66 20 75 6e 64 65 66 69 6e 65 64 20 63 6f   of undefined co
33700 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
33710 73 20 61 73 20 73 74 72 69 6e 67 73 0a 2a 2a 20  s as strings.** 
33720 65 6e 63 6f 64 65 64 20 69 6e 20 55 54 46 2d 38  encoded in UTF-8
33730 2e 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63 6f  . ^If sqlite3_co
33740 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36  llation_needed16
33750 28 29 20 69 73 20 75 73 65 64 2c 0a 2a 2a 20 74  () is used,.** t
33760 68 65 20 6e 61 6d 65 73 20 61 72 65 20 70 61 73  he names are pas
33770 73 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  sed as UTF-16 in
33780 20 6d 61 63 68 69 6e 65 20 6e 61 74 69 76 65 20   machine native 
33790 62 79 74 65 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e  byte order..** ^
337a0 41 20 63 61 6c 6c 20 74 6f 20 65 69 74 68 65 72  A call to either
337b0 20 66 75 6e 63 74 69 6f 6e 20 72 65 70 6c 61 63   function replac
337c0 65 73 20 74 68 65 20 65 78 69 73 74 69 6e 67 20  es the existing 
337d0 63 6f 6c 6c 61 74 69 6f 6e 2d 6e 65 65 64 65 64  collation-needed
337e0 20 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   callback..**.**
337f0 20 5e 28 57 68 65 6e 20 74 68 65 20 63 61 6c 6c   ^(When the call
33800 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 2c  back is invoked,
33810 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
33820 65 6e 74 20 70 61 73 73 65 64 20 69 73 20 61 20  ent passed is a 
33830 63 6f 70 79 0a 2a 2a 20 6f 66 20 74 68 65 20 73  copy.** of the s
33840 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
33850 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  o sqlite3_collat
33860 69 6f 6e 5f 6e 65 65 64 65 64 28 29 20 6f 72 0a  ion_needed() or.
33870 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61  ** sqlite3_colla
33880 74 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 29 2e  tion_needed16().
33890 20 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67    The second arg
338a0 75 6d 65 6e 74 20 69 73 20 74 68 65 20 64 61 74  ument is the dat
338b0 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
338c0 69 6f 6e 2e 20 20 54 68 65 20 74 68 69 72 64 20  ion.  The third 
338d0 61 72 67 75 6d 65 6e 74 20 69 73 20 6f 6e 65 20  argument is one 
338e0 6f 66 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 5d  of [SQLITE_UTF8]
338f0 2c 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 42  , [SQLITE_UTF16B
33900 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54  E],.** or [SQLIT
33910 45 5f 55 54 46 31 36 4c 45 5d 2c 20 69 6e 64 69  E_UTF16LE], indi
33920 63 61 74 69 6e 67 20 74 68 65 20 6d 6f 73 74 20  cating the most 
33930 64 65 73 69 72 61 62 6c 65 20 66 6f 72 6d 20 6f  desirable form o
33940 66 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 0a  f the collation.
33950 2a 2a 20 73 65 71 75 65 6e 63 65 20 66 75 6e 63  ** sequence func
33960 74 69 6f 6e 20 72 65 71 75 69 72 65 64 2e 20 20  tion required.  
33970 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
33980 65 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65  eter is the name
33990 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 71 75 69   of the.** requi
339a0 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  red collation se
339b0 71 75 65 6e 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20  quence.)^.**.** 
339c0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  The callback fun
339d0 63 74 69 6f 6e 20 73 68 6f 75 6c 64 20 72 65 67  ction should reg
339e0 69 73 74 65 72 20 74 68 65 20 64 65 73 69 72 65  ister the desire
339f0 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 75 73 69 6e  d collation usin
33a00 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 72  g.** [sqlite3_cr
33a10 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
33a20 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  ], [sqlite3_crea
33a30 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 29  te_collation16()
33a40 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  ], or.** [sqlite
33a50 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
33a60 6f 6e 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  on_v2()]..*/.int
33a70 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
33a80 6f 6e 5f 6e 65 65 64 65 64 28 0a 20 20 73 71 6c  on_needed(.  sql
33a90 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c  ite3*, .  void*,
33aa0 20 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69 64   .  void(*)(void
33ab0 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20 65  *,sqlite3*,int e
33ac0 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 63 68  TextRep,const ch
33ad0 61 72 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  ar*).);.int sqli
33ae0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
33af0 65 64 65 64 31 36 28 0a 20 20 73 71 6c 69 74 65  eded16(.  sqlite
33b00 33 2a 2c 20 0a 20 20 76 6f 69 64 2a 2c 0a 20 20  3*, .  void*,.  
33b10 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a 2c 73 71  void(*)(void*,sq
33b20 6c 69 74 65 33 2a 2c 69 6e 74 20 65 54 65 78 74  lite3*,int eText
33b30 52 65 70 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  Rep,const void*)
33b40 0a 29 3b 0a 0a 23 69 66 64 65 66 20 53 51 4c 49  .);..#ifdef SQLI
33b50 54 45 5f 48 41 53 5f 43 4f 44 45 43 0a 2f 2a 0a  TE_HAS_CODEC./*.
33b60 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 6b  ** Specify the k
33b70 65 79 20 66 6f 72 20 61 6e 20 65 6e 63 72 79 70  ey for an encryp
33b80 74 65 64 20 64 61 74 61 62 61 73 65 2e 20 20 54  ted database.  T
33b90 68 69 73 20 72 6f 75 74 69 6e 65 20 73 68 6f 75  his routine shou
33ba0 6c 64 20 62 65 0a 2a 2a 20 63 61 6c 6c 65 64 20  ld be.** called 
33bb0 72 69 67 68 74 20 61 66 74 65 72 20 73 71 6c 69  right after sqli
33bc0 74 65 33 5f 6f 70 65 6e 28 29 2e 0a 2a 2a 0a 2a  te3_open()..**.*
33bd0 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
33be0 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
33bf0 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
33c00 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
33c10 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
33c20 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
33c30 69 74 65 33 5f 6b 65 79 28 0a 20 20 73 71 6c 69  ite3_key(.  sqli
33c40 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20  te3 *db,        
33c50 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61             /* Da
33c60 74 61 62 61 73 65 20 74 6f 20 62 65 20 72 65 6b  tabase to be rek
33c70 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  eyed */.  const 
33c80 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20  void *pKey, int 
33c90 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68 65 20  nKey     /* The 
33ca0 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  key */.);../*.**
33cb0 20 43 68 61 6e 67 65 20 74 68 65 20 6b 65 79 20   Change the key 
33cc0 6f 6e 20 61 6e 20 6f 70 65 6e 20 64 61 74 61 62  on an open datab
33cd0 61 73 65 2e 20 20 49 66 20 74 68 65 20 63 75 72  ase.  If the cur
33ce0 72 65 6e 74 20 64 61 74 61 62 61 73 65 20 69 73  rent database is
33cf0 20 6e 6f 74 0a 2a 2a 20 65 6e 63 72 79 70 74 65   not.** encrypte
33d00 64 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  d, this routine 
33d10 77 69 6c 6c 20 65 6e 63 72 79 70 74 20 69 74 2e  will encrypt it.
33d20 20 20 49 66 20 70 4e 65 77 3d 3d 30 20 6f 72 20    If pNew==0 or 
33d30 6e 4e 65 77 3d 3d 30 2c 20 74 68 65 0a 2a 2a 20  nNew==0, the.** 
33d40 64 61 74 61 62 61 73 65 20 69 73 20 64 65 63 72  database is decr
33d50 79 70 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ypted..**.** The
33d60 20 63 6f 64 65 20 74 6f 20 69 6d 70 6c 65 6d 65   code to impleme
33d70 6e 74 20 74 68 69 73 20 41 50 49 20 69 73 20 6e  nt this API is n
33d80 6f 74 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 20  ot available in 
33d90 74 68 65 20 70 75 62 6c 69 63 20 72 65 6c 65 61  the public relea
33da0 73 65 0a 2a 2a 20 6f 66 20 53 51 4c 69 74 65 2e  se.** of SQLite.
33db0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
33dc0 72 65 6b 65 79 28 0a 20 20 73 71 6c 69 74 65 33  rekey(.  sqlite3
33dd0 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 20   *db,           
33de0 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
33df0 61 73 65 20 74 6f 20 62 65 20 72 65 6b 65 79 65  ase to be rekeye
33e00 64 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  d */.  const voi
33e10 64 20 2a 70 4b 65 79 2c 20 69 6e 74 20 6e 4b 65  d *pKey, int nKe
33e20 79 20 20 20 20 20 2f 2a 20 54 68 65 20 6e 65 77  y     /* The new
33e30 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   key */.);../*.*
33e40 2a 20 53 70 65 63 69 66 79 20 74 68 65 20 61 63  * Specify the ac
33e50 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72  tivation key for
33e60 20 61 20 53 45 45 20 64 61 74 61 62 61 73 65 2e   a SEE database.
33e70 20 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74    Unless .** act
33e80 69 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20  ivated, none of 
33e90 74 68 65 20 53 45 45 20 72 6f 75 74 69 6e 65 73  the SEE routines
33ea0 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a 76   will work..*/.v
33eb0 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74 69  oid sqlite3_acti
33ec0 76 61 74 65 5f 73 65 65 28 0a 20 20 63 6f 6e 73  vate_see(.  cons
33ed0 74 20 63 68 61 72 20 2a 7a 50 61 73 73 50 68 72  t char *zPassPhr
33ee0 61 73 65 20 20 20 20 20 20 20 20 2f 2a 20 41 63  ase        /* Ac
33ef0 74 69 76 61 74 69 6f 6e 20 70 68 72 61 73 65 20  tivation phrase 
33f00 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a 0a 23 69  */.);.#endif..#i
33f10 66 64 65 66 20 53 51 4c 49 54 45 5f 45 4e 41 42  fdef SQLITE_ENAB
33f20 4c 45 5f 43 45 52 4f 44 0a 2f 2a 0a 2a 2a 20 53  LE_CEROD./*.** S
33f30 70 65 63 69 66 79 20 74 68 65 20 61 63 74 69 76  pecify the activ
33f40 61 74 69 6f 6e 20 6b 65 79 20 66 6f 72 20 61 20  ation key for a 
33f50 43 45 52 4f 44 20 64 61 74 61 62 61 73 65 2e 20  CEROD database. 
33f60 20 55 6e 6c 65 73 73 20 0a 2a 2a 20 61 63 74 69   Unless .** acti
33f70 76 61 74 65 64 2c 20 6e 6f 6e 65 20 6f 66 20 74  vated, none of t
33f80 68 65 20 43 45 52 4f 44 20 72 6f 75 74 69 6e 65  he CEROD routine
33f90 73 20 77 69 6c 6c 20 77 6f 72 6b 2e 0a 2a 2f 0a  s will work..*/.
33fa0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 61 63 74  void sqlite3_act
33fb0 69 76 61 74 65 5f 63 65 72 6f 64 28 0a 20 20 63  ivate_cerod(.  c
33fc0 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61 73 73  onst char *zPass
33fd0 50 68 72 61 73 65 20 20 20 20 20 20 20 20 2f 2a  Phrase        /*
33fe0 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68 72 61   Activation phra
33ff0 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69 66 0a  se */.);.#endif.
34000 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
34010 20 53 75 73 70 65 6e 64 20 45 78 65 63 75 74 69   Suspend Executi
34020 6f 6e 20 46 6f 72 20 41 20 53 68 6f 72 74 20 54  on For A Short T
34030 69 6d 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ime.**.** The sq
34040 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 66 75  lite3_sleep() fu
34050 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 74 68  nction causes th
34060 65 20 63 75 72 72 65 6e 74 20 74 68 72 65 61 64  e current thread
34070 20 74 6f 20 73 75 73 70 65 6e 64 20 65 78 65 63   to suspend exec
34080 75 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 61 74 20  ution.** for at 
34090 6c 65 61 73 74 20 61 20 6e 75 6d 62 65 72 20 6f  least a number o
340a0 66 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 73  f milliseconds s
340b0 70 65 63 69 66 69 65 64 20 69 6e 20 69 74 73 20  pecified in its 
340c0 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a  parameter..**.**
340d0 20 49 66 20 74 68 65 20 6f 70 65 72 61 74 69 6e   If the operatin
340e0 67 20 73 79 73 74 65 6d 20 64 6f 65 73 20 6e 6f  g system does no
340f0 74 20 73 75 70 70 6f 72 74 20 73 6c 65 65 70 20  t support sleep 
34100 72 65 71 75 65 73 74 73 20 77 69 74 68 0a 2a 2a  requests with.**
34110 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 20 74 69 6d   millisecond tim
34120 65 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 20 74 68  e resolution, th
34130 65 6e 20 74 68 65 20 74 69 6d 65 20 77 69 6c 6c  en the time will
34140 20 62 65 20 72 6f 75 6e 64 65 64 20 75 70 20 74   be rounded up t
34150 6f 0a 2a 2a 20 74 68 65 20 6e 65 61 72 65 73 74  o.** the nearest
34160 20 73 65 63 6f 6e 64 2e 20 54 68 65 20 6e 75 6d   second. The num
34170 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
34180 6e 64 73 20 6f 66 20 73 6c 65 65 70 20 61 63 74  nds of sleep act
34190 75 61 6c 6c 79 0a 2a 2a 20 72 65 71 75 65 73 74  ually.** request
341a0 65 64 20 66 72 6f 6d 20 74 68 65 20 6f 70 65 72  ed from the oper
341b0 61 74 69 6e 67 20 73 79 73 74 65 6d 20 69 73 20  ating system is 
341c0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
341d0 5e 53 51 4c 69 74 65 20 69 6d 70 6c 65 6d 65 6e  ^SQLite implemen
341e0 74 73 20 74 68 69 73 20 69 6e 74 65 72 66 61 63  ts this interfac
341f0 65 20 62 79 20 63 61 6c 6c 69 6e 67 20 74 68 65  e by calling the
34200 20 78 53 6c 65 65 70 28 29 0a 2a 2a 20 6d 65 74   xSleep().** met
34210 68 6f 64 20 6f 66 20 74 68 65 20 64 65 66 61 75  hod of the defau
34220 6c 74 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d  lt [sqlite3_vfs]
34230 20 6f 62 6a 65 63 74 2e 20 20 49 66 20 74 68 65   object.  If the
34240 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f 64   xSleep() method
34250 0a 2a 2a 20 6f 66 20 74 68 65 20 64 65 66 61 75  .** of the defau
34260 6c 74 20 56 46 53 20 69 73 20 6e 6f 74 20 69 6d  lt VFS is not im
34270 70 6c 65 6d 65 6e 74 65 64 20 63 6f 72 72 65 63  plemented correc
34280 74 6c 79 2c 20 6f 72 20 6e 6f 74 20 69 6d 70 6c  tly, or not impl
34290 65 6d 65 6e 74 65 64 20 61 74 0a 2a 2a 20 61 6c  emented at.** al
342a0 6c 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  l, then the beha
342b0 76 69 6f 72 20 6f 66 20 73 71 6c 69 74 65 33 5f  vior of sqlite3_
342c0 73 6c 65 65 70 28 29 20 6d 61 79 20 64 65 76 69  sleep() may devi
342d0 61 74 65 20 66 72 6f 6d 20 74 68 65 20 64 65 73  ate from the des
342e0 63 72 69 70 74 69 6f 6e 0a 2a 2a 20 69 6e 20 74  cription.** in t
342f0 68 65 20 70 72 65 76 69 6f 75 73 20 70 61 72 61  he previous para
34300 67 72 61 70 68 73 2e 0a 2a 2f 0a 69 6e 74 20 73  graphs..*/.int s
34310 71 6c 69 74 65 33 5f 73 6c 65 65 70 28 69 6e 74  qlite3_sleep(int
34320 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34330 45 46 3a 20 4e 61 6d 65 20 4f 66 20 54 68 65 20  EF: Name Of The 
34340 46 6f 6c 64 65 72 20 48 6f 6c 64 69 6e 67 20 54  Folder Holding T
34350 65 6d 70 6f 72 61 72 79 20 46 69 6c 65 73 0a 2a  emporary Files.*
34360 2a 0a 2a 2a 20 5e 28 49 66 20 74 68 69 73 20 67  *.** ^(If this g
34370 6c 6f 62 61 6c 20 76 61 72 69 61 62 6c 65 20 69  lobal variable i
34380 73 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  s made to point 
34390 74 6f 20 61 20 73 74 72 69 6e 67 20 77 68 69 63  to a string whic
343a0 68 20 69 73 0a 2a 2a 20 74 68 65 20 6e 61 6d 65  h is.** the name
343b0 20 6f 66 20 61 20 66 6f 6c 64 65 72 20 28 61 2e   of a folder (a.
343c0 6b 2e 61 2e 20 64 69 72 65 63 74 6f 72 79 29 2c  k.a. directory),
343d0 20 74 68 65 6e 20 61 6c 6c 20 74 65 6d 70 6f 72   then all tempor
343e0 61 72 79 20 66 69 6c 65 73 0a 2a 2a 20 63 72 65  ary files.** cre
343f0 61 74 65 64 20 62 79 20 53 51 4c 69 74 65 20 77  ated by SQLite w
34400 68 65 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c  hen using a buil
34410 74 2d 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66  t-in [sqlite3_vf
34420 73 20 7c 20 56 46 53 5d 0a 2a 2a 20 77 69 6c 6c  s | VFS].** will
34430 20 62 65 20 70 6c 61 63 65 64 20 69 6e 20 74 68   be placed in th
34440 61 74 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20  at directory.)^ 
34450 20 5e 49 66 20 74 68 69 73 20 76 61 72 69 61 62   ^If this variab
34460 6c 65 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20  le.** is a NULL 
34470 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
34480 4c 69 74 65 20 70 65 72 66 6f 72 6d 73 20 61 20  Lite performs a 
34490 73 65 61 72 63 68 20 66 6f 72 20 61 6e 20 61 70  search for an ap
344a0 70 72 6f 70 72 69 61 74 65 0a 2a 2a 20 74 65 6d  propriate.** tem
344b0 70 6f 72 61 72 79 20 66 69 6c 65 20 64 69 72 65  porary file dire
344c0 63 74 6f 72 79 2e 0a 2a 2a 0a 2a 2a 20 49 74 20  ctory..**.** It 
344d0 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72  is not safe to r
344e0 65 61 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68  ead or modify th
344f0 69 73 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d  is variable in m
34500 6f 72 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20  ore than one.** 
34510 74 68 72 65 61 64 20 61 74 20 61 20 74 69 6d 65  thread at a time
34520 2e 20 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  .  It is not saf
34530 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
34540 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
34550 65 0a 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62  e.** if a [datab
34560 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
34570 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 61 74  is being used at
34580 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69   the same time i
34590 6e 20 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20  n a separate.** 
345a0 74 68 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73  thread..** It is
345b0 20 69 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74   intended that t
345c0 68 69 73 20 76 61 72 69 61 62 6c 65 20 62 65 20  his variable be 
345d0 73 65 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70  set once.** as p
345e0 61 72 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69  art of process i
345f0 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e  nitialization an
34600 64 20 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c  d before any SQL
34610 69 74 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a  ite interface.**
34620 20 72 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62   routines have b
34630 65 65 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74  een called and t
34640 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
34650 65 20 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67  e remain unchang
34660 65 64 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72  ed.** thereafter
34670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 74 65  ..**.** ^The [te
34680 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
34690 72 79 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d  ry pragma] may m
346a0 6f 64 69 66 79 20 74 68 69 73 20 76 61 72 69 61  odify this varia
346b0 62 6c 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a  ble and cause.**
346c0 20 69 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20   it to point to 
346d0 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20  memory obtained 
346e0 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61  from [sqlite3_ma
346f0 6c 6c 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72  lloc].  ^Further
34700 6d 6f 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 74 65  more,.** the [te
34710 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
34720 72 79 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79  ry pragma] alway
34730 73 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  s assumes that a
34740 6e 79 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61  ny string.** tha
34750 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
34760 70 6f 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c  points to is hel
34770 64 20 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61  d in memory obta
34780 69 6e 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73  ined from .** [s
34790 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61  qlite3_malloc] a
347a0 6e 64 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61  nd the pragma ma
347b0 79 20 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65  y attempt to fre
347c0 65 20 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a  e that memory.**
347d0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
347e0 66 72 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c  free]..** Hence,
347f0 20 69 66 20 74 68 69 73 20 76 61 72 69 61 62 6c   if this variabl
34800 65 20 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69  e is modified di
34810 72 65 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69  rectly, either i
34820 74 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d  t should be.** m
34830 61 64 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65  ade NULL or made
34840 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d   to point to mem
34850 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  ory obtained fro
34860 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  m [sqlite3_mallo
34870 63 5d 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68  c].** or else th
34880 65 20 75 73 65 20 6f 66 20 74 68 65 20 5b 74 65  e use of the [te
34890 6d 70 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f  mp_store_directo
348a0 72 79 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c  ry pragma] shoul
348b0 64 20 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f  d be avoided..*/
348c0 0a 53 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63  .SQLITE_EXTERN c
348d0 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 74 65 6d  har *sqlite3_tem
348e0 70 5f 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a  p_directory;../*
348f0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e 61  .** CAPI3REF: Na
34900 6d 65 20 4f 66 20 54 68 65 20 46 6f 6c 64 65 72  me Of The Folder
34910 20 48 6f 6c 64 69 6e 67 20 44 61 74 61 62 61 73   Holding Databas
34920 65 20 46 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28  e Files.**.** ^(
34930 49 66 20 74 68 69 73 20 67 6c 6f 62 61 6c 20 76  If this global v
34940 61 72 69 61 62 6c 65 20 69 73 20 6d 61 64 65 20  ariable is made 
34950 74 6f 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74  to point to a st
34960 72 69 6e 67 20 77 68 69 63 68 20 69 73 0a 2a 2a  ring which is.**
34970 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 66   the name of a f
34980 6f 6c 64 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69  older (a.k.a. di
34990 72 65 63 74 6f 72 79 29 2c 20 74 68 65 6e 20 61  rectory), then a
349a0 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
349b0 73 0a 2a 2a 20 73 70 65 63 69 66 69 65 64 20 77  s.** specified w
349c0 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
349d0 61 74 68 6e 61 6d 65 20 61 6e 64 20 63 72 65 61  athname and crea
349e0 74 65 64 20 6f 72 20 61 63 63 65 73 73 65 64 20  ted or accessed 
349f0 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 77 68 65  by.** SQLite whe
34a00 6e 20 75 73 69 6e 67 20 61 20 62 75 69 6c 74 2d  n using a built-
34a10 69 6e 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  in [sqlite3_vfs 
34a20 7c 20 56 46 53 5d 20 77 69 6c 6c 20 62 65 20 61  | VFS] will be a
34a30 73 73 75 6d 65 64 0a 2a 2a 20 74 6f 20 62 65 20  ssumed.** to be 
34a40 72 65 6c 61 74 69 76 65 20 74 6f 20 74 68 61 74  relative to that
34a50 20 64 69 72 65 63 74 6f 72 79 2e 29 5e 20 5e 49   directory.)^ ^I
34a60 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
34a70 69 73 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69  is a NULL.** poi
34a80 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c 69 74  nter, then SQLit
34a90 65 20 61 73 73 75 6d 65 73 20 74 68 61 74 20 61  e assumes that a
34aa0 6c 6c 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  ll database file
34ab0 73 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 77  s specified.** w
34ac0 69 74 68 20 61 20 72 65 6c 61 74 69 76 65 20 70  ith a relative p
34ad0 61 74 68 6e 61 6d 65 20 61 72 65 20 72 65 6c 61  athname are rela
34ae0 74 69 76 65 20 74 6f 20 74 68 65 20 63 75 72 72  tive to the curr
34af0 65 6e 74 20 64 69 72 65 63 74 6f 72 79 0a 2a 2a  ent directory.**
34b00 20 66 6f 72 20 74 68 65 20 70 72 6f 63 65 73 73   for the process
34b10 2e 0a 2a 2a 0a 2a 2a 20 43 68 61 6e 67 69 6e 67  ..**.** Changing
34b20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
34b30 69 73 20 76 61 72 69 61 62 6c 65 20 77 68 69 6c  is variable whil
34b40 65 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e  e a database con
34b50 6e 65 63 74 69 6f 6e 20 69 73 0a 2a 2a 20 6f 70  nection is.** op
34b60 65 6e 20 63 61 6e 20 72 65 73 75 6c 74 20 69 6e  en can result in
34b70 20 61 20 63 6f 72 72 75 70 74 20 64 61 74 61 62   a corrupt datab
34b80 61 73 65 2e 0a 2a 2a 0a 2a 2a 20 49 74 20 69 73  ase..**.** It is
34b90 20 6e 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61   not safe to rea
34ba0 64 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73  d or modify this
34bb0 20 76 61 72 69 61 62 6c 65 20 69 6e 20 6d 6f 72   variable in mor
34bc0 65 20 74 68 61 6e 20 6f 6e 65 0a 2a 2a 20 74 68  e than one.** th
34bd0 72 65 61 64 20 61 74 20 61 20 74 69 6d 65 2e 20  read at a time. 
34be0 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65 20   It is not safe 
34bf0 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69 66  to read or modif
34c00 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 0a  y this variable.
34c10 2a 2a 20 69 66 20 61 20 5b 64 61 74 61 62 61 73  ** if a [databas
34c20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
34c30 20 62 65 69 6e 67 20 75 73 65 64 20 61 74 20 74   being used at t
34c40 68 65 20 73 61 6d 65 20 74 69 6d 65 20 69 6e 20  he same time in 
34c50 61 20 73 65 70 61 72 61 74 65 0a 2a 2a 20 74 68  a separate.** th
34c60 72 65 61 64 2e 0a 2a 2a 20 49 74 20 69 73 20 69  read..** It is i
34c70 6e 74 65 6e 64 65 64 20 74 68 61 74 20 74 68 69  ntended that thi
34c80 73 20 76 61 72 69 61 62 6c 65 20 62 65 20 73 65  s variable be se
34c90 74 20 6f 6e 63 65 0a 2a 2a 20 61 73 20 70 61 72  t once.** as par
34ca0 74 20 6f 66 20 70 72 6f 63 65 73 73 20 69 6e 69  t of process ini
34cb0 74 69 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 20  tialization and 
34cc0 62 65 66 6f 72 65 20 61 6e 79 20 53 51 4c 69 74  before any SQLit
34cd0 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 72  e interface.** r
34ce0 6f 75 74 69 6e 65 73 20 68 61 76 65 20 62 65 65  outines have bee
34cf0 6e 20 63 61 6c 6c 65 64 20 61 6e 64 20 74 68 61  n called and tha
34d00 74 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  t this variable 
34d10 72 65 6d 61 69 6e 20 75 6e 63 68 61 6e 67 65 64  remain unchanged
34d20 0a 2a 2a 20 74 68 65 72 65 61 66 74 65 72 2e 0a  .** thereafter..
34d30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 64 61 74 61  **.** ^The [data
34d40 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
34d50 20 70 72 61 67 6d 61 5d 20 6d 61 79 20 6d 6f 64   pragma] may mod
34d60 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
34d70 65 20 61 6e 64 20 63 61 75 73 65 0a 2a 2a 20 69  e and cause.** i
34d80 74 20 74 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65  t to point to me
34d90 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64 20 66 72  mory obtained fr
34da0 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  om [sqlite3_mall
34db0 6f 63 5d 2e 20 20 5e 46 75 72 74 68 65 72 6d 6f  oc].  ^Furthermo
34dc0 72 65 2c 0a 2a 2a 20 74 68 65 20 5b 64 61 74 61  re,.** the [data
34dd0 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
34de0 20 70 72 61 67 6d 61 5d 20 61 6c 77 61 79 73 20   pragma] always 
34df0 61 73 73 75 6d 65 73 20 74 68 61 74 20 61 6e 79  assumes that any
34e00 20 73 74 72 69 6e 67 0a 2a 2a 20 74 68 61 74 20   string.** that 
34e10 74 68 69 73 20 76 61 72 69 61 62 6c 65 20 70 6f  this variable po
34e20 69 6e 74 73 20 74 6f 20 69 73 20 68 65 6c 64 20  ints to is held 
34e30 69 6e 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  in memory obtain
34e40 65 64 20 66 72 6f 6d 20 0a 2a 2a 20 5b 73 71 6c  ed from .** [sql
34e50 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d 20 61 6e 64  ite3_malloc] and
34e60 20 74 68 65 20 70 72 61 67 6d 61 20 6d 61 79 20   the pragma may 
34e70 61 74 74 65 6d 70 74 20 74 6f 20 66 72 65 65 20  attempt to free 
34e80 74 68 61 74 20 6d 65 6d 6f 72 79 0a 2a 2a 20 75  that memory.** u
34e90 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
34ea0 65 65 5d 2e 0a 2a 2a 20 48 65 6e 63 65 2c 20 69  ee]..** Hence, i
34eb0 66 20 74 68 69 73 20 76 61 72 69 61 62 6c 65 20  f this variable 
34ec0 69 73 20 6d 6f 64 69 66 69 65 64 20 64 69 72 65  is modified dire
34ed0 63 74 6c 79 2c 20 65 69 74 68 65 72 20 69 74 20  ctly, either it 
34ee0 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 6d 61 64  should be.** mad
34ef0 65 20 4e 55 4c 4c 20 6f 72 20 6d 61 64 65 20 74  e NULL or made t
34f00 6f 20 70 6f 69 6e 74 20 74 6f 20 6d 65 6d 6f 72  o point to memor
34f10 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
34f20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 5d  [sqlite3_malloc]
34f30 0a 2a 2a 20 6f 72 20 65 6c 73 65 20 74 68 65 20  .** or else the 
34f40 75 73 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61  use of the [data
34f50 5f 73 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79  _store_directory
34f60 20 70 72 61 67 6d 61 5d 20 73 68 6f 75 6c 64 20   pragma] should 
34f70 62 65 20 61 76 6f 69 64 65 64 2e 0a 2a 2f 0a 53  be avoided..*/.S
34f80 51 4c 49 54 45 5f 45 58 54 45 52 4e 20 63 68 61  QLITE_EXTERN cha
34f90 72 20 2a 73 71 6c 69 74 65 33 5f 64 61 74 61 5f  r *sqlite3_data_
34fa0 64 69 72 65 63 74 6f 72 79 3b 0a 0a 2f 2a 0a 2a  directory;../*.*
34fb0 2a 20 43 41 50 49 33 52 45 46 3a 20 54 65 73 74  * CAPI3REF: Test
34fc0 20 46 6f 72 20 41 75 74 6f 2d 43 6f 6d 6d 69 74   For Auto-Commit
34fd0 20 4d 6f 64 65 0a 2a 2a 20 4b 45 59 57 4f 52 44   Mode.** KEYWORD
34fe0 53 3a 20 7b 61 75 74 6f 63 6f 6d 6d 69 74 20 6d  S: {autocommit m
34ff0 6f 64 65 7d 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ode}.**.** ^The 
35000 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 74 6f  sqlite3_get_auto
35010 63 6f 6d 6d 69 74 28 29 20 69 6e 74 65 72 66 61  commit() interfa
35020 63 65 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ce returns non-z
35030 65 72 6f 20 6f 72 0a 2a 2a 20 7a 65 72 6f 20 69  ero or.** zero i
35040 66 20 74 68 65 20 67 69 76 65 6e 20 64 61 74 61  f the given data
35050 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
35060 69 73 20 6f 72 20 69 73 20 6e 6f 74 20 69 6e 20  is or is not in 
35070 61 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65 2c  autocommit mode,
35080 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
35090 2e 20 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d  .  ^Autocommit m
350a0 6f 64 65 20 69 73 20 6f 6e 20 62 79 20 64 65 66  ode is on by def
350b0 61 75 6c 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ault..** ^Autoco
350c0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 64 69 73  mmit mode is dis
350d0 61 62 6c 65 64 20 62 79 20 61 20 5b 42 45 47 49  abled by a [BEGI
350e0 4e 5d 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a  N] statement..**
350f0 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
35100 65 20 69 73 20 72 65 2d 65 6e 61 62 6c 65 64 20  e is re-enabled 
35110 62 79 20 61 20 5b 43 4f 4d 4d 49 54 5d 20 6f 72  by a [COMMIT] or
35120 20 5b 52 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 0a   [ROLLBACK]..**.
35130 2a 2a 20 49 66 20 63 65 72 74 61 69 6e 20 6b 69  ** If certain ki
35140 6e 64 73 20 6f 66 20 65 72 72 6f 72 73 20 6f 63  nds of errors oc
35150 63 75 72 20 6f 6e 20 61 20 73 74 61 74 65 6d 65  cur on a stateme
35160 6e 74 20 77 69 74 68 69 6e 20 61 20 6d 75 6c 74  nt within a mult
35170 69 2d 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  i-statement.** t
35180 72 61 6e 73 61 63 74 69 6f 6e 20 28 65 72 72 6f  ransaction (erro
35190 72 73 20 69 6e 63 6c 75 64 69 6e 67 20 5b 53 51  rs including [SQ
351a0 4c 49 54 45 5f 46 55 4c 4c 5d 2c 20 5b 53 51 4c  LITE_FULL], [SQL
351b0 49 54 45 5f 49 4f 45 52 52 5d 2c 0a 2a 2a 20 5b  ITE_IOERR],.** [
351c0 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2c 20 5b  SQLITE_NOMEM], [
351d0 53 51 4c 49 54 45 5f 42 55 53 59 5d 2c 20 61 6e  SQLITE_BUSY], an
351e0 64 20 5b 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  d [SQLITE_INTERR
351f0 55 50 54 5d 29 20 74 68 65 6e 20 74 68 65 0a 2a  UPT]) then the.*
35200 2a 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 6d 69  * transaction mi
35210 67 68 74 20 62 65 20 72 6f 6c 6c 65 64 20 62 61  ght be rolled ba
35220 63 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79  ck automatically
35230 2e 20 20 54 68 65 20 6f 6e 6c 79 20 77 61 79 20  .  The only way 
35240 74 6f 0a 2a 2a 20 66 69 6e 64 20 6f 75 74 20 77  to.** find out w
35250 68 65 74 68 65 72 20 53 51 4c 69 74 65 20 61 75  hether SQLite au
35260 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72 6f 6c 6c  tomatically roll
35270 65 64 20 62 61 63 6b 20 74 68 65 20 74 72 61 6e  ed back the tran
35280 73 61 63 74 69 6f 6e 20 61 66 74 65 72 0a 2a 2a  saction after.**
35290 20 61 6e 20 65 72 72 6f 72 20 69 73 20 74 6f 20   an error is to 
352a0 75 73 65 20 74 68 69 73 20 66 75 6e 63 74 69 6f  use this functio
352b0 6e 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 6f 74  n..**.** If anot
352c0 68 65 72 20 74 68 72 65 61 64 20 63 68 61 6e 67  her thread chang
352d0 65 73 20 74 68 65 20 61 75 74 6f 63 6f 6d 6d 69  es the autocommi
352e0 74 20 73 74 61 74 75 73 20 6f 66 20 74 68 65 20  t status of the 
352f0 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
35300 65 63 74 69 6f 6e 20 77 68 69 6c 65 20 74 68 69  ection while thi
35310 73 20 72 6f 75 74 69 6e 65 20 69 73 20 72 75 6e  s routine is run
35320 6e 69 6e 67 2c 20 74 68 65 6e 20 74 68 65 20 72  ning, then the r
35330 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 69  eturn value.** i
35340 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a  s undefined..*/.
35350 69 6e 74 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  int sqlite3_get_
35360 61 75 74 6f 63 6f 6d 6d 69 74 28 73 71 6c 69 74  autocommit(sqlit
35370 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  e3*);../*.** CAP
35380 49 33 52 45 46 3a 20 46 69 6e 64 20 54 68 65 20  I3REF: Find The 
35390 44 61 74 61 62 61 73 65 20 48 61 6e 64 6c 65 20  Database Handle 
353a0 4f 66 20 41 20 50 72 65 70 61 72 65 64 20 53 74  Of A Prepared St
353b0 61 74 65 6d 65 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54  atement.**.** ^T
353c0 68 65 20 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  he sqlite3_db_ha
353d0 6e 64 6c 65 20 69 6e 74 65 72 66 61 63 65 20 72  ndle interface r
353e0 65 74 75 72 6e 73 20 74 68 65 20 5b 64 61 74 61  eturns the [data
353f0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
35400 20 68 61 6e 64 6c 65 0a 2a 2a 20 74 6f 20 77 68   handle.** to wh
35410 69 63 68 20 61 20 5b 70 72 65 70 61 72 65 64 20  ich a [prepared 
35420 73 74 61 74 65 6d 65 6e 74 5d 20 62 65 6c 6f 6e  statement] belon
35430 67 73 2e 20 20 5e 54 68 65 20 5b 64 61 74 61 62  gs.  ^The [datab
35440 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
35450 2a 2a 20 72 65 74 75 72 6e 65 64 20 62 79 20 73  ** returned by s
35460 71 6c 69 74 65 33 5f 64 62 5f 68 61 6e 64 6c 65  qlite3_db_handle
35470 20 69 73 20 74 68 65 20 73 61 6d 65 20 5b 64 61   is the same [da
35480 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35490 6e 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 74  n].** that was t
354a0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
354b0 74 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c  t.** to the [sql
354c0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
354d0 29 5d 20 63 61 6c 6c 20 28 6f 72 20 69 74 73 20  )] call (or its 
354e0 76 61 72 69 61 6e 74 73 29 20 74 68 61 74 20 77  variants) that w
354f0 61 73 20 75 73 65 64 20 74 6f 0a 2a 2a 20 63 72  as used to.** cr
35500 65 61 74 65 20 74 68 65 20 73 74 61 74 65 6d 65  eate the stateme
35510 6e 74 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  nt in the first 
35520 70 6c 61 63 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  place..*/.sqlite
35530 33 20 2a 73 71 6c 69 74 65 33 5f 64 62 5f 68 61  3 *sqlite3_db_ha
35540 6e 64 6c 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  ndle(sqlite3_stm
35550 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
35560 33 52 45 46 3a 20 52 65 74 75 72 6e 20 54 68 65  3REF: Return The
35570 20 46 69 6c 65 6e 61 6d 65 20 46 6f 72 20 41 20   Filename For A 
35580 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
35590 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ion.**.** ^The s
355a0 71 6c 69 74 65 33 5f 64 62 5f 66 69 6c 65 6e 61  qlite3_db_filena
355b0 6d 65 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  me(D,N) interfac
355c0 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  e returns a poin
355d0 74 65 72 20 74 6f 20 61 20 66 69 6c 65 6e 61 6d  ter to a filenam
355e0 65 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  e.** associated 
355f0 77 69 74 68 20 64 61 74 61 62 61 73 65 20 4e 20  with database N 
35600 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44 2e  of connection D.
35610 20 20 5e 54 68 65 20 6d 61 69 6e 20 64 61 74 61    ^The main data
35620 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 68 61 73  base file.** has
35630 20 74 68 65 20 6e 61 6d 65 20 22 6d 61 69 6e 22   the name "main"
35640 2e 20 20 49 66 20 74 68 65 72 65 20 69 73 20 6e  .  If there is n
35650 6f 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62  o attached datab
35660 61 73 65 20 4e 20 6f 6e 20 74 68 65 20 64 61 74  ase N on the dat
35670 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63 74  abase.** connect
35680 69 6f 6e 20 44 2c 20 6f 72 20 69 66 20 64 61 74  ion D, or if dat
35690 61 62 61 73 65 20 4e 20 69 73 20 61 20 74 65 6d  abase N is a tem
356a0 70 6f 72 61 72 79 20 6f 72 20 69 6e 2d 6d 65 6d  porary or in-mem
356b0 6f 72 79 20 64 61 74 61 62 61 73 65 2c 20 74 68  ory database, th
356c0 65 6e 0a 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69  en.** a NULL poi
356d0 6e 74 65 72 20 69 73 20 72 65 74 75 72 6e 65 64  nter is returned
356e0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 6c  ..**.** ^The fil
356f0 65 6e 61 6d 65 20 72 65 74 75 72 6e 65 64 20 62  ename returned b
35700 79 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  y this function 
35710 69 73 20 74 68 65 20 6f 75 74 70 75 74 20 6f 66  is the output of
35720 20 74 68 65 0a 2a 2a 20 78 46 75 6c 6c 50 61 74   the.** xFullPat
35730 68 6e 61 6d 65 20 6d 65 74 68 6f 64 20 6f 66 20  hname method of 
35740 74 68 65 20 5b 56 46 53 5d 2e 20 20 5e 49 6e 20  the [VFS].  ^In 
35750 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
35760 20 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 77 69 6c   filename.** wil
35770 6c 20 62 65 20 61 6e 20 61 62 73 6f 6c 75 74 65  l be an absolute
35780 20 70 61 74 68 6e 61 6d 65 2c 20 65 76 65 6e 20   pathname, even 
35790 69 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  if the filename 
357a0 75 73 65 64 0a 2a 2a 20 74 6f 20 6f 70 65 6e 20  used.** to open 
357b0 74 68 65 20 64 61 74 61 62 61 73 65 20 6f 72 69  the database ori
357c0 67 69 6e 61 6c 6c 79 20 77 61 73 20 61 20 55 52  ginally was a UR
357d0 49 20 6f 72 20 72 65 6c 61 74 69 76 65 20 70 61  I or relative pa
357e0 74 68 6e 61 6d 65 2e 0a 2a 2f 0a 63 6f 6e 73 74  thname..*/.const
357f0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 64   char *sqlite3_d
35800 62 5f 66 69 6c 65 6e 61 6d 65 28 73 71 6c 69 74  b_filename(sqlit
35810 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74 20 63 68  e3 *db, const ch
35820 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b 0a 0a 2f  ar *zDbName);../
35830 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
35840 65 74 65 72 6d 69 6e 65 20 69 66 20 61 20 64 61  etermine if a da
35850 74 61 62 61 73 65 20 69 73 20 72 65 61 64 2d 6f  tabase is read-o
35860 6e 6c 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nly.**.** ^The s
35870 71 6c 69 74 65 33 5f 64 62 5f 72 65 61 64 6f 6e  qlite3_db_readon
35880 6c 79 28 44 2c 4e 29 20 69 6e 74 65 72 66 61 63  ly(D,N) interfac
35890 65 20 72 65 74 75 72 6e 73 20 31 20 69 66 20 74  e returns 1 if t
358a0 68 65 20 64 61 74 61 62 61 73 65 20 4e 0a 2a 2a  he database N.**
358b0 20 6f 66 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 44   of connection D
358c0 20 69 73 20 72 65 61 64 2d 6f 6e 6c 79 2c 20 30   is read-only, 0
358d0 20 69 66 20 69 74 20 69 73 20 72 65 61 64 2f 77   if it is read/w
358e0 72 69 74 65 2c 20 6f 72 20 2d 31 20 69 66 20 4e  rite, or -1 if N
358f0 20 69 73 20 6e 6f 74 0a 2a 2a 20 74 68 65 20 6e   is not.** the n
35900 61 6d 65 20 6f 66 20 61 20 64 61 74 61 62 61 73  ame of a databas
35910 65 20 6f 6e 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  e on connection 
35920 44 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  D..*/.int sqlite
35930 33 5f 64 62 5f 72 65 61 64 6f 6e 6c 79 28 73 71  3_db_readonly(sq
35940 6c 69 74 65 33 20 2a 64 62 2c 20 63 6f 6e 73 74  lite3 *db, const
35950 20 63 68 61 72 20 2a 7a 44 62 4e 61 6d 65 29 3b   char *zDbName);
35960 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35970 3a 20 46 69 6e 64 20 74 68 65 20 6e 65 78 74 20  : Find the next 
35980 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
35990 6e 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69  nt.**.** ^This i
359a0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
359b0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
359c0 65 20 6e 65 78 74 20 5b 70 72 65 70 61 72 65 64  e next [prepared
359d0 20 73 74 61 74 65 6d 65 6e 74 5d 20 61 66 74 65   statement] afte
359e0 72 0a 2a 2a 20 70 53 74 6d 74 20 61 73 73 6f 63  r.** pStmt assoc
359f0 69 61 74 65 64 20 77 69 74 68 20 74 68 65 20 5b  iated with the [
35a00 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35a10 69 6f 6e 5d 20 70 44 62 2e 20 20 5e 49 66 20 70  ion] pDb.  ^If p
35a20 53 74 6d 74 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20  Stmt is NULL.** 
35a30 74 68 65 6e 20 74 68 69 73 20 69 6e 74 65 72 66  then this interf
35a40 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
35a50 69 6e 74 65 72 20 74 6f 20 74 68 65 20 66 69 72  inter to the fir
35a60 73 74 20 70 72 65 70 61 72 65 64 20 73 74 61 74  st prepared stat
35a70 65 6d 65 6e 74 0a 2a 2a 20 61 73 73 6f 63 69 61  ement.** associa
35a80 74 65 64 20 77 69 74 68 20 74 68 65 20 64 61 74  ted with the dat
35a90 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
35aa0 20 70 44 62 2e 20 20 5e 49 66 20 6e 6f 20 70 72   pDb.  ^If no pr
35ab0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
35ac0 0a 2a 2a 20 73 61 74 69 73 66 69 65 73 20 74 68  .** satisfies th
35ad0 65 20 63 6f 6e 64 69 74 69 6f 6e 73 20 6f 66 20  e conditions of 
35ae0 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20 69 74  this routine, it
35af0 20 72 65 74 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a   returns NULL..*
35b00 2a 0a 2a 2a 20 54 68 65 20 5b 64 61 74 61 62 61  *.** The [databa
35b10 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70  se connection] p
35b20 6f 69 6e 74 65 72 20 44 20 69 6e 20 61 20 63 61  ointer D in a ca
35b30 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ll to.** [sqlite
35b40 33 5f 6e 65 78 74 5f 73 74 6d 74 28 44 2c 53 29  3_next_stmt(D,S)
35b50 5d 20 6d 75 73 74 20 72 65 66 65 72 20 74 6f 20  ] must refer to 
35b60 61 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  an open database
35b70 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 61  .** connection a
35b80 6e 64 20 69 6e 20 70 61 72 74 69 63 75 6c 61 72  nd in particular
35b90 20 6d 75 73 74 20 6e 6f 74 20 62 65 20 61 20 4e   must not be a N
35ba0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a  ULL pointer..*/.
35bb0 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 73 71  sqlite3_stmt *sq
35bc0 6c 69 74 65 33 5f 6e 65 78 74 5f 73 74 6d 74 28  lite3_next_stmt(
35bd0 73 71 6c 69 74 65 33 20 2a 70 44 62 2c 20 73 71  sqlite3 *pDb, sq
35be0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
35bf0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
35c00 52 45 46 3a 20 43 6f 6d 6d 69 74 20 41 6e 64 20  REF: Commit And 
35c10 52 6f 6c 6c 62 61 63 6b 20 4e 6f 74 69 66 69 63  Rollback Notific
35c20 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
35c30 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
35c40 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29  e3_commit_hook()
35c50 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
35c60 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a  ters a callback.
35c70 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ** function to b
35c80 65 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76  e invoked whenev
35c90 65 72 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e  er a transaction
35ca0 20 69 73 20 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f   is [COMMIT | co
35cb0 6d 6d 69 74 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e  mmitted]..** ^An
35cc0 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20 62  y callback set b
35cd0 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61 6c  y a previous cal
35ce0 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6d  l to sqlite3_com
35cf0 6d 69 74 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f  mit_hook().** fo
35d00 72 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  r the same datab
35d10 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
35d20 73 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a  s overridden..**
35d30 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 6f   ^The sqlite3_ro
35d40 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e  llback_hook() in
35d50 74 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72  terface register
35d60 73 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  s a callback.** 
35d70 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69  function to be i
35d80 6e 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20  nvoked whenever 
35d90 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
35da0 20 5b 52 4f 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c   [ROLLBACK | rol
35db0 6c 65 64 20 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41  led back]..** ^A
35dc0 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65 74 20  ny callback set 
35dd0 62 79 20 61 20 70 72 65 76 69 6f 75 73 20 63 61  by a previous ca
35de0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 6f  ll to sqlite3_ro
35df0 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a  llback_hook().**
35e00 20 66 6f 72 20 74 68 65 20 73 61 6d 65 20 64 61   for the same da
35e10 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
35e20 6e 20 69 73 20 6f 76 65 72 72 69 64 64 65 6e 2e  n is overridden.
35e30 0a 2a 2a 20 5e 54 68 65 20 70 41 72 67 20 61 72  .** ^The pArg ar
35e40 67 75 6d 65 6e 74 20 69 73 20 70 61 73 73 65 64  gument is passed
35e50 20 74 68 72 6f 75 67 68 20 74 6f 20 74 68 65 20   through to the 
35e60 63 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66  callback..** ^If
35e70 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 6f 6e   the callback on
35e80 20 61 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66   a commit hook f
35e90 75 6e 63 74 69 6f 6e 20 72 65 74 75 72 6e 73 20  unction returns 
35ea0 6e 6f 6e 2d 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65  non-zero,.** the
35eb0 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 69 73 20  n the commit is 
35ec0 63 6f 6e 76 65 72 74 65 64 20 69 6e 74 6f 20 61  converted into a
35ed0 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a   rollback..**.**
35ee0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
35ef0 6d 6d 69 74 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29  mmit_hook(D,C,P)
35f00 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 6f 6c   and sqlite3_rol
35f10 6c 62 61 63 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50  lback_hook(D,C,P
35f20 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72  ) functions.** r
35f30 65 74 75 72 6e 20 74 68 65 20 50 20 61 72 67 75  eturn the P argu
35f40 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72  ment from the pr
35f50 65 76 69 6f 75 73 20 63 61 6c 6c 20 6f 66 20 74  evious call of t
35f60 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
35f70 0a 2a 2a 20 6f 6e 20 74 68 65 20 73 61 6d 65 20  .** on the same 
35f80 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
35f90 74 69 6f 6e 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c  tion] D, or NULL
35fa0 20 66 6f 72 0a 2a 2a 20 74 68 65 20 66 69 72 73   for.** the firs
35fb0 74 20 63 61 6c 6c 20 66 6f 72 20 65 61 63 68 20  t call for each 
35fc0 66 75 6e 63 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a  function on D..*
35fd0 2a 0a 2a 2a 20 54 68 65 20 63 6f 6d 6d 69 74 20  *.** The commit 
35fe0 61 6e 64 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f  and rollback hoo
35ff0 6b 20 63 61 6c 6c 62 61 63 6b 73 20 61 72 65 20  k callbacks are 
36000 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74 2e 0a 2a  not reentrant..*
36010 2a 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69  * The callback i
36020 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
36030 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
36040 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
36050 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
36060 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
36070 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
36080 63 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61  callback.  Any a
36090 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
360a0 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
360b0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
360c0 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
360d0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
360e0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
360f0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
36100 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
36110 67 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69  ggered the commi
36120 74 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b  t.** or rollback
36130 20 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72   hook in the fir
36140 73 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74  st place..** Not
36150 65 20 74 68 61 74 20 72 75 6e 6e 69 6e 67 20 61  e that running a
36160 6e 79 20 6f 74 68 65 72 20 53 51 4c 20 73 74 61  ny other SQL sta
36170 74 65 6d 65 6e 74 73 2c 20 69 6e 63 6c 75 64 69  tements, includi
36180 6e 67 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d  ng SELECT statem
36190 65 6e 74 73 2c 0a 2a 2a 20 6f 72 20 6d 65 72 65  ents,.** or mere
361a0 6c 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ly calling [sqli
361b0 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
361c0 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73  ] and [sqlite3_s
361d0 74 65 70 28 29 5d 20 77 69 6c 6c 20 6d 6f 64 69  tep()] will modi
361e0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
361f0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66  se connections f
36200 6f 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f  or the meaning o
36210 66 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68  f "modify" in th
36220 69 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a  is paragraph..**
36230 0a 2a 2a 20 5e 52 65 67 69 73 74 65 72 69 6e 67  .** ^Registering
36240 20 61 20 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e   a NULL function
36250 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 61   disables the ca
36260 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57  llback..**.** ^W
36270 68 65 6e 20 74 68 65 20 63 6f 6d 6d 69 74 20 68  hen the commit h
36280 6f 6f 6b 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75  ook callback rou
36290 74 69 6e 65 20 72 65 74 75 72 6e 73 20 7a 65 72  tine returns zer
362a0 6f 2c 20 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a  o, the [COMMIT].
362b0 2a 2a 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20  ** operation is 
362c0 61 6c 6c 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69  allowed to conti
362d0 6e 75 65 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e  nue normally.  ^
362e0 49 66 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f  If the commit ho
362f0 6f 6b 0a 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f  ok.** returns no
36300 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 74 68 65  n-zero, then the
36310 20 5b 43 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e   [COMMIT] is con
36320 76 65 72 74 65 64 20 69 6e 74 6f 20 61 20 5b 52  verted into a [R
36330 4f 4c 4c 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68  OLLBACK]..** ^Th
36340 65 20 72 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20  e rollback hook 
36350 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20  is invoked on a 
36360 72 6f 6c 6c 62 61 63 6b 20 74 68 61 74 20 72 65  rollback that re
36370 73 75 6c 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d  sults from a com
36380 6d 69 74 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75  mit.** hook retu
36390 72 6e 69 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20  rning non-zero, 
363a0 6a 75 73 74 20 61 73 20 69 74 20 77 6f 75 6c 64  just as it would
363b0 20 62 65 20 77 69 74 68 20 61 6e 79 20 6f 74 68   be with any oth
363c0 65 72 20 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a  er rollback..**.
363d0 2a 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70  ** ^For the purp
363e0 6f 73 65 73 20 6f 66 20 74 68 69 73 20 41 50 49  oses of this API
363f0 2c 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  , a transaction 
36400 69 73 20 73 61 69 64 20 74 6f 20 68 61 76 65 20  is said to have 
36410 62 65 65 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62  been.** rolled b
36420 61 63 6b 20 69 66 20 61 6e 20 65 78 70 6c 69 63  ack if an explic
36430 69 74 20 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74  it "ROLLBACK" st
36440 61 74 65 6d 65 6e 74 20 69 73 20 65 78 65 63 75  atement is execu
36450 74 65 64 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72  ted, or.** an er
36460 72 6f 72 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e  ror or constrain
36470 74 20 63 61 75 73 65 73 20 61 6e 20 69 6d 70 6c  t causes an impl
36480 69 63 69 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f  icit rollback to
36490 20 6f 63 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20   occur..** ^The 
364a0 72 6f 6c 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63  rollback callbac
364b0 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64  k is not invoked
364c0 20 69 66 20 61 20 74 72 61 6e 73 61 63 74 69 6f   if a transactio
364d0 6e 20 69 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69  n is.** automati
364e0 63 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63  cally rolled bac
364f0 6b 20 62 65 63 61 75 73 65 20 74 68 65 20 64 61  k because the da
36500 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36510 6e 20 69 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a  n is closed..**.
36520 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20  ** See also the 
36530 5b 73 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f  [sqlite3_update_
36540 68 6f 6f 6b 28 29 5d 20 69 6e 74 65 72 66 61 63  hook()] interfac
36550 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  e..*/.void *sqli
36560 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28  te3_commit_hook(
36570 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29  sqlite3*, int(*)
36580 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b  (void*), void*);
36590 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 72  .void *sqlite3_r
365a0 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c  ollback_hook(sql
365b0 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76  ite3*, void(*)(v
365c0 6f 69 64 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  oid *), void*);.
365d0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
365e0 20 44 61 74 61 20 43 68 61 6e 67 65 20 4e 6f 74   Data Change Not
365f0 69 66 69 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61  ification Callba
36600 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  cks.**.** ^The s
36610 71 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f  qlite3_update_ho
36620 6f 6b 28 29 20 69 6e 74 65 72 66 61 63 65 20 72  ok() interface r
36630 65 67 69 73 74 65 72 73 20 61 20 63 61 6c 6c 62  egisters a callb
36640 61 63 6b 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ack function.** 
36650 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
36660 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69  se connection] i
36670 64 65 6e 74 69 66 69 65 64 20 62 79 20 74 68 65  dentified by the
36680 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 0a   first argument.
36690 2a 2a 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  ** to be invoked
366a0 20 77 68 65 6e 65 76 65 72 20 61 20 72 6f 77 20   whenever a row 
366b0 69 73 20 75 70 64 61 74 65 64 2c 20 69 6e 73 65  is updated, inse
366c0 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64 2e  rted or deleted.
366d0 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63  .** ^Any callbac
366e0 6b 20 73 65 74 20 62 79 20 61 20 70 72 65 76 69  k set by a previ
366f0 6f 75 73 20 63 61 6c 6c 20 74 6f 20 74 68 69 73  ous call to this
36700 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72   function.** for
36710 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
36720 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
36730 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a   overridden..**.
36740 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61  ** ^The second a
36750 72 67 75 6d 65 6e 74 20 69 73 20 61 20 70 6f 69  rgument is a poi
36760 6e 74 65 72 20 74 6f 20 74 68 65 20 66 75 6e 63  nter to the func
36770 74 69 6f 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77  tion to invoke w
36780 68 65 6e 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20  hen a.** row is 
36790 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
367a0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
367b0 20 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75   ^The first argu
367c0 6d 65 6e 74 20 74 6f 20 74 68 65 20 63 61 6c 6c  ment to the call
367d0 62 61 63 6b 20 69 73 20 61 20 63 6f 70 79 20 6f  back is a copy o
367e0 66 20 74 68 65 20 74 68 69 72 64 20 61 72 67 75  f the third argu
367f0 6d 65 6e 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  ment.** to sqlit
36800 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
36810 2e 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64  ..** ^The second
36820 20 63 61 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65   callback argume
36830 6e 74 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51  nt is one of [SQ
36840 4c 49 54 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53  LITE_INSERT], [S
36850 51 4c 49 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a  QLITE_DELETE],.*
36860 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 55 50 44  * or [SQLITE_UPD
36870 41 54 45 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20  ATE], depending 
36880 6f 6e 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e  on the operation
36890 20 74 68 61 74 20 63 61 75 73 65 64 20 74 68 65   that caused the
368a0 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20   callback.** to 
368b0 62 65 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e  be invoked..** ^
368c0 54 68 65 20 74 68 69 72 64 20 61 6e 64 20 66 6f  The third and fo
368d0 75 72 74 68 20 61 72 67 75 6d 65 6e 74 73 20 74  urth arguments t
368e0 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 63  o the callback c
368f0 6f 6e 74 61 69 6e 20 70 6f 69 6e 74 65 72 73 20  ontain pointers 
36900 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  to the.** databa
36910 73 65 20 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d  se and table nam
36920 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
36930 20 61 66 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a   affected row..*
36940 2a 20 5e 54 68 65 20 66 69 6e 61 6c 20 63 61 6c  * ^The final cal
36950 6c 62 61 63 6b 20 70 61 72 61 6d 65 74 65 72 20  lback parameter 
36960 69 73 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f  is the [rowid] o
36970 66 20 74 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49  f the row..** ^I
36980 6e 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e  n the case of an
36990 20 75 70 64 61 74 65 2c 20 74 68 69 73 20 69 73   update, this is
369a0 20 74 68 65 20 5b 72 6f 77 69 64 5d 20 61 66 74   the [rowid] aft
369b0 65 72 20 74 68 65 20 75 70 64 61 74 65 20 74 61  er the update ta
369c0 6b 65 73 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a  kes place..**.**
369d0 20 5e 28 54 68 65 20 75 70 64 61 74 65 20 68 6f   ^(The update ho
369e0 6f 6b 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ok is not invoke
369f0 64 20 77 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20  d when internal 
36a00 73 79 73 74 65 6d 20 74 61 62 6c 65 73 20 61 72  system tables ar
36a10 65 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 20 28 69  e.** modified (i
36a20 2e 65 2e 20 73 71 6c 69 74 65 5f 6d 61 73 74 65  .e. sqlite_maste
36a30 72 20 61 6e 64 20 73 71 6c 69 74 65 5f 73 65 71  r and sqlite_seq
36a40 75 65 6e 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  uence).)^.**.** 
36a50 5e 49 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20  ^In the current 
36a60 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20  implementation, 
36a70 74 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a  the update hook.
36a80 2a 2a 20 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65  ** is not invoke
36a90 64 20 77 68 65 6e 20 64 75 70 6c 69 63 61 74 69  d when duplicati
36aa0 6f 6e 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65  on rows are dele
36ab0 74 65 64 20 62 65 63 61 75 73 65 20 6f 66 20 61  ted because of a
36ac0 6e 0a 2a 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43  n.** [ON CONFLIC
36ad0 54 20 7c 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20  T | ON CONFLICT 
36ae0 52 45 50 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e  REPLACE] clause.
36af0 20 20 5e 4e 6f 72 20 69 73 20 74 68 65 20 75 70    ^Nor is the up
36b00 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76  date hook.** inv
36b10 6f 6b 65 64 20 77 68 65 6e 20 72 6f 77 73 20 61  oked when rows a
36b20 72 65 20 64 65 6c 65 74 65 64 20 75 73 69 6e 67  re deleted using
36b30 20 74 68 65 20 5b 74 72 75 6e 63 61 74 65 20 6f   the [truncate o
36b40 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a  ptimization]..**
36b50 20 54 68 65 20 65 78 63 65 70 74 69 6f 6e 73 20   The exceptions 
36b60 64 65 66 69 6e 65 64 20 69 6e 20 74 68 69 73 20  defined in this 
36b70 70 61 72 61 67 72 61 70 68 20 6d 69 67 68 74 20  paragraph might 
36b80 63 68 61 6e 67 65 20 69 6e 20 61 20 66 75 74 75  change in a futu
36b90 72 65 0a 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66  re.** release of
36ba0 20 53 51 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54   SQLite..**.** T
36bb0 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
36bc0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75  mplementation mu
36bd0 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69  st not do anythi
36be0 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64  ng that will mod
36bf0 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62  ify.** the datab
36c00 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74  ase connection t
36c10 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20  hat invoked the 
36c20 75 70 64 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e  update hook.  An
36c30 79 20 61 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20  y actions.** to 
36c40 6d 6f 64 69 66 79 20 74 68 65 20 64 61 74 61 62  modify the datab
36c50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d  ase connection m
36c60 75 73 74 20 62 65 20 64 65 66 65 72 72 65 64 20  ust be deferred 
36c70 75 6e 74 69 6c 20 61 66 74 65 72 20 74 68 65 0a  until after the.
36c80 2a 2a 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66  ** completion of
36c90 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74   the [sqlite3_st
36ca0 65 70 28 29 5d 20 63 61 6c 6c 20 74 68 61 74 20  ep()] call that 
36cb0 74 72 69 67 67 65 72 65 64 20 74 68 65 20 75 70  triggered the up
36cc0 64 61 74 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f  date hook..** No
36cd0 74 65 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33  te that [sqlite3
36ce0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61  _prepare_v2()] a
36cf0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  nd [sqlite3_step
36d00 28 29 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20  ()] both modify 
36d10 74 68 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73  their.** databas
36d20 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f  e connections fo
36d30 72 20 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66  r the meaning of
36d40 20 22 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69   "modify" in thi
36d50 73 20 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a  s paragraph..**.
36d60 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
36d70 75 70 64 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c  update_hook(D,C,
36d80 50 29 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72  P) function.** r
36d90 65 74 75 72 6e 73 20 74 68 65 20 50 20 61 72 67  eturns the P arg
36da0 75 6d 65 6e 74 20 66 72 6f 6d 20 74 68 65 20 70  ument from the p
36db0 72 65 76 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20  revious call.** 
36dc0 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
36dd0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36de0 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
36df0 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
36e00 6c 6c 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53  ll on D..**.** S
36e10 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
36e20 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b  ite3_commit_hook
36e30 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
36e40 5f 72 6f 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29  _rollback_hook()
36e50 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2e  ].** interfaces.
36e60 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
36e70 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20  3_update_hook(. 
36e80 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f   sqlite3*, .  vo
36e90 69 64 28 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74  id(*)(void *,int
36ea0 20 2c 63 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63   ,char const *,c
36eb0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69  har const *,sqli
36ec0 74 65 33 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f  te3_int64),.  vo
36ed0 69 64 2a 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  id*.);../*.** CA
36ee0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
36ef0 72 20 44 69 73 61 62 6c 65 20 53 68 61 72 65 64  r Disable Shared
36f00 20 50 61 67 65 72 20 43 61 63 68 65 0a 2a 2a 20   Pager Cache.** 
36f10 4b 45 59 57 4f 52 44 53 3a 20 7b 73 68 61 72 65  KEYWORDS: {share
36f20 64 20 63 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e  d cache}.**.** ^
36f30 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 65 6e  (This routine en
36f40 61 62 6c 65 73 20 6f 72 20 64 69 73 61 62 6c 65  ables or disable
36f50 73 20 74 68 65 20 73 68 61 72 69 6e 67 20 6f 66  s the sharing of
36f60 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63 61   the database ca
36f70 63 68 65 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d  che.** and schem
36f80 61 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  a data structure
36f90 73 20 62 65 74 77 65 65 6e 20 5b 64 61 74 61 62  s between [datab
36fa0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c  ase connection |
36fb0 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a   connections].**
36fc0 20 74 6f 20 74 68 65 20 73 61 6d 65 20 64 61 74   to the same dat
36fd0 61 62 61 73 65 2e 20 53 68 61 72 69 6e 67 20 69  abase. Sharing i
36fe0 73 20 65 6e 61 62 6c 65 64 20 69 66 20 74 68 65  s enabled if the
36ff0 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 72 75   argument is tru
37000 65 0a 2a 2a 20 61 6e 64 20 64 69 73 61 62 6c 65  e.** and disable
37010 64 20 69 66 20 74 68 65 20 61 72 67 75 6d 65 6e  d if the argumen
37020 74 20 69 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a  t is false.)^.**
37030 0a 2a 2a 20 5e 43 61 63 68 65 20 73 68 61 72 69  .** ^Cache shari
37040 6e 67 20 69 73 20 65 6e 61 62 6c 65 64 20 61 6e  ng is enabled an
37050 64 20 64 69 73 61 62 6c 65 64 20 66 6f 72 20 61  d disabled for a
37060 6e 20 65 6e 74 69 72 65 20 70 72 6f 63 65 73 73  n entire process
37070 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 63  ..** This is a c
37080 68 61 6e 67 65 20 61 73 20 6f 66 20 53 51 4c 69  hange as of SQLi
37090 74 65 20 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30  te version 3.5.0
370a0 2e 20 49 6e 20 70 72 69 6f 72 20 76 65 72 73 69  . In prior versi
370b0 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a  ons of SQLite,.*
370c0 2a 20 73 68 61 72 69 6e 67 20 77 61 73 20 65 6e  * sharing was en
370d0 61 62 6c 65 64 20 6f 72 20 64 69 73 61 62 6c 65  abled or disable
370e0 64 20 66 6f 72 20 65 61 63 68 20 74 68 72 65 61  d for each threa
370f0 64 20 73 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a  d separately..**
37100 0a 2a 2a 20 5e 28 54 68 65 20 63 61 63 68 65 20  .** ^(The cache 
37110 73 68 61 72 69 6e 67 20 6d 6f 64 65 20 73 65 74  sharing mode set
37120 20 62 79 20 74 68 69 73 20 69 6e 74 65 72 66 61   by this interfa
37130 63 65 20 65 66 66 65 63 74 73 20 61 6c 6c 20 73  ce effects all s
37140 75 62 73 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c  ubsequent.** cal
37150 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f  ls to [sqlite3_o
37160 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  pen()], [sqlite3
37170 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64  _open_v2()], and
37180 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
37190 28 29 5d 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67  ()]..** Existing
371a0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
371b0 74 69 6f 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75  tions continue u
371c0 73 65 20 74 68 65 20 73 68 61 72 69 6e 67 20 6d  se the sharing m
371d0 6f 64 65 0a 2a 2a 20 74 68 61 74 20 77 61 73 20  ode.** that was 
371e0 69 6e 20 65 66 66 65 63 74 20 61 74 20 74 68 65  in effect at the
371f0 20 74 69 6d 65 20 74 68 65 79 20 77 65 72 65 20   time they were 
37200 6f 70 65 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  opened.)^.**.** 
37210 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72  ^(This routine r
37220 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f  eturns [SQLITE_O
37230 4b 5d 20 69 66 20 73 68 61 72 65 64 20 63 61 63  K] if shared cac
37240 68 65 20 77 61 73 20 65 6e 61 62 6c 65 64 20 6f  he was enabled o
37250 72 20 64 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75  r disabled.** su
37260 63 63 65 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20  ccessfully.  An 
37270 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20  [error code] is 
37280 72 65 74 75 72 6e 65 64 20 6f 74 68 65 72 77 69  returned otherwi
37290 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61  se.)^.**.** ^Sha
372a0 72 65 64 20 63 61 63 68 65 20 69 73 20 64 69 73  red cache is dis
372b0 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
372c0 2e 20 42 75 74 20 74 68 69 73 20 6d 69 67 68 74  . But this might
372d0 20 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75   change in.** fu
372e0 74 75 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66  ture releases of
372f0 20 53 51 4c 69 74 65 2e 20 20 41 70 70 6c 69 63   SQLite.  Applic
37300 61 74 69 6f 6e 73 20 74 68 61 74 20 63 61 72 65  ations that care
37310 20 61 62 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a   about shared.**
37320 20 63 61 63 68 65 20 73 65 74 74 69 6e 67 20 73   cache setting s
37330 68 6f 75 6c 64 20 73 65 74 20 69 74 20 65 78 70  hould set it exp
37340 6c 69 63 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53  licitly..**.** S
37350 65 65 20 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74  ee Also:  [SQLit
37360 65 20 53 68 61 72 65 64 2d 43 61 63 68 65 20 4d  e Shared-Cache M
37370 6f 64 65 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ode].*/.int sqli
37380 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65  te3_enable_share
37390 64 5f 63 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f  d_cache(int);../
373a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 41  *.** CAPI3REF: A
373b0 74 74 65 6d 70 74 20 54 6f 20 46 72 65 65 20 48  ttempt To Free H
373c0 65 61 70 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a  eap Memory.**.**
373d0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
373e0 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69  lease_memory() i
373f0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
37400 73 20 74 6f 20 66 72 65 65 20 4e 20 62 79 74 65  s to free N byte
37410 73 0a 2a 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d  s.** of heap mem
37420 6f 72 79 20 62 79 20 64 65 61 6c 6c 6f 63 61 74  ory by deallocat
37430 69 6e 67 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61  ing non-essentia
37440 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  l memory allocat
37450 69 6f 6e 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20  ions.** held by 
37460 74 68 65 20 64 61 74 61 62 61 73 65 20 6c 69 62  the database lib
37470 72 61 72 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75  rary.   Memory u
37480 73 65 64 20 74 6f 20 63 61 63 68 65 20 64 61 74  sed to cache dat
37490 61 62 61 73 65 0a 2a 2a 20 70 61 67 65 73 20 74  abase.** pages t
374a0 6f 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f 72  o improve perfor
374b0 6d 61 6e 63 65 20 69 73 20 61 6e 20 65 78 61 6d  mance is an exam
374c0 70 6c 65 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e  ple of non-essen
374d0 74 69 61 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20  tial memory..** 
374e0 5e 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73 65  ^sqlite3_release
374f0 5f 6d 65 6d 6f 72 79 28 29 20 72 65 74 75 72 6e  _memory() return
37500 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  s the number of 
37510 62 79 74 65 73 20 61 63 74 75 61 6c 6c 79 20 66  bytes actually f
37520 72 65 65 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d  reed,.** which m
37530 69 67 68 74 20 62 65 20 6d 6f 72 65 20 6f 72 20  ight be more or 
37540 6c 65 73 73 20 74 68 61 6e 20 74 68 65 20 61 6d  less than the am
37550 6f 75 6e 74 20 72 65 71 75 65 73 74 65 64 2e 0a  ount requested..
37560 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
37570 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29  release_memory()
37580 20 72 6f 75 74 69 6e 65 20 69 73 20 61 20 6e 6f   routine is a no
37590 2d 6f 70 20 72 65 74 75 72 6e 69 6e 67 20 7a 65  -op returning ze
375a0 72 6f 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  ro.** if SQLite 
375b0 69 73 20 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20  is not compiled 
375c0 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41  with [SQLITE_ENA
375d0 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47  BLE_MEMORY_MANAG
375e0 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  EMENT]..**.** Se
375f0 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
37600 5f 64 62 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  _db_release_memo
37610 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ry()].*/.int sql
37620 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
37630 6f 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  ory(int);../*.**
37640 20 43 41 50 49 33 52 45 46 3a 20 46 72 65 65 20   CAPI3REF: Free 
37650 4d 65 6d 6f 72 79 20 55 73 65 64 20 42 79 20 41  Memory Used By A
37660 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
37670 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  tion.**.** ^The 
37680 73 71 6c 69 74 65 33 5f 64 62 5f 72 65 6c 65 61  sqlite3_db_relea
37690 73 65 5f 6d 65 6d 6f 72 79 28 44 29 20 69 6e 74  se_memory(D) int
376a0 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20  erface attempts 
376b0 74 6f 20 66 72 65 65 20 61 73 20 6d 75 63 68 20  to free as much 
376c0 68 65 61 70 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61  heap.** memory a
376d0 73 20 70 6f 73 73 69 62 6c 65 20 66 72 6f 6d 20  s possible from 
376e0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
376f0 69 6f 6e 20 44 2e 20 55 6e 6c 69 6b 65 20 74 68  ion D. Unlike th
37700 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65  e.** [sqlite3_re
37710 6c 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 5d 20  lease_memory()] 
37720 69 6e 74 65 72 66 61 63 65 2c 20 74 68 69 73 20  interface, this 
37730 69 6e 74 65 72 66 61 63 65 20 69 73 20 65 66 66  interface is eff
37740 65 63 74 20 65 76 65 6e 0a 2a 2a 20 77 68 65 6e  ect even.** when
37750 20 74 68 65 6e 20 5b 53 51 4c 49 54 45 5f 45 4e   then [SQLITE_EN
37760 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41  ABLE_MEMORY_MANA
37770 47 45 4d 45 4e 54 5d 20 63 6f 6d 70 69 6c 65 2d  GEMENT] compile-
37780 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  time option is.*
37790 2a 20 6f 6d 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a  * omitted..**.**
377a0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
377b0 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
377c0 72 79 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ry()].*/.int sql
377d0 69 74 65 33 5f 64 62 5f 72 65 6c 65 61 73 65 5f  ite3_db_release_
377e0 6d 65 6d 6f 72 79 28 73 71 6c 69 74 65 33 2a 29  memory(sqlite3*)
377f0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
37800 46 3a 20 49 6d 70 6f 73 65 20 41 20 4c 69 6d 69  F: Impose A Limi
37810 74 20 4f 6e 20 48 65 61 70 20 53 69 7a 65 0a 2a  t On Heap Size.*
37820 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
37830 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
37840 74 36 34 28 29 20 69 6e 74 65 72 66 61 63 65 20  t64() interface 
37850 73 65 74 73 20 61 6e 64 2f 6f 72 20 71 75 65 72  sets and/or quer
37860 69 65 73 20 74 68 65 0a 2a 2a 20 73 6f 66 74 20  ies the.** soft 
37870 6c 69 6d 69 74 20 6f 6e 20 74 68 65 20 61 6d 6f  limit on the amo
37880 75 6e 74 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f  unt of heap memo
37890 72 79 20 74 68 61 74 20 6d 61 79 20 62 65 20 61  ry that may be a
378a0 6c 6c 6f 63 61 74 65 64 20 62 79 20 53 51 4c 69  llocated by SQLi
378b0 74 65 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 73  te..** ^SQLite s
378c0 74 72 69 76 65 73 20 74 6f 20 6b 65 65 70 20 68  trives to keep h
378d0 65 61 70 20 6d 65 6d 6f 72 79 20 75 74 69 6c 69  eap memory utili
378e0 7a 61 74 69 6f 6e 20 62 65 6c 6f 77 20 74 68 65  zation below the
378f0 20 73 6f 66 74 20 68 65 61 70 0a 2a 2a 20 6c 69   soft heap.** li
37900 6d 69 74 20 62 79 20 72 65 64 75 63 69 6e 67 20  mit by reducing 
37910 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 70 61  the number of pa
37920 67 65 73 20 68 65 6c 64 20 69 6e 20 74 68 65 20  ges held in the 
37930 70 61 67 65 20 63 61 63 68 65 0a 2a 2a 20 61 73  page cache.** as
37940 20 68 65 61 70 20 6d 65 6d 6f 72 79 20 75 73 61   heap memory usa
37950 67 65 73 20 61 70 70 72 6f 61 63 68 65 73 20 74  ges approaches t
37960 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 54 68  he limit..** ^Th
37970 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37980 74 20 69 73 20 22 73 6f 66 74 22 20 62 65 63 61  t is "soft" beca
37990 75 73 65 20 65 76 65 6e 20 74 68 6f 75 67 68 20  use even though 
379a0 53 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74  SQLite strives t
379b0 6f 20 73 74 61 79 0a 2a 2a 20 62 65 6c 6f 77 20  o stay.** below 
379c0 74 68 65 20 6c 69 6d 69 74 2c 20 69 74 20 77 69  the limit, it wi
379d0 6c 6c 20 65 78 63 65 65 64 20 74 68 65 20 6c 69  ll exceed the li
379e0 6d 69 74 20 72 61 74 68 65 72 20 74 68 61 6e 20  mit rather than 
379f0 67 65 6e 65 72 61 74 65 0a 2a 2a 20 61 6e 20 5b  generate.** an [
37a00 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 20 65 72  SQLITE_NOMEM] er
37a10 72 6f 72 2e 20 20 49 6e 20 6f 74 68 65 72 20 77  ror.  In other w
37a20 6f 72 64 73 2c 20 74 68 65 20 73 6f 66 74 20 68  ords, the soft h
37a30 65 61 70 20 6c 69 6d 69 74 20 0a 2a 2a 20 69 73  eap limit .** is
37a40 20 61 64 76 69 73 6f 72 79 20 6f 6e 6c 79 2e 0a   advisory only..
37a50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65 74 75 72  **.** ^The retur
37a60 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73 71 6c  n value from sql
37a70 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c  ite3_soft_heap_l
37a80 69 6d 69 74 36 34 28 29 20 69 73 20 74 68 65 20  imit64() is the 
37a90 73 69 7a 65 20 6f 66 0a 2a 2a 20 74 68 65 20 73  size of.** the s
37aa0 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 70  oft heap limit p
37ab0 72 69 6f 72 20 74 6f 20 74 68 65 20 63 61 6c 6c  rior to the call
37ac0 2c 20 6f 72 20 6e 65 67 61 74 69 76 65 20 69 6e  , or negative in
37ad0 20 74 68 65 20 63 61 73 65 20 6f 66 20 61 6e 0a   the case of an.
37ae0 2a 2a 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74  ** error.  ^If t
37af0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
37b00 20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65   negative.** the
37b10 6e 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d  n no change is m
37b20 61 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20  ade to the soft 
37b30 68 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e  heap limit.  Hen
37b40 63 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a  ce, the current.
37b50 2a 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73  ** size of the s
37b60 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63  oft heap limit c
37b70 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64  an be determined
37b80 20 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20   by invoking.** 
37b90 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
37ba0 70 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68  p_limit64() with
37bb0 20 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75   a negative argu
37bc0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ment..**.** ^If 
37bd0 74 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69  the argument N i
37be0 73 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20  s zero then the 
37bf0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
37c00 69 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a  is disabled..**.
37c10 2a 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65  ** ^(The soft he
37c20 61 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20  ap limit is not 
37c30 65 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20  enforced in the 
37c40 63 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e  current implemen
37c50 74 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65  tation.** if one
37c60 20 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c   or more of foll
37c70 6f 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73  owing conditions
37c80 20 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a   are true:.**.**
37c90 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68   <ul>.** <li> Th
37ca0 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69  e soft heap limi
37cb0 74 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f  t is set to zero
37cc0 2e 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79  ..** <li> Memory
37cd0 20 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64   accounting is d
37ce0 69 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20  isabled using a 
37cf0 63 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74  combination of t
37d00 68 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69  he.**      [sqli
37d10 74 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c  te3_config]([SQL
37d20 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
37d30 41 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74  ATUS],...) start
37d40 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64  -time option and
37d50 0a 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51  .**      the [SQ
37d60 4c 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d  LITE_DEFAULT_MEM
37d70 53 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d  STATUS] compile-
37d80 74 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20  time option..** 
37d90 3c 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74  <li> An alternat
37da0 69 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69  ive page cache i
37db0 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73  mplementation is
37dc0 20 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67   specified using
37dd0 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
37de0 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
37df0 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 32  E_CONFIG_PCACHE2
37e00 5d 2c 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20  ],...)..** <li> 
37e10 54 68 65 20 70 61 67 65 20 63 61 63 68 65 20 61  The page cache a
37e20 6c 6c 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74  llocates from it
37e30 73 20 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f  s own memory poo
37e40 6c 20 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20  l supplied.**   
37e50 20 20 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63     by [sqlite3_c
37e60 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43  onfig]([SQLITE_C
37e70 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
37e80 2c 2e 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61  ,...) rather tha
37e90 6e 0a 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74  n.**      from t
37ea0 68 65 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c  he heap..** </ul
37eb0 3e 29 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e  >)^.**.** Beginn
37ec0 69 6e 67 20 77 69 74 68 20 53 51 4c 69 74 65 20  ing with SQLite 
37ed0 76 65 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74  version 3.7.3, t
37ee0 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
37ef0 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a  it is enforced.*
37f00 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20  * regardless of 
37f10 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74  whether or not t
37f20 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  he [SQLITE_ENABL
37f30 45 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d  E_MEMORY_MANAGEM
37f40 45 4e 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d  ENT].** compile-
37f50 74 69 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69  time option is i
37f60 6e 76 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53  nvoked.  With [S
37f70 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
37f80 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c  ORY_MANAGEMENT],
37f90 0a 2a 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61  .** the soft hea
37fa0 70 20 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72  p limit is enfor
37fb0 63 65 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d  ced on every mem
37fc0 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20  ory allocation. 
37fd0 20 57 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c   Without.** [SQL
37fe0 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
37ff0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74  Y_MANAGEMENT], t
38000 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d  he soft heap lim
38010 69 74 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72  it is only enfor
38020 63 65 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f  ced.** when memo
38030 72 79 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20  ry is allocated 
38040 62 79 20 74 68 65 20 70 61 67 65 20 63 61 63 68  by the page cach
38050 65 2e 20 20 54 65 73 74 69 6e 67 20 73 75 67 67  e.  Testing sugg
38060 65 73 74 73 20 74 68 61 74 20 62 65 63 61 75 73  ests that becaus
38070 65 0a 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61  e.** the page ca
38080 63 68 65 20 69 73 20 74 68 65 20 70 72 65 64 6f  che is the predo
38090 6d 69 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73  minate memory us
380a0 65 72 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f  er in SQLite, mo
380b0 73 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f  st.** applicatio
380c0 6e 73 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20  ns will achieve 
380d0 61 64 65 71 75 61 74 65 20 73 6f 66 74 20 68 65  adequate soft he
380e0 61 70 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65  ap limit enforce
380f0 6d 65 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20  ment without.** 
38100 74 68 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49  the use of [SQLI
38110 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
38120 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a  _MANAGEMENT]..**
38130 0a 2a 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74  .** The circumst
38140 61 6e 63 65 73 20 75 6e 64 65 72 20 77 68 69 63  ances under whic
38150 68 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e  h SQLite will en
38160 66 6f 72 63 65 20 74 68 65 20 73 6f 66 74 20 68  force the soft h
38170 65 61 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a  eap limit may.**
38180 20 63 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75   changes in futu
38190 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
381a0 51 4c 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65  QLite..*/.sqlite
381b0 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
381c0 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36  soft_heap_limit6
381d0 34 28 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  4(sqlite3_int64 
381e0 4e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  N);../*.** CAPI3
381f0 52 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20  REF: Deprecated 
38200 53 6f 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20  Soft Heap Limit 
38210 49 6e 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50  Interface.** DEP
38220 52 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68  RECATED.**.** Th
38230 69 73 20 69 73 20 61 20 64 65 70 72 65 63 61 74  is is a deprecat
38240 65 64 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68  ed version of th
38250 65 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  e [sqlite3_soft_
38260 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a  heap_limit64()].
38270 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54  ** interface.  T
38280 68 69 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70  his routine is p
38290 72 6f 76 69 64 65 64 20 66 6f 72 20 68 69 73 74  rovided for hist
382a0 6f 72 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69  orical compatibi
382b0 6c 69 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41  lity.** only.  A
382c0 6c 6c 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69  ll new applicati
382d0 6f 6e 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74  ons should use t
382e0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73  he.** [sqlite3_s
382f0 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34  oft_heap_limit64
38300 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61  ()] interface ra
38310 74 68 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f  ther than this o
38320 6e 65 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45  ne..*/.SQLITE_DE
38330 50 52 45 43 41 54 45 44 20 76 6f 69 64 20 73 71  PRECATED void sq
38340 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
38350 6c 69 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a  limit(int N);...
38360 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
38370 45 78 74 72 61 63 74 20 4d 65 74 61 64 61 74 61  Extract Metadata
38380 20 41 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20   About A Column 
38390 4f 66 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a  Of A Table.**.**
383a0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
383b0 65 74 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20  eturns metadata 
383c0 61 62 6f 75 74 20 61 20 73 70 65 63 69 66 69 63  about a specific
383d0 20 63 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65   column of a spe
383e0 63 69 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73  cific.** databas
383f0 65 20 74 61 62 6c 65 20 61 63 63 65 73 73 69 62  e table accessib
38400 6c 65 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61  le using the [da
38410 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
38420 6e 5d 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73  n] handle.** pas
38430 73 65 64 20 61 73 20 74 68 65 20 66 69 72 73 74  sed as the first
38440 20 66 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65   function argume
38450 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63  nt..**.** ^The c
38460 6f 6c 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66  olumn is identif
38470 69 65 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e  ied by the secon
38480 64 2c 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75  d, third and fou
38490 72 74 68 20 70 61 72 61 6d 65 74 65 72 73 20 74  rth parameters t
384a0 6f 0a 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69  o.** this functi
384b0 6f 6e 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  on. ^The second 
384c0 70 61 72 61 6d 65 74 65 72 20 69 73 20 65 69 74  parameter is eit
384d0 68 65 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  her the name of 
384e0 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
384f0 28 69 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74  (i.e. "main", "t
38500 65 6d 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61  emp", or an atta
38510 63 68 65 64 20 64 61 74 61 62 61 73 65 29 20 63  ched database) c
38520 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70  ontaining the sp
38530 65 63 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65  ecified.** table
38540 20 6f 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74   or NULL. ^If it
38550 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61   is NULL, then a
38560 6c 6c 20 61 74 74 61 63 68 65 64 20 64 61 74 61  ll attached data
38570 62 61 73 65 73 20 61 72 65 20 73 65 61 72 63 68  bases are search
38580 65 64 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61  ed.** for the ta
38590 62 6c 65 20 75 73 69 6e 67 20 74 68 65 20 73 61  ble using the sa
385a0 6d 65 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65  me algorithm use
385b0 64 20 62 79 20 74 68 65 20 64 61 74 61 62 61 73  d by the databas
385c0 65 20 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72  e engine to.** r
385d0 65 73 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69  esolve unqualifi
385e0 65 64 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e  ed table referen
385f0 63 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ces..**.** ^The 
38600 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
38610 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
38620 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65  his function are
38630 20 74 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63   the table and c
38640 6f 6c 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66  olumn.** name of
38650 20 74 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c   the desired col
38660 75 6d 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c  umn, respectivel
38670 79 2e 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68  y. Neither of th
38680 65 73 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  ese parameters.*
38690 2a 20 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a  * may be NULL..*
386a0 2a 0a 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69  *.** ^Metadata i
386b0 73 20 72 65 74 75 72 6e 65 64 20 62 79 20 77 72  s returned by wr
386c0 69 74 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d  iting to the mem
386d0 6f 72 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61  ory locations pa
386e0 73 73 65 64 20 61 73 20 74 68 65 20 35 74 68 0a  ssed as the 5th.
386f0 2a 2a 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e  ** and subsequen
38700 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20  t parameters to 
38710 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e  this function. ^
38720 41 6e 79 20 6f 66 20 74 68 65 73 65 20 61 72 67  Any of these arg
38730 75 6d 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a  uments may be.**
38740 20 4e 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20   NULL, in which 
38750 63 61 73 65 20 74 68 65 20 63 6f 72 72 65 73 70  case the corresp
38760 6f 6e 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f  onding element o
38770 66 20 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d  f metadata is om
38780 69 74 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c  itted..**.** ^(<
38790 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
387a0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
387b0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61  >.** <tr><th> Pa
387c0 72 61 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74  rameter <th> Out
387d0 70 75 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e  put<br>Type <th>
387e0 20 20 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a    Description.**
387f0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68  .** <tr><td> 5th
38800 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
38810 2a 20 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65  * <td> Data type
38820 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68  .** <tr><td> 6th
38830 20 3c 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72   <td> const char
38840 2a 20 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64  * <td> Name of d
38850 65 66 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e  efau