/ Hex Artifact Content
Login

Artifact 55fe75ae0d2ee71c33283bae647443c8ec8400be:


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 6d 75 74 65 78 69 6e 67 20 63 6f  iled mutexing co
1be0: 64 65 20 6f 6d 69 74 74 65 64 20 64 75 65 20 74  de omitted due t
1bf0: 6f 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  o the.** [SQLITE
1c00: 5f 54 48 52 45 41 44 53 41 46 45 5d 20 63 6f 6d  _THREADSAFE] com
1c10: 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e  pile-time option
1c20: 20 62 65 69 6e 67 20 73 65 74 20 74 6f 20 30 2e   being set to 0.
1c30: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 61  .**.** SQLite ca
1c40: 6e 20 62 65 20 63 6f 6d 70 69 6c 65 64 20 77 69  n be compiled wi
1c50: 74 68 20 6f 72 20 77 69 74 68 6f 75 74 20 6d 75  th or without mu
1c60: 74 65 78 65 73 2e 20 20 57 68 65 6e 0a 2a 2a 20  texes.  When.** 
1c70: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
1c80: 41 44 53 41 46 45 5d 20 43 20 70 72 65 70 72 6f  ADSAFE] C prepro
1c90: 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 69 73 20  cessor macro is 
1ca0: 31 20 6f 72 20 32 2c 20 6d 75 74 65 78 65 73 0a  1 or 2, mutexes.
1cb0: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 61  ** are enabled a
1cc0: 6e 64 20 53 51 4c 69 74 65 20 69 73 20 74 68 72  nd SQLite is thr
1cd0: 65 61 64 73 61 66 65 2e 20 20 57 68 65 6e 20 74  eadsafe.  When t
1ce0: 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 54 48  he.** [SQLITE_TH
1cf0: 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f 20  READSAFE] macro 
1d00: 69 73 20 30 2c 20 0a 2a 2a 20 74 68 65 20 6d 75  is 0, .** the mu
1d10: 74 65 78 65 73 20 61 72 65 20 6f 6d 69 74 74 65  texes are omitte
1d20: 64 2e 20 20 57 69 74 68 6f 75 74 20 74 68 65 20  d.  Without the 
1d30: 6d 75 74 65 78 65 73 2c 20 69 74 20 69 73 20 6e  mutexes, it is n
1d40: 6f 74 20 73 61 66 65 0a 2a 2a 20 74 6f 20 75 73  ot safe.** to us
1d50: 65 20 53 51 4c 69 74 65 20 63 6f 6e 63 75 72 72  e SQLite concurr
1d60: 65 6e 74 6c 79 20 66 72 6f 6d 20 6d 6f 72 65 20  ently from more 
1d70: 74 68 61 6e 20 6f 6e 65 20 74 68 72 65 61 64 2e  than one thread.
1d80: 0a 2a 2a 0a 2a 2a 20 45 6e 61 62 6c 69 6e 67 20  .**.** Enabling 
1d90: 6d 75 74 65 78 65 73 20 69 6e 63 75 72 73 20 61  mutexes incurs a
1da0: 20 6d 65 61 73 75 72 61 62 6c 65 20 70 65 72 66   measurable perf
1db0: 6f 72 6d 61 6e 63 65 20 70 65 6e 61 6c 74 79 2e  ormance penalty.
1dc0: 0a 2a 2a 20 53 6f 20 69 66 20 73 70 65 65 64 20  .** So if speed 
1dd0: 69 73 20 6f 66 20 75 74 6d 6f 73 74 20 69 6d 70  is of utmost imp
1de0: 6f 72 74 61 6e 63 65 2c 20 69 74 20 6d 61 6b 65  ortance, it make
1df0: 73 20 73 65 6e 73 65 20 74 6f 20 64 69 73 61 62  s sense to disab
1e00: 6c 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 65  le.** the mutexe
1e10: 73 2e 20 20 42 75 74 20 66 6f 72 20 6d 61 78 69  s.  But for maxi
1e20: 6d 75 6d 20 73 61 66 65 74 79 2c 20 6d 75 74 65  mum safety, mute
1e30: 78 65 73 20 73 68 6f 75 6c 64 20 62 65 20 65 6e  xes should be en
1e40: 61 62 6c 65 64 2e 0a 2a 2a 20 5e 54 68 65 20 64  abled..** ^The d
1e50: 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72 20  efault behavior 
1e60: 69 73 20 66 6f 72 20 6d 75 74 65 78 65 73 20 74  is for mutexes t
1e70: 6f 20 62 65 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a  o be enabled..**
1e80: 0a 2a 2a 20 54 68 69 73 20 69 6e 74 65 72 66 61  .** This interfa
1e90: 63 65 20 63 61 6e 20 62 65 20 75 73 65 64 20 62  ce can be used b
1ea0: 79 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  y an application
1eb0: 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68   to make sure th
1ec0: 61 74 20 74 68 65 0a 2a 2a 20 76 65 72 73 69 6f  at the.** versio
1ed0: 6e 20 6f 66 20 53 51 4c 69 74 65 20 74 68 61 74  n of SQLite that
1ee0: 20 69 74 20 69 73 20 6c 69 6e 6b 69 6e 67 20 61   it is linking a
1ef0: 67 61 69 6e 73 74 20 77 61 73 20 63 6f 6d 70 69  gainst was compi
1f00: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
1f10: 64 65 73 69 72 65 64 20 73 65 74 74 69 6e 67 20  desired setting 
1f20: 6f 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54  of the [SQLITE_T
1f30: 48 52 45 41 44 53 41 46 45 5d 20 6d 61 63 72 6f  HREADSAFE] macro
1f40: 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 6e 74  ..**.** This int
1f50: 65 72 66 61 63 65 20 6f 6e 6c 79 20 72 65 70 6f  erface only repo
1f60: 72 74 73 20 6f 6e 20 74 68 65 20 63 6f 6d 70 69  rts on the compi
1f70: 6c 65 2d 74 69 6d 65 20 6d 75 74 65 78 20 73 65  le-time mutex se
1f80: 74 74 69 6e 67 0a 2a 2a 20 6f 66 20 74 68 65 20  tting.** of the 
1f90: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
1fa0: 46 45 5d 20 66 6c 61 67 2e 20 20 49 66 20 53 51  FE] flag.  If SQ
1fb0: 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64  Lite is compiled
1fc0: 20 77 69 74 68 0a 2a 2a 20 53 51 4c 49 54 45 5f   with.** SQLITE_
1fd0: 54 48 52 45 41 44 53 41 46 45 3d 31 20 6f 72 20  THREADSAFE=1 or 
1fe0: 3d 32 20 74 68 65 6e 20 6d 75 74 65 78 65 73 20  =2 then mutexes 
1ff0: 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79 20 64  are enabled by d
2000: 65 66 61 75 6c 74 20 62 75 74 0a 2a 2a 20 63 61  efault but.** ca
2010: 6e 20 62 65 20 66 75 6c 6c 79 20 6f 72 20 70 61  n be fully or pa
2020: 72 74 69 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  rtially disabled
2030: 20 75 73 69 6e 67 20 61 20 63 61 6c 6c 20 74 6f   using a call to
2040: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
2050: 28 29 5d 0a 2a 2a 20 77 69 74 68 20 74 68 65 20  ()].** with the 
2060: 76 65 72 62 73 20 5b 53 51 4c 49 54 45 5f 43 4f  verbs [SQLITE_CO
2070: 4e 46 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41  NFIG_SINGLETHREA
2080: 44 5d 2c 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  D], [SQLITE_CONF
2090: 49 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 2c  IG_MULTITHREAD],
20a0: 0a 2a 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43  .** or [SQLITE_C
20b0: 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 2e 20 20 5e  ONFIG_MUTEX].  ^
20c0: 28 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75  (The return valu
20d0: 65 20 6f 66 20 74 68 65 0a 2a 2a 20 73 71 6c 69  e of the.** sqli
20e0: 74 65 33 5f 74 68 72 65 61 64 73 61 66 65 28 29  te3_threadsafe()
20f0: 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 77 73 20   function shows 
2100: 6f 6e 6c 79 20 74 68 65 20 63 6f 6d 70 69 6c 65  only the compile
2110: 2d 74 69 6d 65 20 73 65 74 74 69 6e 67 20 6f 66  -time setting of
2120: 0a 2a 2a 20 74 68 72 65 61 64 20 73 61 66 65 74  .** thread safet
2130: 79 2c 20 6e 6f 74 20 61 6e 79 20 72 75 6e 2d 74  y, not any run-t
2140: 69 6d 65 20 63 68 61 6e 67 65 73 20 74 6f 20 74  ime changes to t
2150: 68 61 74 20 73 65 74 74 69 6e 67 20 6d 61 64 65  hat setting made
2160: 20 62 79 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   by.** sqlite3_c
2170: 6f 6e 66 69 67 28 29 2e 20 49 6e 20 6f 74 68 65  onfig(). In othe
2180: 72 20 77 6f 72 64 73 2c 20 74 68 65 20 72 65 74  r words, the ret
2190: 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d 20 73  urn value from s
21a0: 71 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66  qlite3_threadsaf
21b0: 65 28 29 0a 2a 2a 20 69 73 20 75 6e 63 68 61 6e  e().** is unchan
21c0: 67 65 64 20 62 79 20 63 61 6c 6c 73 20 74 6f 20  ged by calls to 
21d0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
21e0: 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 74 68  .)^.**.** See th
21f0: 65 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  e [threading mod
2200: 65 5d 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e  e] documentation
2210: 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20   for additional 
2220: 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
2230: 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 68 72 65  int sqlite3_thre
2240: 61 64 73 61 66 65 28 76 6f 69 64 29 3b 0a 0a 2f  adsafe(void);../
2250: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44  *.** CAPI3REF: D
2260: 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
2270: 6f 6e 20 48 61 6e 64 6c 65 0a 2a 2a 20 4b 45 59  on Handle.** KEY
2280: 57 4f 52 44 53 3a 20 7b 64 61 74 61 62 61 73 65  WORDS: {database
2290: 20 63 6f 6e 6e 65 63 74 69 6f 6e 7d 20 7b 64 61   connection} {da
22a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
22b0: 6e 73 7d 0a 2a 2a 0a 2a 2a 20 45 61 63 68 20 6f  ns}.**.** Each o
22c0: 70 65 6e 20 53 51 4c 69 74 65 20 64 61 74 61 62  pen SQLite datab
22d0: 61 73 65 20 69 73 20 72 65 70 72 65 73 65 6e 74  ase is represent
22e0: 65 64 20 62 79 20 61 20 70 6f 69 6e 74 65 72 20  ed by a pointer 
22f0: 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f  to an instance o
2300: 66 0a 2a 2a 20 74 68 65 20 6f 70 61 71 75 65 20  f.** the opaque 
2310: 73 74 72 75 63 74 75 72 65 20 6e 61 6d 65 64 20  structure named 
2320: 22 73 71 6c 69 74 65 33 22 2e 20 20 49 74 20 69  "sqlite3".  It i
2330: 73 20 75 73 65 66 75 6c 20 74 6f 20 74 68 69 6e  s useful to thin
2340: 6b 20 6f 66 20 61 6e 20 73 71 6c 69 74 65 33 0a  k of an sqlite3.
2350: 2a 2a 20 70 6f 69 6e 74 65 72 20 61 73 20 61 6e  ** pointer as an
2360: 20 6f 62 6a 65 63 74 2e 20 20 54 68 65 20 5b 73   object.  The [s
2370: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20  qlite3_open()], 
2380: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
2390: 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
23a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 69  te3_open_v2()] i
23b0: 6e 74 65 72 66 61 63 65 73 20 61 72 65 20 69 74  nterfaces are it
23c0: 73 20 63 6f 6e 73 74 72 75 63 74 6f 72 73 2c 20  s constructors, 
23d0: 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 6c 6f  and [sqlite3_clo
23e0: 73 65 28 29 5d 0a 2a 2a 20 69 73 20 69 74 73 20  se()].** is its 
23f0: 64 65 73 74 72 75 63 74 6f 72 2e 20 20 54 68 65  destructor.  The
2400: 72 65 20 61 72 65 20 6d 61 6e 79 20 6f 74 68 65  re are many othe
2410: 72 20 69 6e 74 65 72 66 61 63 65 73 20 28 73 75  r interfaces (su
2420: 63 68 20 61 73 0a 2a 2a 20 5b 73 71 6c 69 74 65  ch as.** [sqlite
2430: 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c  3_prepare_v2()],
2440: 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65   [sqlite3_create
2450: 5f 66 75 6e 63 74 69 6f 6e 28 29 5d 2c 20 61 6e  _function()], an
2460: 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 75  d.** [sqlite3_bu
2470: 73 79 5f 74 69 6d 65 6f 75 74 28 29 5d 20 74 6f  sy_timeout()] to
2480: 20 6e 61 6d 65 20 62 75 74 20 74 68 72 65 65 29   name but three)
2490: 20 74 68 61 74 20 61 72 65 20 6d 65 74 68 6f 64   that are method
24a0: 73 20 6f 6e 20 61 6e 0a 2a 2a 20 73 71 6c 69 74  s on an.** sqlit
24b0: 65 33 20 6f 62 6a 65 63 74 2e 0a 2a 2f 0a 74 79  e3 object..*/.ty
24c0: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
24d0: 69 74 65 33 20 73 71 6c 69 74 65 33 3b 0a 0a 2f  ite3 sqlite3;../
24e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 36  *.** CAPI3REF: 6
24f0: 34 2d 42 69 74 20 49 6e 74 65 67 65 72 20 54 79  4-Bit Integer Ty
2500: 70 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  pes.** KEYWORDS:
2510: 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 20 73 71   sqlite_int64 sq
2520: 6c 69 74 65 5f 75 69 6e 74 36 34 0a 2a 2a 0a 2a  lite_uint64.**.*
2530: 2a 20 42 65 63 61 75 73 65 20 74 68 65 72 65 20  * Because there 
2540: 69 73 20 6e 6f 20 63 72 6f 73 73 2d 70 6c 61 74  is no cross-plat
2550: 66 6f 72 6d 20 77 61 79 20 74 6f 20 73 70 65 63  form way to spec
2560: 69 66 79 20 36 34 2d 62 69 74 20 69 6e 74 65 67  ify 64-bit integ
2570: 65 72 20 74 79 70 65 73 0a 2a 2a 20 53 51 4c 69  er types.** SQLi
2580: 74 65 20 69 6e 63 6c 75 64 65 73 20 74 79 70 65  te includes type
2590: 64 65 66 73 20 66 6f 72 20 36 34 2d 62 69 74 20  defs for 64-bit 
25a0: 73 69 67 6e 65 64 20 61 6e 64 20 75 6e 73 69 67  signed and unsig
25b0: 6e 65 64 20 69 6e 74 65 67 65 72 73 2e 0a 2a 2a  ned integers..**
25c0: 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
25d0: 69 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65  int64 and sqlite
25e0: 33 5f 75 69 6e 74 36 34 20 61 72 65 20 74 68 65  3_uint64 are the
25f0: 20 70 72 65 66 65 72 72 65 64 20 74 79 70 65 20   preferred type 
2600: 64 65 66 69 6e 69 74 69 6f 6e 73 2e 0a 2a 2a 20  definitions..** 
2610: 54 68 65 20 73 71 6c 69 74 65 5f 69 6e 74 36 34  The sqlite_int64
2620: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2630: 36 34 20 74 79 70 65 73 20 61 72 65 20 73 75 70  64 types are sup
2640: 70 6f 72 74 65 64 20 66 6f 72 20 62 61 63 6b 77  ported for backw
2650: 61 72 64 73 0a 2a 2a 20 63 6f 6d 70 61 74 69 62  ards.** compatib
2660: 69 6c 69 74 79 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a  ility only..**.*
2670: 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 69  * ^The sqlite3_i
2680: 6e 74 36 34 20 61 6e 64 20 73 71 6c 69 74 65 5f  nt64 and sqlite_
2690: 69 6e 74 36 34 20 74 79 70 65 73 20 63 61 6e 20  int64 types can 
26a0: 73 74 6f 72 65 20 69 6e 74 65 67 65 72 20 76 61  store integer va
26b0: 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65 6e 20  lues.** between 
26c0: 2d 39 32 32 33 33 37 32 30 33 36 38 35 34 37 37  -922337203685477
26d0: 35 38 30 38 20 61 6e 64 20 2b 39 32 32 33 33 37  5808 and +922337
26e0: 32 30 33 36 38 35 34 37 37 35 38 30 37 20 69 6e  2036854775807 in
26f0: 63 6c 75 73 69 76 65 2e 20 20 5e 54 68 65 0a 2a  clusive.  ^The.*
2700: 2a 20 73 71 6c 69 74 65 33 5f 75 69 6e 74 36 34  * sqlite3_uint64
2710: 20 61 6e 64 20 73 71 6c 69 74 65 5f 75 69 6e 74   and sqlite_uint
2720: 36 34 20 74 79 70 65 73 20 63 61 6e 20 73 74 6f  64 types can sto
2730: 72 65 20 69 6e 74 65 67 65 72 20 76 61 6c 75 65  re integer value
2740: 73 20 0a 2a 2a 20 62 65 74 77 65 65 6e 20 30 20  s .** between 0 
2750: 61 6e 64 20 2b 31 38 34 34 36 37 34 34 30 37 33  and +18446744073
2760: 37 30 39 35 35 31 36 31 35 20 69 6e 63 6c 75 73  709551615 inclus
2770: 69 76 65 2e 0a 2a 2f 0a 23 69 66 64 65 66 20 53  ive..*/.#ifdef S
2780: 51 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45  QLITE_INT64_TYPE
2790: 0a 20 20 74 79 70 65 64 65 66 20 53 51 4c 49 54  .  typedef SQLIT
27a0: 45 5f 49 4e 54 36 34 5f 54 59 50 45 20 73 71 6c  E_INT64_TYPE sql
27b0: 69 74 65 5f 69 6e 74 36 34 3b 0a 20 20 74 79 70  ite_int64;.  typ
27c0: 65 64 65 66 20 75 6e 73 69 67 6e 65 64 20 53 51  edef unsigned SQ
27d0: 4c 49 54 45 5f 49 4e 54 36 34 5f 54 59 50 45 20  LITE_INT64_TYPE 
27e0: 73 71 6c 69 74 65 5f 75 69 6e 74 36 34 3b 0a 23  sqlite_uint64;.#
27f0: 65 6c 69 66 20 64 65 66 69 6e 65 64 28 5f 4d 53  elif defined(_MS
2800: 43 5f 56 45 52 29 20 7c 7c 20 64 65 66 69 6e 65  C_VER) || define
2810: 64 28 5f 5f 42 4f 52 4c 41 4e 44 43 5f 5f 29 0a  d(__BORLANDC__).
2820: 20 20 74 79 70 65 64 65 66 20 5f 5f 69 6e 74 36    typedef __int6
2830: 34 20 73 71 6c 69 74 65 5f 69 6e 74 36 34 3b 0a  4 sqlite_int64;.
2840: 20 20 74 79 70 65 64 65 66 20 75 6e 73 69 67 6e    typedef unsign
2850: 65 64 20 5f 5f 69 6e 74 36 34 20 73 71 6c 69 74  ed __int64 sqlit
2860: 65 5f 75 69 6e 74 36 34 3b 0a 23 65 6c 73 65 0a  e_uint64;.#else.
2870: 20 20 74 79 70 65 64 65 66 20 6c 6f 6e 67 20 6c    typedef long l
2880: 6f 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 69  ong int sqlite_i
2890: 6e 74 36 34 3b 0a 20 20 74 79 70 65 64 65 66 20  nt64;.  typedef 
28a0: 75 6e 73 69 67 6e 65 64 20 6c 6f 6e 67 20 6c 6f  unsigned long lo
28b0: 6e 67 20 69 6e 74 20 73 71 6c 69 74 65 5f 75 69  ng int sqlite_ui
28c0: 6e 74 36 34 3b 0a 23 65 6e 64 69 66 0a 74 79 70  nt64;.#endif.typ
28d0: 65 64 65 66 20 73 71 6c 69 74 65 5f 69 6e 74 36  edef sqlite_int6
28e0: 34 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 3b  4 sqlite3_int64;
28f0: 0a 74 79 70 65 64 65 66 20 73 71 6c 69 74 65 5f  .typedef sqlite_
2900: 75 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 75  uint64 sqlite3_u
2910: 69 6e 74 36 34 3b 0a 0a 2f 2a 0a 2a 2a 20 49 66  int64;../*.** If
2920: 20 63 6f 6d 70 69 6c 69 6e 67 20 66 6f 72 20 61   compiling for a
2930: 20 70 72 6f 63 65 73 73 6f 72 20 74 68 61 74 20   processor that 
2940: 6c 61 63 6b 73 20 66 6c 6f 61 74 69 6e 67 20 70  lacks floating p
2950: 6f 69 6e 74 20 73 75 70 70 6f 72 74 2c 0a 2a 2a  oint support,.**
2960: 20 73 75 62 73 74 69 74 75 74 65 20 69 6e 74 65   substitute inte
2970: 67 65 72 20 66 6f 72 20 66 6c 6f 61 74 69 6e 67  ger for floating
2980: 2d 70 6f 69 6e 74 2e 0a 2a 2f 0a 23 69 66 64 65  -point..*/.#ifde
2990: 66 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 46 4c  f SQLITE_OMIT_FL
29a0: 4f 41 54 49 4e 47 5f 50 4f 49 4e 54 0a 23 20 64  OATING_POINT.# d
29b0: 65 66 69 6e 65 20 64 6f 75 62 6c 65 20 73 71 6c  efine double sql
29c0: 69 74 65 33 5f 69 6e 74 36 34 0a 23 65 6e 64 69  ite3_int64.#endi
29d0: 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  f../*.** CAPI3RE
29e0: 46 3a 20 43 6c 6f 73 69 6e 67 20 41 20 44 61 74  F: Closing A Dat
29f0: 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69 6f 6e  abase Connection
2a00: 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2a10: 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 6f 75 74  te3_close() rout
2a20: 69 6e 65 20 69 73 20 74 68 65 20 64 65 73 74 72  ine is the destr
2a30: 75 63 74 6f 72 20 66 6f 72 20 74 68 65 20 5b 73  uctor for the [s
2a40: 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2e 0a  qlite3] object..
2a50: 2a 2a 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c  ** ^Calls to sql
2a60: 69 74 65 33 5f 63 6c 6f 73 65 28 29 20 72 65 74  ite3_close() ret
2a70: 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20 69 66  urn SQLITE_OK if
2a80: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5d 20 6f   the [sqlite3] o
2a90: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 73 75 63 63  bject is.** succ
2aa0: 65 73 73 66 75 6c 6c 79 20 64 65 73 74 72 6f 79  essfully destroy
2ab0: 65 64 20 61 6e 64 20 61 6c 6c 20 61 73 73 6f 63  ed and all assoc
2ac0: 69 61 74 65 64 20 72 65 73 6f 75 72 63 65 73 20  iated resources 
2ad0: 61 72 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 2e  are deallocated.
2ae0: 0a 2a 2a 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69  .**.** Applicati
2af0: 6f 6e 73 20 6d 75 73 74 20 5b 73 71 6c 69 74 65  ons must [sqlite
2b00: 33 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e  3_finalize | fin
2b10: 61 6c 69 7a 65 5d 20 61 6c 6c 20 5b 70 72 65 70  alize] all [prep
2b20: 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 5d  ared statements]
2b30: 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  .** and [sqlite3
2b40: 5f 62 6c 6f 62 5f 63 6c 6f 73 65 20 7c 20 63 6c  _blob_close | cl
2b50: 6f 73 65 5d 20 61 6c 6c 20 5b 42 4c 4f 42 20 68  ose] all [BLOB h
2b60: 61 6e 64 6c 65 73 5d 20 61 73 73 6f 63 69 61 74  andles] associat
2b70: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
2b80: 73 71 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 20  sqlite3] object 
2b90: 70 72 69 6f 72 20 74 6f 20 61 74 74 65 6d 70 74  prior to attempt
2ba0: 69 6e 67 20 74 6f 20 63 6c 6f 73 65 20 74 68 65  ing to close the
2bb0: 20 6f 62 6a 65 63 74 2e 20 20 5e 49 66 0a 2a 2a   object.  ^If.**
2bc0: 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29   sqlite3_close()
2bd0: 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 61 20   is called on a 
2be0: 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
2bf0: 74 69 6f 6e 5d 20 74 68 61 74 20 73 74 69 6c 6c  tion] that still
2c00: 20 68 61 73 0a 2a 2a 20 6f 75 74 73 74 61 6e 64   has.** outstand
2c10: 69 6e 67 20 5b 70 72 65 70 61 72 65 64 20 73 74  ing [prepared st
2c20: 61 74 65 6d 65 6e 74 73 5d 20 6f 72 20 5b 42 4c  atements] or [BL
2c30: 4f 42 20 68 61 6e 64 6c 65 73 5d 2c 20 74 68 65  OB handles], the
2c40: 6e 20 69 74 20 72 65 74 75 72 6e 73 0a 2a 2a 20  n it returns.** 
2c50: 53 51 4c 49 54 45 5f 42 55 53 59 2e 0a 2a 2a 0a  SQLITE_BUSY..**.
2c60: 2a 2a 20 5e 49 66 20 5b 73 71 6c 69 74 65 33 5f  ** ^If [sqlite3_
2c70: 63 6c 6f 73 65 28 29 5d 20 69 73 20 69 6e 76 6f  close()] is invo
2c80: 6b 65 64 20 77 68 69 6c 65 20 61 20 74 72 61 6e  ked while a tran
2c90: 73 61 63 74 69 6f 6e 20 69 73 20 6f 70 65 6e 2c  saction is open,
2ca0: 0a 2a 2a 20 74 68 65 20 74 72 61 6e 73 61 63 74  .** the transact
2cb0: 69 6f 6e 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ion is automatic
2cc0: 61 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b  ally rolled back
2cd0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 20 70 61  ..**.** The C pa
2ce0: 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71 6c 69  rameter to [sqli
2cf0: 74 65 33 5f 63 6c 6f 73 65 28 43 29 5d 20 6d 75  te3_close(C)] mu
2d00: 73 74 20 62 65 20 65 69 74 68 65 72 20 61 20 4e  st be either a N
2d10: 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74 65 72 20 6f  ULL.** pointer o
2d20: 72 20 61 6e 20 5b 73 71 6c 69 74 65 33 5d 20 6f  r an [sqlite3] o
2d30: 62 6a 65 63 74 20 70 6f 69 6e 74 65 72 20 6f 62  bject pointer ob
2d40: 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  tained.** from [
2d50: 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 2c  sqlite3_open()],
2d60: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36   [sqlite3_open16
2d70: 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69  ()], or.** [sqli
2d80: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
2d90: 61 6e 64 20 6e 6f 74 20 70 72 65 76 69 6f 75 73  and not previous
2da0: 6c 79 20 63 6c 6f 73 65 64 2e 0a 2a 2a 20 5e 43  ly closed..** ^C
2db0: 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  alling sqlite3_c
2dc0: 6c 6f 73 65 28 29 20 77 69 74 68 20 61 20 4e 55  lose() with a NU
2dd0: 4c 4c 20 70 6f 69 6e 74 65 72 20 61 72 67 75 6d  LL pointer argum
2de0: 65 6e 74 20 69 73 20 61 20 0a 2a 2a 20 68 61 72  ent is a .** har
2df0: 6d 6c 65 73 73 20 6e 6f 2d 6f 70 2e 0a 2a 2f 0a  mless no-op..*/.
2e00: 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6c 6f 73  int sqlite3_clos
2e10: 65 28 73 71 6c 69 74 65 33 20 2a 29 3b 0a 0a 2f  e(sqlite3 *);../
2e20: 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 20 66 6f  *.** The type fo
2e30: 72 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  r a callback fun
2e40: 63 74 69 6f 6e 2e 0a 2a 2a 20 54 68 69 73 20 69  ction..** This i
2e50: 73 20 6c 65 67 61 63 79 20 61 6e 64 20 64 65 70  s legacy and dep
2e60: 72 65 63 61 74 65 64 2e 20 20 49 74 20 69 73 20  recated.  It is 
2e70: 69 6e 63 6c 75 64 65 64 20 66 6f 72 20 68 69 73  included for his
2e80: 74 6f 72 69 63 61 6c 0a 2a 2a 20 63 6f 6d 70 61  torical.** compa
2e90: 74 69 62 69 6c 69 74 79 20 61 6e 64 20 69 73 20  tibility and is 
2ea0: 6e 6f 74 20 64 6f 63 75 6d 65 6e 74 65 64 2e 0a  not documented..
2eb0: 2a 2f 0a 74 79 70 65 64 65 66 20 69 6e 74 20 28  */.typedef int (
2ec0: 2a 73 71 6c 69 74 65 33 5f 63 61 6c 6c 62 61 63  *sqlite3_callbac
2ed0: 6b 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 68 61  k)(void*,int,cha
2ee0: 72 2a 2a 2c 20 63 68 61 72 2a 2a 29 3b 0a 0a 2f  r**, char**);../
2ef0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
2f00: 6e 65 2d 53 74 65 70 20 51 75 65 72 79 20 45 78  ne-Step Query Ex
2f10: 65 63 75 74 69 6f 6e 20 49 6e 74 65 72 66 61 63  ecution Interfac
2f20: 65 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c 69  e.**.** The sqli
2f30: 74 65 33 5f 65 78 65 63 28 29 20 69 6e 74 65 72  te3_exec() inter
2f40: 66 61 63 65 20 69 73 20 61 20 63 6f 6e 76 65 6e  face is a conven
2f50: 69 65 6e 63 65 20 77 72 61 70 70 65 72 20 61 72  ience wrapper ar
2f60: 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  ound.** [sqlite3
2f70: 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 2c 20  _prepare_v2()], 
2f80: 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
2f90: 2c 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 66  , and [sqlite3_f
2fa0: 69 6e 61 6c 69 7a 65 28 29 5d 2c 0a 2a 2a 20 74  inalize()],.** t
2fb0: 68 61 74 20 61 6c 6c 6f 77 73 20 61 6e 20 61 70  hat allows an ap
2fc0: 70 6c 69 63 61 74 69 6f 6e 20 74 6f 20 72 75 6e  plication to run
2fd0: 20 6d 75 6c 74 69 70 6c 65 20 73 74 61 74 65 6d   multiple statem
2fe0: 65 6e 74 73 20 6f 66 20 53 51 4c 0a 2a 2a 20 77  ents of SQL.** w
2ff0: 69 74 68 6f 75 74 20 68 61 76 69 6e 67 20 74 6f  ithout having to
3000: 20 75 73 65 20 61 20 6c 6f 74 20 6f 66 20 43 20   use a lot of C 
3010: 63 6f 64 65 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68  code. .**.** ^Th
3020: 65 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  e sqlite3_exec()
3030: 20 69 6e 74 65 72 66 61 63 65 20 72 75 6e 73 20   interface runs 
3040: 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 55 54 46  zero or more UTF
3050: 2d 38 20 65 6e 63 6f 64 65 64 2c 0a 2a 2a 20 73  -8 encoded,.** s
3060: 65 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74  emicolon-separat
3070: 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  e SQL statements
3080: 20 70 61 73 73 65 64 20 69 6e 74 6f 20 69 74 73   passed into its
3090: 20 32 6e 64 20 61 72 67 75 6d 65 6e 74 2c 0a 2a   2nd argument,.*
30a0: 2a 20 69 6e 20 74 68 65 20 63 6f 6e 74 65 78 74  * in the context
30b0: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
30c0: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 61  e connection] pa
30d0: 73 73 65 64 20 69 6e 20 61 73 20 69 74 73 20 31  ssed in as its 1
30e0: 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 2e 20  st.** argument. 
30f0: 20 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63   ^If the callbac
3100: 6b 20 66 75 6e 63 74 69 6f 6e 20 6f 66 20 74 68  k function of th
3110: 65 20 33 72 64 20 61 72 67 75 6d 65 6e 74 20 74  e 3rd argument t
3120: 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78 65  o.** sqlite3_exe
3130: 63 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 2c  c() is not NULL,
3140: 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 76 6f   then it is invo
3150: 6b 65 64 20 66 6f 72 20 65 61 63 68 20 72 65 73  ked for each res
3160: 75 6c 74 20 72 6f 77 0a 2a 2a 20 63 6f 6d 69 6e  ult row.** comin
3170: 67 20 6f 75 74 20 6f 66 20 74 68 65 20 65 76 61  g out of the eva
3180: 6c 75 61 74 65 64 20 53 51 4c 20 73 74 61 74 65  luated SQL state
3190: 6d 65 6e 74 73 2e 20 20 5e 54 68 65 20 34 74 68  ments.  ^The 4th
31a0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20   argument to.** 
31b0: 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  to sqlite3_exec(
31c0: 29 20 69 73 20 72 65 6c 61 79 65 64 20 74 68 72  ) is relayed thr
31d0: 6f 75 67 68 20 74 6f 20 74 68 65 20 31 73 74 20  ough to the 1st 
31e0: 61 72 67 75 6d 65 6e 74 20 6f 66 20 65 61 63 68  argument of each
31f0: 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 69 6e 76  .** callback inv
3200: 6f 63 61 74 69 6f 6e 2e 20 20 5e 49 66 20 74 68  ocation.  ^If th
3210: 65 20 63 61 6c 6c 62 61 63 6b 20 70 6f 69 6e 74  e callback point
3220: 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78  er to sqlite3_ex
3230: 65 63 28 29 0a 2a 2a 20 69 73 20 4e 55 4c 4c 2c  ec().** is NULL,
3240: 20 74 68 65 6e 20 6e 6f 20 63 61 6c 6c 62 61 63   then no callbac
3250: 6b 20 69 73 20 65 76 65 72 20 69 6e 76 6f 6b 65  k is ever invoke
3260: 64 20 61 6e 64 20 72 65 73 75 6c 74 20 72 6f 77  d and result row
3270: 73 20 61 72 65 0a 2a 2a 20 69 67 6e 6f 72 65 64  s are.** ignored
3280: 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 65  ..**.** ^If an e
3290: 72 72 6f 72 20 6f 63 63 75 72 73 20 77 68 69 6c  rror occurs whil
32a0: 65 20 65 76 61 6c 75 61 74 69 6e 67 20 74 68 65  e evaluating the
32b0: 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
32c0: 70 61 73 73 65 64 20 69 6e 74 6f 0a 2a 2a 20 73  passed into.** s
32d0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 2c 20 74  qlite3_exec(), t
32e0: 68 65 6e 20 65 78 65 63 75 74 69 6f 6e 20 6f 66  hen execution of
32f0: 20 74 68 65 20 63 75 72 72 65 6e 74 20 73 74 61   the current sta
3300: 74 65 6d 65 6e 74 20 73 74 6f 70 73 20 61 6e 64  tement stops and
3310: 0a 2a 2a 20 73 75 62 73 65 71 75 65 6e 74 20 73  .** subsequent s
3320: 74 61 74 65 6d 65 6e 74 73 20 61 72 65 20 73 6b  tatements are sk
3330: 69 70 70 65 64 2e 20 20 5e 49 66 20 74 68 65 20  ipped.  ^If the 
3340: 35 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  5th parameter to
3350: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
3360: 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20 74  ** is not NULL t
3370: 68 65 6e 20 61 6e 79 20 65 72 72 6f 72 20 6d 65  hen any error me
3380: 73 73 61 67 65 20 69 73 20 77 72 69 74 74 65 6e  ssage is written
3390: 20 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74   into memory obt
33a0: 61 69 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  ained.** from [s
33b0: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
33c0: 20 61 6e 64 20 70 61 73 73 65 64 20 62 61 63 6b   and passed back
33d0: 20 74 68 72 6f 75 67 68 20 74 68 65 20 35 74 68   through the 5th
33e0: 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 54   parameter..** T
33f0: 6f 20 61 76 6f 69 64 20 6d 65 6d 6f 72 79 20 6c  o avoid memory l
3400: 65 61 6b 73 2c 20 74 68 65 20 61 70 70 6c 69 63  eaks, the applic
3410: 61 74 69 6f 6e 20 73 68 6f 75 6c 64 20 69 6e 76  ation should inv
3420: 6f 6b 65 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  oke [sqlite3_fre
3430: 65 28 29 5d 0a 2a 2a 20 6f 6e 20 65 72 72 6f 72  e()].** on error
3440: 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67 73   message strings
3450: 20 72 65 74 75 72 6e 65 64 20 74 68 72 6f 75 67   returned throug
3460: 68 20 74 68 65 20 35 74 68 20 70 61 72 61 6d 65  h the 5th parame
3470: 74 65 72 20 6f 66 0a 2a 2a 20 6f 66 20 73 71 6c  ter of.** of sql
3480: 69 74 65 33 5f 65 78 65 63 28 29 20 61 66 74 65  ite3_exec() afte
3490: 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73  r the error mess
34a0: 61 67 65 20 73 74 72 69 6e 67 20 69 73 20 6e 6f  age string is no
34b0: 20 6c 6f 6e 67 65 72 20 6e 65 65 64 65 64 2e 0a   longer needed..
34c0: 2a 2a 20 5e 49 66 20 74 68 65 20 35 74 68 20 70  ** ^If the 5th p
34d0: 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
34e0: 74 65 33 5f 65 78 65 63 28 29 20 69 73 20 6e 6f  te3_exec() is no
34f0: 74 20 4e 55 4c 4c 20 61 6e 64 20 6e 6f 20 65 72  t NULL and no er
3500: 72 6f 72 73 0a 2a 2a 20 6f 63 63 75 72 2c 20 74  rors.** occur, t
3510: 68 65 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63  hen sqlite3_exec
3520: 28 29 20 73 65 74 73 20 74 68 65 20 70 6f 69 6e  () sets the poin
3530: 74 65 72 20 69 6e 20 69 74 73 20 35 74 68 20 70  ter in its 5th p
3540: 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 4e  arameter to.** N
3550: 55 4c 4c 20 62 65 66 6f 72 65 20 72 65 74 75 72  ULL before retur
3560: 6e 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ning..**.** ^If 
3570: 61 6e 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28  an sqlite3_exec(
3580: 29 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  ) callback retur
3590: 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65  ns non-zero, the
35a0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
35b0: 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  ** routine retur
35c0: 6e 73 20 53 51 4c 49 54 45 5f 41 42 4f 52 54 20  ns SQLITE_ABORT 
35d0: 77 69 74 68 6f 75 74 20 69 6e 76 6f 6b 69 6e 67  without invoking
35e0: 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 67   the callback ag
35f0: 61 69 6e 20 61 6e 64 0a 2a 2a 20 77 69 74 68 6f  ain and.** witho
3600: 75 74 20 72 75 6e 6e 69 6e 67 20 61 6e 79 20 73  ut running any s
3610: 75 62 73 65 71 75 65 6e 74 20 53 51 4c 20 73 74  ubsequent SQL st
3620: 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  atements..**.** 
3630: 5e 54 68 65 20 32 6e 64 20 61 72 67 75 6d 65 6e  ^The 2nd argumen
3640: 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  t to the sqlite3
3650: 5f 65 78 65 63 28 29 20 63 61 6c 6c 62 61 63 6b  _exec() callback
3660: 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 68 65   function is the
3670: 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f  .** number of co
3680: 6c 75 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73  lumns in the res
3690: 75 6c 74 2e 20 20 5e 54 68 65 20 33 72 64 20 61  ult.  ^The 3rd a
36a0: 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 73  rgument to the s
36b0: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a 2a 2a  qlite3_exec().**
36c0: 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20   callback is an 
36d0: 61 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72  array of pointer
36e0: 73 20 74 6f 20 73 74 72 69 6e 67 73 20 6f 62 74  s to strings obt
36f0: 61 69 6e 65 64 20 61 73 20 69 66 20 66 72 6f 6d  ained as if from
3700: 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
3710: 75 6d 6e 5f 74 65 78 74 28 29 5d 2c 20 6f 6e 65  umn_text()], one
3720: 20 66 6f 72 20 65 61 63 68 20 63 6f 6c 75 6d 6e   for each column
3730: 2e 20 20 5e 49 66 20 61 6e 20 65 6c 65 6d 65 6e  .  ^If an elemen
3740: 74 20 6f 66 20 61 0a 2a 2a 20 72 65 73 75 6c 74  t of a.** result
3750: 20 72 6f 77 20 69 73 20 4e 55 4c 4c 20 74 68 65   row is NULL the
3760: 6e 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  n the correspond
3770: 69 6e 67 20 73 74 72 69 6e 67 20 70 6f 69 6e 74  ing string point
3780: 65 72 20 66 6f 72 20 74 68 65 0a 2a 2a 20 73 71  er for the.** sq
3790: 6c 69 74 65 33 5f 65 78 65 63 28 29 20 63 61 6c  lite3_exec() cal
37a0: 6c 62 61 63 6b 20 69 73 20 61 20 4e 55 4c 4c 20  lback is a NULL 
37b0: 70 6f 69 6e 74 65 72 2e 20 20 5e 54 68 65 20 34  pointer.  ^The 4
37c0: 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  th argument to t
37d0: 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 78  he.** sqlite3_ex
37e0: 65 63 28 29 20 63 61 6c 6c 62 61 63 6b 20 69 73  ec() callback is
37f0: 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
3800: 6e 74 65 72 73 20 74 6f 20 73 74 72 69 6e 67 73  nters to strings
3810: 20 77 68 65 72 65 20 65 61 63 68 0a 2a 2a 20 65   where each.** e
3820: 6e 74 72 79 20 72 65 70 72 65 73 65 6e 74 73 20  ntry represents 
3830: 74 68 65 20 6e 61 6d 65 20 6f 66 20 63 6f 72 72  the name of corr
3840: 65 73 70 6f 6e 64 69 6e 67 20 72 65 73 75 6c 74  esponding result
3850: 20 63 6f 6c 75 6d 6e 20 61 73 20 6f 62 74 61 69   column as obtai
3860: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73 71 6c  ned.** from [sql
3870: 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
3880: 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ()]..**.** ^If t
3890: 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
38a0: 20 74 6f 20 73 71 6c 69 74 65 33 5f 65 78 65 63   to sqlite3_exec
38b0: 28 29 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  () is a NULL poi
38c0: 6e 74 65 72 2c 20 61 20 70 6f 69 6e 74 65 72 0a  nter, a pointer.
38d0: 2a 2a 20 74 6f 20 61 6e 20 65 6d 70 74 79 20 73  ** to an empty s
38e0: 74 72 69 6e 67 2c 20 6f 72 20 61 20 70 6f 69 6e  tring, or a poin
38f0: 74 65 72 20 74 68 61 74 20 63 6f 6e 74 61 69 6e  ter that contain
3900: 73 20 6f 6e 6c 79 20 77 68 69 74 65 73 70 61 63  s only whitespac
3910: 65 20 61 6e 64 2f 6f 72 20 0a 2a 2a 20 53 51 4c  e and/or .** SQL
3920: 20 63 6f 6d 6d 65 6e 74 73 2c 20 74 68 65 6e 20   comments, then 
3930: 6e 6f 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  no SQL statement
3940: 73 20 61 72 65 20 65 76 61 6c 75 61 74 65 64 20  s are evaluated 
3950: 61 6e 64 20 74 68 65 20 64 61 74 61 62 61 73 65  and the database
3960: 0a 2a 2a 20 69 73 20 6e 6f 74 20 63 68 61 6e 67  .** is not chang
3970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 52 65 73 74 72 69  ed..**.** Restri
3980: 63 74 69 6f 6e 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  ctions:.**.** <u
3990: 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  l>.** <li> The a
39a0: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
39b0: 69 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20  insure that the 
39c0: 31 73 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f  1st parameter to
39d0: 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29 0a   sqlite3_exec().
39e0: 2a 2a 20 20 20 20 20 20 69 73 20 61 20 76 61 6c  **      is a val
39f0: 69 64 20 61 6e 64 20 6f 70 65 6e 20 5b 64 61 74  id and open [dat
3a00: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
3a10: 5d 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 61  ]..** <li> The a
3a20: 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20  pplication must 
3a30: 6e 6f 74 20 63 6c 6f 73 65 20 5b 64 61 74 61 62  not close [datab
3a40: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
3a50: 73 70 65 63 69 66 69 65 64 20 62 79 0a 2a 2a 20  specified by.** 
3a60: 20 20 20 20 20 74 68 65 20 31 73 74 20 70 61 72       the 1st par
3a70: 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
3a80: 33 5f 65 78 65 63 28 29 20 77 68 69 6c 65 20 73  3_exec() while s
3a90: 71 6c 69 74 65 33 5f 65 78 65 63 28 29 20 69 73  qlite3_exec() is
3aa0: 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 3c 6c 69   running..** <li
3ab0: 3e 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  > The applicatio
3ac0: 6e 20 6d 75 73 74 20 6e 6f 74 20 6d 6f 64 69 66  n must not modif
3ad0: 79 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d  y the SQL statem
3ae0: 65 6e 74 20 74 65 78 74 20 70 61 73 73 65 64 20  ent text passed 
3af0: 69 6e 74 6f 0a 2a 2a 20 20 20 20 20 20 74 68 65  into.**      the
3b00: 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 6f   2nd parameter o
3b10: 66 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29  f sqlite3_exec()
3b20: 20 77 68 69 6c 65 20 73 71 6c 69 74 65 33 5f 65   while sqlite3_e
3b30: 78 65 63 28 29 20 69 73 20 72 75 6e 6e 69 6e 67  xec() is running
3b40: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2f 0a 69 6e  ..** </ul>.*/.in
3b50: 74 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 0a  t sqlite3_exec(.
3b60: 20 20 73 71 6c 69 74 65 33 2a 2c 20 20 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 2f 2a 20               /* 
3b90: 41 6e 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65  An open database
3ba0: 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
3bb0: 20 2a 73 71 6c 2c 20 20 20 20 20 20 20 20 20 20   *sql,          
3bc0: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
3bd0: 20 2f 2a 20 53 51 4c 20 74 6f 20 62 65 20 65 76   /* SQL to be ev
3be0: 61 6c 75 61 74 65 64 20 2a 2f 0a 20 20 69 6e 74  aluated */.  int
3bf0: 20 28 2a 63 61 6c 6c 62 61 63 6b 29 28 76 6f 69   (*callback)(voi
3c00: 64 2a 2c 69 6e 74 2c 63 68 61 72 2a 2a 2c 63 68  d*,int,char**,ch
3c10: 61 72 2a 2a 29 2c 20 20 2f 2a 20 43 61 6c 6c 62  ar**),  /* Callb
3c20: 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a  ack function */.
3c30: 20 20 76 6f 69 64 20 2a 2c 20 20 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 2f 2a 20               /* 
3c60: 31 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  1st argument to 
3c70: 63 61 6c 6c 62 61 63 6b 20 2a 2f 0a 20 20 63 68  callback */.  ch
3c80: 61 72 20 2a 2a 65 72 72 6d 73 67 20 20 20 20 20  ar **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 2f 2a 20 45 72 72 6f           /* Erro
3cb0: 72 20 6d 73 67 20 77 72 69 74 74 65 6e 20 68 65  r msg written he
3cc0: 72 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  re */.);../*.** 
3cd0: 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
3ce0: 20 43 6f 64 65 73 0a 2a 2a 20 4b 45 59 57 4f 52   Codes.** KEYWOR
3cf0: 44 53 3a 20 53 51 4c 49 54 45 5f 4f 4b 20 7b 65  DS: SQLITE_OK {e
3d00: 72 72 6f 72 20 63 6f 64 65 7d 20 7b 65 72 72 6f  rror code} {erro
3d10: 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45 59 57  r codes}.** KEYW
3d20: 4f 52 44 53 3a 20 7b 72 65 73 75 6c 74 20 63 6f  ORDS: {result co
3d30: 64 65 7d 20 7b 72 65 73 75 6c 74 20 63 6f 64 65  de} {result code
3d40: 73 7d 0a 2a 2a 0a 2a 2a 20 4d 61 6e 79 20 53 51  s}.**.** Many SQ
3d50: 4c 69 74 65 20 66 75 6e 63 74 69 6f 6e 73 20 72  Lite functions r
3d60: 65 74 75 72 6e 20 61 6e 20 69 6e 74 65 67 65 72  eturn an integer
3d70: 20 72 65 73 75 6c 74 20 63 6f 64 65 20 66 72 6f   result code fro
3d80: 6d 20 74 68 65 20 73 65 74 20 73 68 6f 77 6e 0a  m the set shown.
3d90: 2a 2a 20 68 65 72 65 20 69 6e 20 6f 72 64 65 72  ** here in order
3da0: 20 74 6f 20 69 6e 64 69 63 61 74 65 73 20 73 75   to indicates su
3db0: 63 63 65 73 73 20 6f 72 20 66 61 69 6c 75 72 65  ccess or failure
3dc0: 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 65 72 72 6f  ..**.** New erro
3dd0: 72 20 63 6f 64 65 73 20 6d 61 79 20 62 65 20 61  r codes may be a
3de0: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 76  dded in future v
3df0: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
3e00: 65 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  e..**.** See als
3e10: 6f 3a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  o: [SQLITE_IOERR
3e20: 5f 52 45 41 44 20 7c 20 65 78 74 65 6e 64 65 64  _READ | extended
3e30: 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d 2c 0a   result codes],.
3e40: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62  ** [sqlite3_vtab
3e50: 5f 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20  _on_conflict()] 
3e60: 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41 43 4b  [SQLITE_ROLLBACK
3e70: 20 7c 20 72 65 73 75 6c 74 20 63 6f 64 65 73 5d   | result codes]
3e80: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
3e90: 49 54 45 5f 4f 4b 20 20 20 20 20 20 20 20 20 20  ITE_OK          
3ea0: 20 30 20 20 20 2f 2a 20 53 75 63 63 65 73 73 66   0   /* Successf
3eb0: 75 6c 20 72 65 73 75 6c 74 20 2a 2f 0a 2f 2a 20  ul result */./* 
3ec0: 62 65 67 69 6e 6e 69 6e 67 2d 6f 66 2d 65 72 72  beginning-of-err
3ed0: 6f 72 2d 63 6f 64 65 73 20 2a 2f 0a 23 64 65 66  or-codes */.#def
3ee0: 69 6e 65 20 53 51 4c 49 54 45 5f 45 52 52 4f 52  ine SQLITE_ERROR
3ef0: 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20 53          1   /* S
3f00: 51 4c 20 65 72 72 6f 72 20 6f 72 20 6d 69 73 73  QL error or miss
3f10: 69 6e 67 20 64 61 74 61 62 61 73 65 20 2a 2f 0a  ing database */.
3f20: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
3f30: 4e 54 45 52 4e 41 4c 20 20 20 20 20 32 20 20 20  NTERNAL     2   
3f40: 2f 2a 20 49 6e 74 65 72 6e 61 6c 20 6c 6f 67 69  /* Internal logi
3f50: 63 20 65 72 72 6f 72 20 69 6e 20 53 51 4c 69 74  c error in SQLit
3f60: 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  e */.#define SQL
3f70: 49 54 45 5f 50 45 52 4d 20 20 20 20 20 20 20 20  ITE_PERM        
3f80: 20 33 20 20 20 2f 2a 20 41 63 63 65 73 73 20 70   3   /* Access p
3f90: 65 72 6d 69 73 73 69 6f 6e 20 64 65 6e 69 65 64  ermission denied
3fa0: 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
3fb0: 54 45 5f 41 42 4f 52 54 20 20 20 20 20 20 20 20  TE_ABORT        
3fc0: 34 20 20 20 2f 2a 20 43 61 6c 6c 62 61 63 6b 20  4   /* Callback 
3fd0: 72 6f 75 74 69 6e 65 20 72 65 71 75 65 73 74 65  routine requeste
3fe0: 64 20 61 6e 20 61 62 6f 72 74 20 2a 2f 0a 23 64  d an abort */.#d
3ff0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53  efine SQLITE_BUS
4000: 59 20 20 20 20 20 20 20 20 20 35 20 20 20 2f 2a  Y         5   /*
4010: 20 54 68 65 20 64 61 74 61 62 61 73 65 20 66 69   The database fi
4020: 6c 65 20 69 73 20 6c 6f 63 6b 65 64 20 2a 2f 0a  le is locked */.
4030: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
4040: 4f 43 4b 45 44 20 20 20 20 20 20 20 36 20 20 20  OCKED       6   
4050: 2f 2a 20 41 20 74 61 62 6c 65 20 69 6e 20 74 68  /* A table in th
4060: 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6c 6f  e database is lo
4070: 63 6b 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20  cked */.#define 
4080: 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 20 20 20  SQLITE_NOMEM    
4090: 20 20 20 20 37 20 20 20 2f 2a 20 41 20 6d 61 6c      7   /* A mal
40a0: 6c 6f 63 28 29 20 66 61 69 6c 65 64 20 2a 2f 0a  loc() failed */.
40b0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52  #define SQLITE_R
40c0: 45 41 44 4f 4e 4c 59 20 20 20 20 20 38 20 20 20  EADONLY     8   
40d0: 2f 2a 20 41 74 74 65 6d 70 74 20 74 6f 20 77 72  /* Attempt to wr
40e0: 69 74 65 20 61 20 72 65 61 64 6f 6e 6c 79 20 64  ite a readonly d
40f0: 61 74 61 62 61 73 65 20 2a 2f 0a 23 64 65 66 69  atabase */.#defi
4100: 6e 65 20 53 51 4c 49 54 45 5f 49 4e 54 45 52 52  ne SQLITE_INTERR
4110: 55 50 54 20 20 20 20 39 20 20 20 2f 2a 20 4f 70  UPT    9   /* Op
4120: 65 72 61 74 69 6f 6e 20 74 65 72 6d 69 6e 61 74  eration terminat
4130: 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e  ed by sqlite3_in
4140: 74 65 72 72 75 70 74 28 29 2a 2f 0a 23 64 65 66  terrupt()*/.#def
4150: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4160: 20 20 20 20 20 20 20 31 30 20 20 20 2f 2a 20 53         10   /* S
4170: 6f 6d 65 20 6b 69 6e 64 20 6f 66 20 64 69 73 6b  ome kind of disk
4180: 20 49 2f 4f 20 65 72 72 6f 72 20 6f 63 63 75 72   I/O error occur
4190: 72 65 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  red */.#define S
41a0: 51 4c 49 54 45 5f 43 4f 52 52 55 50 54 20 20 20  QLITE_CORRUPT   
41b0: 20 20 31 31 20 20 20 2f 2a 20 54 68 65 20 64 61    11   /* The da
41c0: 74 61 62 61 73 65 20 64 69 73 6b 20 69 6d 61 67  tabase disk imag
41d0: 65 20 69 73 20 6d 61 6c 66 6f 72 6d 65 64 20 2a  e is malformed *
41e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
41f0: 5f 4e 4f 54 46 4f 55 4e 44 20 20 20 20 31 32 20  _NOTFOUND    12 
4200: 20 20 2f 2a 20 55 6e 6b 6e 6f 77 6e 20 6f 70 63    /* Unknown opc
4210: 6f 64 65 20 69 6e 20 73 71 6c 69 74 65 33 5f 66  ode in sqlite3_f
4220: 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 20 2a 2f  ile_control() */
4230: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4240: 46 55 4c 4c 20 20 20 20 20 20 20 20 31 33 20 20  FULL        13  
4250: 20 2f 2a 20 49 6e 73 65 72 74 69 6f 6e 20 66 61   /* Insertion fa
4260: 69 6c 65 64 20 62 65 63 61 75 73 65 20 64 61 74  iled because dat
4270: 61 62 61 73 65 20 69 73 20 66 75 6c 6c 20 2a 2f  abase is full */
4280: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4290: 43 41 4e 54 4f 50 45 4e 20 20 20 20 31 34 20 20  CANTOPEN    14  
42a0: 20 2f 2a 20 55 6e 61 62 6c 65 20 74 6f 20 6f 70   /* Unable to op
42b0: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
42c0: 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e 65 20  file */.#define 
42d0: 53 51 4c 49 54 45 5f 50 52 4f 54 4f 43 4f 4c 20  SQLITE_PROTOCOL 
42e0: 20 20 20 31 35 20 20 20 2f 2a 20 44 61 74 61 62     15   /* Datab
42f0: 61 73 65 20 6c 6f 63 6b 20 70 72 6f 74 6f 63 6f  ase lock protoco
4300: 6c 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  l error */.#defi
4310: 6e 65 20 53 51 4c 49 54 45 5f 45 4d 50 54 59 20  ne SQLITE_EMPTY 
4320: 20 20 20 20 20 20 31 36 20 20 20 2f 2a 20 44 61        16   /* Da
4330: 74 61 62 61 73 65 20 69 73 20 65 6d 70 74 79 20  tabase is empty 
4340: 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
4350: 45 5f 53 43 48 45 4d 41 20 20 20 20 20 20 31 37  E_SCHEMA      17
4360: 20 20 20 2f 2a 20 54 68 65 20 64 61 74 61 62 61     /* The databa
4370: 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
4380: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4390: 49 54 45 5f 54 4f 4f 42 49 47 20 20 20 20 20 20  ITE_TOOBIG      
43a0: 31 38 20 20 20 2f 2a 20 53 74 72 69 6e 67 20 6f  18   /* String o
43b0: 72 20 42 4c 4f 42 20 65 78 63 65 65 64 73 20 73  r BLOB exceeds s
43c0: 69 7a 65 20 6c 69 6d 69 74 20 2a 2f 0a 23 64 65  ize limit */.#de
43d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 53  fine SQLITE_CONS
43e0: 54 52 41 49 4e 54 20 20 31 39 20 20 20 2f 2a 20  TRAINT  19   /* 
43f0: 41 62 6f 72 74 20 64 75 65 20 74 6f 20 63 6f 6e  Abort due to con
4400: 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
4410: 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
4420: 49 54 45 5f 4d 49 53 4d 41 54 43 48 20 20 20 20  ITE_MISMATCH    
4430: 32 30 20 20 20 2f 2a 20 44 61 74 61 20 74 79 70  20   /* Data typ
4440: 65 20 6d 69 73 6d 61 74 63 68 20 2a 2f 0a 23 64  e mismatch */.#d
4450: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4d 49 53  efine SQLITE_MIS
4460: 55 53 45 20 20 20 20 20 20 32 31 20 20 20 2f 2a  USE      21   /*
4470: 20 4c 69 62 72 61 72 79 20 75 73 65 64 20 69 6e   Library used in
4480: 63 6f 72 72 65 63 74 6c 79 20 2a 2f 0a 23 64 65  correctly */.#de
4490: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 4c 46  fine SQLITE_NOLF
44a0: 53 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20  S       22   /* 
44b0: 55 73 65 73 20 4f 53 20 66 65 61 74 75 72 65 73  Uses OS features
44c0: 20 6e 6f 74 20 73 75 70 70 6f 72 74 65 64 20 6f   not supported o
44d0: 6e 20 68 6f 73 74 20 2a 2f 0a 23 64 65 66 69 6e  n host */.#defin
44e0: 65 20 53 51 4c 49 54 45 5f 41 55 54 48 20 20 20  e SQLITE_AUTH   
44f0: 20 20 20 20 20 32 33 20 20 20 2f 2a 20 41 75 74       23   /* Aut
4500: 68 6f 72 69 7a 61 74 69 6f 6e 20 64 65 6e 69 65  horization denie
4510: 64 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  d */.#define SQL
4520: 49 54 45 5f 46 4f 52 4d 41 54 20 20 20 20 20 20  ITE_FORMAT      
4530: 32 34 20 20 20 2f 2a 20 41 75 78 69 6c 69 61 72  24   /* Auxiliar
4540: 79 20 64 61 74 61 62 61 73 65 20 66 6f 72 6d 61  y database forma
4550: 74 20 65 72 72 6f 72 20 2a 2f 0a 23 64 65 66 69  t error */.#defi
4560: 6e 65 20 53 51 4c 49 54 45 5f 52 41 4e 47 45 20  ne SQLITE_RANGE 
4570: 20 20 20 20 20 20 32 35 20 20 20 2f 2a 20 32 6e        25   /* 2n
4580: 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  d parameter to s
4590: 71 6c 69 74 65 33 5f 62 69 6e 64 20 6f 75 74 20  qlite3_bind out 
45a0: 6f 66 20 72 61 6e 67 65 20 2a 2f 0a 23 64 65 66  of range */.#def
45b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4e 4f 54 41 44  ine SQLITE_NOTAD
45c0: 42 20 20 20 20 20 20 32 36 20 20 20 2f 2a 20 46  B      26   /* F
45d0: 69 6c 65 20 6f 70 65 6e 65 64 20 74 68 61 74 20  ile opened that 
45e0: 69 73 20 6e 6f 74 20 61 20 64 61 74 61 62 61 73  is not a databas
45f0: 65 20 66 69 6c 65 20 2a 2f 0a 23 64 65 66 69 6e  e file */.#defin
4600: 65 20 53 51 4c 49 54 45 5f 52 4f 57 20 20 20 20  e SQLITE_ROW    
4610: 20 20 20 20 20 31 30 30 20 20 2f 2a 20 73 71 6c       100  /* sql
4620: 69 74 65 33 5f 73 74 65 70 28 29 20 68 61 73 20  ite3_step() has 
4630: 61 6e 6f 74 68 65 72 20 72 6f 77 20 72 65 61 64  another row read
4640: 79 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  y */.#define SQL
4650: 49 54 45 5f 44 4f 4e 45 20 20 20 20 20 20 20 20  ITE_DONE        
4660: 31 30 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f  101  /* sqlite3_
4670: 73 74 65 70 28 29 20 68 61 73 20 66 69 6e 69 73  step() has finis
4680: 68 65 64 20 65 78 65 63 75 74 69 6e 67 20 2a 2f  hed executing */
4690: 0a 2f 2a 20 65 6e 64 2d 6f 66 2d 65 72 72 6f 72  ./* end-of-error
46a0: 2d 63 6f 64 65 73 20 2a 2f 0a 0a 2f 2a 0a 2a 2a  -codes */../*.**
46b0: 20 43 41 50 49 33 52 45 46 3a 20 45 78 74 65 6e   CAPI3REF: Exten
46c0: 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73  ded Result Codes
46d0: 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 65  .** KEYWORDS: {e
46e0: 78 74 65 6e 64 65 64 20 65 72 72 6f 72 20 63 6f  xtended error co
46f0: 64 65 7d 20 7b 65 78 74 65 6e 64 65 64 20 65 72  de} {extended er
4700: 72 6f 72 20 63 6f 64 65 73 7d 0a 2a 2a 20 4b 45  ror codes}.** KE
4710: 59 57 4f 52 44 53 3a 20 7b 65 78 74 65 6e 64 65  YWORDS: {extende
4720: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 7d 20 7b  d result code} {
4730: 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20  extended result 
4740: 63 6f 64 65 73 7d 0a 2a 2a 0a 2a 2a 20 49 6e 20  codes}.**.** In 
4750: 69 74 73 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  its default conf
4760: 69 67 75 72 61 74 69 6f 6e 2c 20 53 51 4c 69 74  iguration, SQLit
4770: 65 20 41 50 49 20 72 6f 75 74 69 6e 65 73 20 72  e API routines r
4780: 65 74 75 72 6e 20 6f 6e 65 20 6f 66 20 32 36 20  eturn one of 26 
4790: 69 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49  integer.** [SQLI
47a0: 54 45 5f 4f 4b 20 7c 20 72 65 73 75 6c 74 20 63  TE_OK | result c
47b0: 6f 64 65 73 5d 2e 20 20 48 6f 77 65 76 65 72 2c  odes].  However,
47c0: 20 65 78 70 65 72 69 65 6e 63 65 20 68 61 73 20   experience has 
47d0: 73 68 6f 77 6e 20 74 68 61 74 20 6d 61 6e 79 20  shown that many 
47e0: 6f 66 0a 2a 2a 20 74 68 65 73 65 20 72 65 73 75  of.** these resu
47f0: 6c 74 20 63 6f 64 65 73 20 61 72 65 20 74 6f 6f  lt codes are too
4800: 20 63 6f 61 72 73 65 2d 67 72 61 69 6e 65 64 2e   coarse-grained.
4810: 20 20 54 68 65 79 20 64 6f 20 6e 6f 74 20 70 72    They do not pr
4820: 6f 76 69 64 65 20 61 73 0a 2a 2a 20 6d 75 63 68  ovide as.** much
4830: 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f   information abo
4840: 75 74 20 70 72 6f 62 6c 65 6d 73 20 61 73 20 70  ut problems as p
4850: 72 6f 67 72 61 6d 6d 65 72 73 20 6d 69 67 68 74  rogrammers might
4860: 20 6c 69 6b 65 2e 20 20 49 6e 20 61 6e 20 65 66   like.  In an ef
4870: 66 6f 72 74 20 74 6f 0a 2a 2a 20 61 64 64 72 65  fort to.** addre
4880: 73 73 20 74 68 69 73 2c 20 6e 65 77 65 72 20 76  ss this, newer v
4890: 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74  ersions of SQLit
48a0: 65 20 28 76 65 72 73 69 6f 6e 20 33 2e 33 2e 38  e (version 3.3.8
48b0: 20 61 6e 64 20 6c 61 74 65 72 29 20 69 6e 63 6c   and later) incl
48c0: 75 64 65 0a 2a 2a 20 73 75 70 70 6f 72 74 20 66  ude.** support f
48d0: 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 72 65  or additional re
48e0: 73 75 6c 74 20 63 6f 64 65 73 20 74 68 61 74 20  sult codes that 
48f0: 70 72 6f 76 69 64 65 20 6d 6f 72 65 20 64 65 74  provide more det
4900: 61 69 6c 65 64 20 69 6e 66 6f 72 6d 61 74 69 6f  ailed informatio
4910: 6e 0a 2a 2a 20 61 62 6f 75 74 20 65 72 72 6f 72  n.** about error
4920: 73 2e 20 54 68 65 20 65 78 74 65 6e 64 65 64 20  s. The extended 
4930: 72 65 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65  result codes are
4940: 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69 73 61   enabled or disa
4950: 62 6c 65 64 0a 2a 2a 20 6f 6e 20 61 20 70 65 72  bled.** on a per
4960: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
4970: 74 69 6f 6e 20 62 61 73 69 73 20 75 73 69 6e 67  tion basis using
4980: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
4990: 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75 6c 74  _extended_result
49a0: 5f 63 6f 64 65 73 28 29 5d 20 41 50 49 2e 0a 2a  _codes()] API..*
49b0: 2a 0a 2a 2a 20 53 6f 6d 65 20 6f 66 20 74 68 65  *.** Some of the
49c0: 20 61 76 61 69 6c 61 62 6c 65 20 65 78 74 65 6e   available exten
49d0: 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
49e0: 20 61 72 65 20 6c 69 73 74 65 64 20 68 65 72 65   are listed here
49f0: 2e 0a 2a 2a 20 4f 6e 65 20 6d 61 79 20 65 78 70  ..** One may exp
4a00: 65 63 74 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ect the number o
4a10: 66 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c  f extended resul
4a20: 74 20 63 6f 64 65 73 20 77 69 6c 6c 20 62 65 20  t codes will be 
4a30: 65 78 70 61 6e 64 0a 2a 2a 20 6f 76 65 72 20 74  expand.** over t
4a40: 69 6d 65 2e 20 20 53 6f 66 74 77 61 72 65 20 74  ime.  Software t
4a50: 68 61 74 20 75 73 65 73 20 65 78 74 65 6e 64 65  hat uses extende
4a60: 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73 20 73  d result codes s
4a70: 68 6f 75 6c 64 20 65 78 70 65 63 74 0a 2a 2a 20  hould expect.** 
4a80: 74 6f 20 73 65 65 20 6e 65 77 20 72 65 73 75 6c  to see new resul
4a90: 74 20 63 6f 64 65 73 20 69 6e 20 66 75 74 75 72  t codes in futur
4aa0: 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
4ab0: 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
4ac0: 53 51 4c 49 54 45 5f 4f 4b 20 72 65 73 75 6c 74  SQLITE_OK result
4ad0: 20 63 6f 64 65 20 77 69 6c 6c 20 6e 65 76 65 72   code will never
4ae0: 20 62 65 20 65 78 74 65 6e 64 65 64 2e 20 20 49   be extended.  I
4af0: 74 20 77 69 6c 6c 20 61 6c 77 61 79 73 0a 2a 2a  t will always.**
4b00: 20 62 65 20 65 78 61 63 74 6c 79 20 7a 65 72 6f   be exactly zero
4b10: 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  ..*/.#define SQL
4b20: 49 54 45 5f 49 4f 45 52 52 5f 52 45 41 44 20 20  ITE_IOERR_READ  
4b30: 20 20 20 20 20 20 20 20 20 20 20 20 28 53 51 4c              (SQL
4b40: 49 54 45 5f 49 4f 45 52 52 20 7c 20 28 31 3c 3c  ITE_IOERR | (1<<
4b50: 38 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  8)).#define SQLI
4b60: 54 45 5f 49 4f 45 52 52 5f 53 48 4f 52 54 5f 52  TE_IOERR_SHORT_R
4b70: 45 41 44 20 20 20 20 20 20 20 20 28 53 51 4c 49  EAD        (SQLI
4b80: 54 45 5f 49 4f 45 52 52 20 7c 20 28 32 3c 3c 38  TE_IOERR | (2<<8
4b90: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
4ba0: 45 5f 49 4f 45 52 52 5f 57 52 49 54 45 20 20 20  E_IOERR_WRITE   
4bb0: 20 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54            (SQLIT
4bc0: 45 5f 49 4f 45 52 52 20 7c 20 28 33 3c 3c 38 29  E_IOERR | (3<<8)
4bd0: 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ).#define SQLITE
4be0: 5f 49 4f 45 52 52 5f 46 53 59 4e 43 20 20 20 20  _IOERR_FSYNC    
4bf0: 20 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45           (SQLITE
4c00: 5f 49 4f 45 52 52 20 7c 20 28 34 3c 3c 38 29 29  _IOERR | (4<<8))
4c10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
4c20: 49 4f 45 52 52 5f 44 49 52 5f 46 53 59 4e 43 20  IOERR_DIR_FSYNC 
4c30: 20 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f          (SQLITE_
4c40: 49 4f 45 52 52 20 7c 20 28 35 3c 3c 38 29 29 0a  IOERR | (5<<8)).
4c50: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
4c60: 4f 45 52 52 5f 54 52 55 4e 43 41 54 45 20 20 20  OERR_TRUNCATE   
4c70: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49         (SQLITE_I
4c80: 4f 45 52 52 20 7c 20 28 36 3c 3c 38 29 29 0a 23  OERR | (6<<8)).#
4c90: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
4ca0: 45 52 52 5f 46 53 54 41 54 20 20 20 20 20 20 20  ERR_FSTAT       
4cb0: 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f        (SQLITE_IO
4cc0: 45 52 52 20 7c 20 28 37 3c 3c 38 29 29 0a 23 64  ERR | (7<<8)).#d
4cd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45  efine SQLITE_IOE
4ce0: 52 52 5f 55 4e 4c 4f 43 4b 20 20 20 20 20 20 20  RR_UNLOCK       
4cf0: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45       (SQLITE_IOE
4d00: 52 52 20 7c 20 28 38 3c 3c 38 29 29 0a 23 64 65  RR | (8<<8)).#de
4d10: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52  fine SQLITE_IOER
4d20: 52 5f 52 44 4c 4f 43 4b 20 20 20 20 20 20 20 20  R_RDLOCK        
4d30: 20 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52      (SQLITE_IOER
4d40: 52 20 7c 20 28 39 3c 3c 38 29 29 0a 23 64 65 66  R | (9<<8)).#def
4d50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4d60: 5f 44 45 4c 45 54 45 20 20 20 20 20 20 20 20 20  _DELETE         
4d70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4d80: 20 7c 20 28 31 30 3c 3c 38 29 29 0a 23 64 65 66   | (10<<8)).#def
4d90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4da0: 5f 42 4c 4f 43 4b 45 44 20 20 20 20 20 20 20 20  _BLOCKED        
4db0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4dc0: 20 7c 20 28 31 31 3c 3c 38 29 29 0a 23 64 65 66   | (11<<8)).#def
4dd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4de0: 5f 4e 4f 4d 45 4d 20 20 20 20 20 20 20 20 20 20  _NOMEM          
4df0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e00: 20 7c 20 28 31 32 3c 3c 38 29 29 0a 23 64 65 66   | (12<<8)).#def
4e10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e20: 5f 41 43 43 45 53 53 20 20 20 20 20 20 20 20 20  _ACCESS         
4e30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4e40: 20 7c 20 28 31 33 3c 3c 38 29 29 0a 23 64 65 66   | (13<<8)).#def
4e50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4e60: 5f 43 48 45 43 4b 52 45 53 45 52 56 45 44 4c 4f  _CHECKRESERVEDLO
4e70: 43 4b 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52  CK (SQLITE_IOERR
4e80: 20 7c 20 28 31 34 3c 3c 38 29 29 0a 23 64 65 66   | (14<<8)).#def
4e90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ea0: 5f 4c 4f 43 4b 20 20 20 20 20 20 20 20 20 20 20  _LOCK           
4eb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4ec0: 20 7c 20 28 31 35 3c 3c 38 29 29 0a 23 64 65 66   | (15<<8)).#def
4ed0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4ee0: 5f 43 4c 4f 53 45 20 20 20 20 20 20 20 20 20 20  _CLOSE          
4ef0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f00: 20 7c 20 28 31 36 3c 3c 38 29 29 0a 23 64 65 66   | (16<<8)).#def
4f10: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f20: 5f 44 49 52 5f 43 4c 4f 53 45 20 20 20 20 20 20  _DIR_CLOSE      
4f30: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f40: 20 7c 20 28 31 37 3c 3c 38 29 29 0a 23 64 65 66   | (17<<8)).#def
4f50: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4f60: 5f 53 48 4d 4f 50 45 4e 20 20 20 20 20 20 20 20  _SHMOPEN        
4f70: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4f80: 20 7c 20 28 31 38 3c 3c 38 29 29 0a 23 64 65 66   | (18<<8)).#def
4f90: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fa0: 5f 53 48 4d 53 49 5a 45 20 20 20 20 20 20 20 20  _SHMSIZE        
4fb0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
4fc0: 20 7c 20 28 31 39 3c 3c 38 29 29 0a 23 64 65 66   | (19<<8)).#def
4fd0: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
4fe0: 5f 53 48 4d 4c 4f 43 4b 20 20 20 20 20 20 20 20  _SHMLOCK        
4ff0: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5000: 20 7c 20 28 32 30 3c 3c 38 29 29 0a 23 64 65 66   | (20<<8)).#def
5010: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5020: 5f 53 48 4d 4d 41 50 20 20 20 20 20 20 20 20 20  _SHMMAP         
5030: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5040: 20 7c 20 28 32 31 3c 3c 38 29 29 0a 23 64 65 66   | (21<<8)).#def
5050: 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  ine SQLITE_IOERR
5060: 5f 53 45 45 4b 20 20 20 20 20 20 20 20 20 20 20  _SEEK           
5070: 20 20 20 28 53 51 4c 49 54 45 5f 49 4f 45 52 52     (SQLITE_IOERR
5080: 20 7c 20 28 32 32 3c 3c 38 29 29 0a 23 64 65 66   | (22<<8)).#def
5090: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 45  ine SQLITE_LOCKE
50a0: 44 5f 53 48 41 52 45 44 43 41 43 48 45 20 20 20  D_SHAREDCACHE   
50b0: 20 20 20 28 53 51 4c 49 54 45 5f 4c 4f 43 4b 45     (SQLITE_LOCKE
50c0: 44 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64 65  D |  (1<<8)).#de
50d0: 66 69 6e 65 20 53 51 4c 49 54 45 5f 42 55 53 59  fine SQLITE_BUSY
50e0: 5f 52 45 43 4f 56 45 52 59 20 20 20 20 20 20 20  _RECOVERY       
50f0: 20 20 20 20 28 53 51 4c 49 54 45 5f 42 55 53 59      (SQLITE_BUSY
5100: 20 20 20 7c 20 20 28 31 3c 3c 38 29 29 0a 23 64     |  (1<<8)).#d
5110: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 41 4e  efine SQLITE_CAN
5120: 54 4f 50 45 4e 5f 4e 4f 54 45 4d 50 44 49 52 20  TOPEN_NOTEMPDIR 
5130: 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43 41 4e       (SQLITE_CAN
5140: 54 4f 50 45 4e 20 7c 20 28 31 3c 3c 38 29 29 0a  TOPEN | (1<<8)).
5150: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
5160: 4f 52 52 55 50 54 5f 56 54 41 42 20 20 20 20 20  ORRUPT_VTAB     
5170: 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f 43         (SQLITE_C
5180: 4f 52 52 55 50 54 20 7c 20 28 31 3c 3c 38 29 29  ORRUPT | (1<<8))
5190: 0a 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  ..#define SQLITE
51a0: 5f 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45  _READONLY_RECOVE
51b0: 52 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45  RY       (SQLITE
51c0: 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c  _READONLY | (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 43 41 4e 54  TE_READONLY_CANT
51f0: 4c 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49  LOCK       (SQLI
5200: 54 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32  TE_READONLY | (2
5210: 3c 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  <<8))../*.** CAP
5220: 49 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72  I3REF: Flags For
5230: 20 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61   File Open Opera
5240: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73  tions.**.** Thes
5250: 65 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65  e bit values are
5260: 20 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73   intended for us
5270: 65 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20  e in the.** 3rd 
5280: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5290: 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76   [sqlite3_open_v
52a0: 32 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61  2()] interface a
52b0: 6e 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68  nd.** in the 4th
52c0: 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
52d0: 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78  e [sqlite3_vfs.x
52e0: 4f 70 65 6e 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2f  Open] method..*/
52f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5300: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
5310: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
5320: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5330: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5340: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5350: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5360: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5370: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5380: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5390: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53a0: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
53b0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
53c0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53d0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53e0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53f0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
5400: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
5410: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5420: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5430: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5440: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5450: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5460: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5470: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5480: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5490: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54b0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
54c0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 34 30        0x00000040
54d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
54e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
54f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5500: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5510: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
5520: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5530: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5540: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
5550: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
5560: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5570: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5580: 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5590: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
55a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
55c0: 4f 50 45 4e 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
55d0: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
55e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
55f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5600: 4f 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5610: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
5620: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5630: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5640: 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
5650: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
5660: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5670: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5680: 4f 50 45 4e 5f 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5690: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
56a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
56b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56c0: 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
56d0: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
56e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
56f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5700: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5710: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
5720: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
5730: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5740: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5750: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5760: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
5770: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5780: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5790: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57a0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57b0: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
57c0: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
57d0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57e0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
57f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5800: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5810: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
5820: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5830: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5840: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5850: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5860: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5870: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5880: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5890: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
58a0: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
58b0: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
58c0: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
58d0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
58e0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
58f0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
5900: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
5910: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
5920: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5930: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5940: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5950: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5960: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5970: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5980: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5990: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
59a0: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
59b0: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
59c0: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
59d0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
59e0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
59f0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5a00: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
5a10: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
5a20: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5a30: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5a40: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5a50: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5a60: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5a70: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5a80: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5a90: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5aa0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5ab0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5ac0: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5ad0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5ae0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5af0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5b00: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5b10: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5b20: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5b30: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5b40: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5b50: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5b60: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b70: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5b80: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5b90: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5ba0: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5bb0: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5bc0: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5bd0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5be0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bf0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
5c00: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5c10: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5c20: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5c30: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c40: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5c50: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c60: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
5c70: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5c80: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c90: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5ca0: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5cb0: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5cc0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5cd0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5ce0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5cf0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5d00: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5d10: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5d20: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5d30: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5d40: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5d50: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5d60: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5d70: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
5d80: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5d90: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5da0: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5db0: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5dc0: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5dd0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5de0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
5df0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5e00: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5e10: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5e20: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e30: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5e40: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
5e50: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
5e60: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a   0x00000800../*.
5e70: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5e80: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5e90: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
5ea0: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
5eb0: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5ec0: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
5ed0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
5ee0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
5ef0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
5f00: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
5f10: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
5f20: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5f30: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5f40: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
5f50: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
5f60: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f70: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
5f80: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f90: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
5fa0: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
5fb0: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
5fc0: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
5fd0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
5fe0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
5ff0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
6000: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
6010: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
6020: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6030: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6040: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6050: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6060: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6070: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6080: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6090: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
60a0: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
60b0: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
60c0: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
60d0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
60e0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
60f0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
6100: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
6110: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
6120: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6130: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6140: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6150: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6160: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6170: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6180: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6190: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
61a0: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
61b0: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
61c0: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
61d0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
61e0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
61f0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
6200: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
6210: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
6220: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
6230: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
6240: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6250: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6260: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6270: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6280: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6290: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
62a0: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
62b0: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
62c0: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
62d0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
62e0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
62f0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
6300: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
6310: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
6320: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
6330: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
6340: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
6350: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
6360: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6370: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6380: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
6390: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
63a0: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
63b0: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
63c0: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
63d0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
63e0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
63f0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
6400: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
6410: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
6420: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
6430: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
6440: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
6450: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
6460: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
6470: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6480: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6490: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
64a0: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
64b0: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
64c0: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
64d0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
64e0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
64f0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
6500: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
6510: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
6520: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
6530: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6540: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
6550: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
6560: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6570: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
6580: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6590: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
65a0: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
65b0: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
65c0: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
65d0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
65e0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
65f0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
6600: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
6610: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
6620: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
6630: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
6640: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6650: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6660: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6670: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6680: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6690: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
66a0: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
66b0: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
66c0: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
66d0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
66e0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
66f0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
6700: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
6710: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
6720: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
6730: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6740: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6750: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6760: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6770: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6780: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6790: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
67a0: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
67b0: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
67c0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
67d0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
67e0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
67f0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
6800: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
6810: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
6820: 76 66 73 2e 78 4f 70 65 6e 5d 20 6d 65 74 68 6f  vfs.xOpen] metho
6830: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
6840: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6850: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
6860: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
6870: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
6880: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6890: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
68a0: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
68b0: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
68c0: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
68d0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
68e0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
68f0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
6900: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
6910: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
6920: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
6930: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
6940: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
6950: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 5b 73 71 6c  *.** If the [sql
6960: 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e 5d 20  ite3_vfs.xOpen] 
6970: 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68 65 20  method sets the 
6980: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65  sqlite3_file.pMe
6990: 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20 0a 2a  thods element .*
69a0: 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  * to a non-NULL 
69b0: 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 74 68  pointer, then th
69c0: 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74  e sqlite3_io_met
69d0: 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65 74 68  hods.xClose meth
69e0: 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69 6e 76  od.** may be inv
69f0: 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74 68 65  oked even if the
6a00: 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f   [sqlite3_vfs.xO
6a10: 70 65 6e 5d 20 72 65 70 6f 72 74 65 64 20 74 68  pen] reported th
6a20: 61 74 20 69 74 20 66 61 69 6c 65 64 2e 20 20 54  at it failed.  T
6a30: 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77 61 79 20 74  he.** only way t
6a40: 6f 20 70 72 65 76 65 6e 74 20 61 20 63 61 6c 6c  o prevent a call
6a50: 20 74 6f 20 78 43 6c 6f 73 65 20 66 6f 6c 6c 6f   to xClose follo
6a60: 77 69 6e 67 20 61 20 66 61 69 6c 65 64 20 5b 73  wing a failed [s
6a70: 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70 65 6e  qlite3_vfs.xOpen
6a80: 5d 0a 2a 2a 20 69 73 20 66 6f 72 20 74 68 65 20  ].** is for the 
6a90: 5b 73 71 6c 69 74 65 33 5f 76 66 73 2e 78 4f 70  [sqlite3_vfs.xOp
6aa0: 65 6e 5d 20 74 6f 20 73 65 74 20 74 68 65 20 73  en] to set the s
6ab0: 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74  qlite3_file.pMet
6ac0: 68 6f 64 73 20 65 6c 65 6d 65 6e 74 0a 2a 2a 20  hods element.** 
6ad0: 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 54  to NULL..**.** T
6ae0: 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e  he flags argumen
6af0: 74 20 74 6f 20 78 53 79 6e 63 20 6d 61 79 20 62  t to xSync may b
6b00: 65 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  e one of [SQLITE
6b10: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 5d 20 6f 72  _SYNC_NORMAL] or
6b20: 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 53 59 4e 43  .** [SQLITE_SYNC
6b30: 5f 46 55 4c 4c 5d 2e 20 20 54 68 65 20 66 69 72  _FULL].  The fir
6b40: 73 74 20 63 68 6f 69 63 65 20 69 73 20 74 68 65  st choice is the
6b50: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 2e   normal fsync().
6b60: 0a 2a 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 63  .** The second c
6b70: 68 6f 69 63 65 20 69 73 20 61 20 4d 61 63 20 4f  hoice is a Mac O
6b80: 53 20 58 20 73 74 79 6c 65 20 66 75 6c 6c 73 79  S X style fullsy
6b90: 6e 63 2e 20 20 54 68 65 20 5b 53 51 4c 49 54 45  nc.  The [SQLITE
6ba0: 5f 53 59 4e 43 5f 44 41 54 41 4f 4e 4c 59 5d 0a  _SYNC_DATAONLY].
6bb0: 2a 2a 20 66 6c 61 67 20 6d 61 79 20 62 65 20 4f  ** flag may be O
6bc0: 52 65 64 20 69 6e 20 74 6f 20 69 6e 64 69 63 61  Red in to indica
6bd0: 74 65 20 74 68 61 74 20 6f 6e 6c 79 20 74 68 65  te that only the
6be0: 20 64 61 74 61 20 6f 66 20 74 68 65 20 66 69 6c   data of the fil
6bf0: 65 0a 2a 2a 20 61 6e 64 20 6e 6f 74 20 69 74 73  e.** and not its
6c00: 20 69 6e 6f 64 65 20 6e 65 65 64 73 20 74 6f 20   inode needs to 
6c10: 62 65 20 73 79 6e 63 65 64 2e 0a 2a 2a 0a 2a 2a  be synced..**.**
6c20: 20 54 68 65 20 69 6e 74 65 67 65 72 20 76 61 6c   The integer val
6c30: 75 65 73 20 74 6f 20 78 4c 6f 63 6b 28 29 20 61  ues to xLock() a
6c40: 6e 64 20 78 55 6e 6c 6f 63 6b 28 29 20 61 72 65  nd xUnlock() are
6c50: 20 6f 6e 65 20 6f 66 0a 2a 2a 20 3c 75 6c 3e 0a   one of.** <ul>.
6c60: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
6c70: 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c 0a 2a 2a 20 3c  LOCK_NONE],.** <
6c80: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6c90: 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  _SHARED],.** <li
6ca0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52  > [SQLITE_LOCK_R
6cb0: 45 53 45 52 56 45 44 5d 2c 0a 2a 2a 20 3c 6c 69  ESERVED],.** <li
6cc0: 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 50  > [SQLITE_LOCK_P
6cd0: 45 4e 44 49 4e 47 5d 2c 20 6f 72 0a 2a 2a 20 3c  ENDING], or.** <
6ce0: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b  li> [SQLITE_LOCK
6cf0: 5f 45 58 43 4c 55 53 49 56 45 5d 2e 0a 2a 2a 20  _EXCLUSIVE]..** 
6d00: 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c 6f 63 6b 28 29  </ul>.** xLock()
6d10: 20 69 6e 63 72 65 61 73 65 73 20 74 68 65 20 6c   increases the l
6d20: 6f 63 6b 2e 20 78 55 6e 6c 6f 63 6b 28 29 20 64  ock. xUnlock() d
6d30: 65 63 72 65 61 73 65 73 20 74 68 65 20 6c 6f 63  ecreases the loc
6d40: 6b 2e 0a 2a 2a 20 54 68 65 20 78 43 68 65 63 6b  k..** The xCheck
6d50: 52 65 73 65 72 76 65 64 4c 6f 63 6b 28 29 20 6d  ReservedLock() m
6d60: 65 74 68 6f 64 20 63 68 65 63 6b 73 20 77 68 65  ethod checks whe
6d70: 74 68 65 72 20 61 6e 79 20 64 61 74 61 62 61 73  ther any databas
6d80: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 0a 2a 2a  e connection,.**
6d90: 20 65 69 74 68 65 72 20 69 6e 20 74 68 69 73 20   either in this 
6da0: 70 72 6f 63 65 73 73 20 6f 72 20 69 6e 20 73 6f  process or in so
6db0: 6d 65 20 6f 74 68 65 72 20 70 72 6f 63 65 73 73  me other process
6dc0: 2c 20 69 73 20 68 6f 6c 64 69 6e 67 20 61 20 52  , is holding a R
6dd0: 45 53 45 52 56 45 44 2c 0a 2a 2a 20 50 45 4e 44  ESERVED,.** PEND
6de0: 49 4e 47 2c 20 6f 72 20 45 58 43 4c 55 53 49 56  ING, or EXCLUSIV
6df0: 45 20 6c 6f 63 6b 20 6f 6e 20 74 68 65 20 66 69  E lock on the fi
6e00: 6c 65 2e 20 20 49 74 20 72 65 74 75 72 6e 73 20  le.  It returns 
6e10: 74 72 75 65 0a 2a 2a 20 69 66 20 73 75 63 68 20  true.** if such 
6e20: 61 20 6c 6f 63 6b 20 65 78 69 73 74 73 20 61 6e  a lock exists an
6e30: 64 20 66 61 6c 73 65 20 6f 74 68 65 72 77 69 73  d false otherwis
6e40: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 46 69  e..**.** The xFi
6e50: 6c 65 43 6f 6e 74 72 6f 6c 28 29 20 6d 65 74 68  leControl() meth
6e60: 6f 64 20 69 73 20 61 20 67 65 6e 65 72 69 63 20  od is a generic 
6e70: 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20 61  interface that a
6e80: 6c 6c 6f 77 73 20 63 75 73 74 6f 6d 0a 2a 2a 20  llows custom.** 
6e90: 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  VFS implementati
6ea0: 6f 6e 73 20 74 6f 20 64 69 72 65 63 74 6c 79 20  ons to directly 
6eb0: 63 6f 6e 74 72 6f 6c 20 61 6e 20 6f 70 65 6e 20  control an open 
6ec0: 66 69 6c 65 20 75 73 69 6e 67 20 74 68 65 0a 2a  file using the.*
6ed0: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f  * [sqlite3_file_
6ee0: 63 6f 6e 74 72 6f 6c 28 29 5d 20 69 6e 74 65 72  control()] inter
6ef0: 66 61 63 65 2e 20 20 54 68 65 20 73 65 63 6f 6e  face.  The secon
6f00: 64 20 22 6f 70 22 20 61 72 67 75 6d 65 6e 74 20  d "op" argument 
6f10: 69 73 20 61 6e 0a 2a 2a 20 69 6e 74 65 67 65 72  is an.** integer
6f20: 20 6f 70 63 6f 64 65 2e 20 20 54 68 65 20 74 68   opcode.  The th
6f30: 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20  ird argument is 
6f40: 61 20 67 65 6e 65 72 69 63 20 70 6f 69 6e 74 65  a generic pointe
6f50: 72 20 69 6e 74 65 6e 64 65 64 20 74 6f 0a 2a 2a  r intended to.**
6f60: 20 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 75   point to a stru
6f70: 63 74 75 72 65 20 74 68 61 74 20 6d 61 79 20 63  cture that may c
6f80: 6f 6e 74 61 69 6e 20 61 72 67 75 6d 65 6e 74 73  ontain arguments
6f90: 20 6f 72 20 73 70 61 63 65 20 69 6e 20 77 68 69   or space in whi
6fa0: 63 68 20 74 6f 0a 2a 2a 20 77 72 69 74 65 20 72  ch to.** write r
6fb0: 65 74 75 72 6e 20 76 61 6c 75 65 73 2e 20 20 50  eturn values.  P
6fc0: 6f 74 65 6e 74 69 61 6c 20 75 73 65 73 20 66 6f  otential uses fo
6fd0: 72 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  r xFileControl()
6fe0: 20 6d 69 67 68 74 20 62 65 0a 2a 2a 20 66 75 6e   might be.** fun
6ff0: 63 74 69 6f 6e 73 20 74 6f 20 65 6e 61 62 6c 65  ctions to enable
7000: 20 62 6c 6f 63 6b 69 6e 67 20 6c 6f 63 6b 73 20   blocking locks 
7010: 77 69 74 68 20 74 69 6d 65 6f 75 74 73 2c 20 74  with timeouts, t
7020: 6f 20 63 68 61 6e 67 65 20 74 68 65 0a 2a 2a 20  o change the.** 
7030: 6c 6f 63 6b 69 6e 67 20 73 74 72 61 74 65 67 79  locking strategy
7040: 20 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 74 6f   (for example to
7050: 20 75 73 65 20 64 6f 74 2d 66 69 6c 65 20 6c 6f   use dot-file lo
7060: 63 6b 73 29 2c 20 74 6f 20 69 6e 71 75 69 72 65  cks), to inquire
7070: 0a 2a 2a 20 61 62 6f 75 74 20 74 68 65 20 73 74  .** about the st
7080: 61 74 75 73 20 6f 66 20 61 20 6c 6f 63 6b 2c 20  atus of a lock, 
7090: 6f 72 20 74 6f 20 62 72 65 61 6b 20 73 74 61 6c  or to break stal
70a0: 65 20 6c 6f 63 6b 73 2e 20 20 54 68 65 20 53 51  e locks.  The SQ
70b0: 4c 69 74 65 0a 2a 2a 20 63 6f 72 65 20 72 65 73  Lite.** core res
70c0: 65 72 76 65 73 20 61 6c 6c 20 6f 70 63 6f 64 65  erves all opcode
70d0: 73 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20  s less than 100 
70e0: 66 6f 72 20 69 74 73 20 6f 77 6e 20 75 73 65 2e  for its own use.
70f0: 0a 2a 2a 20 41 20 5b 53 51 4c 49 54 45 5f 46 43  .** A [SQLITE_FC
7100: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20 7c 20  NTL_LOCKSTATE | 
7110: 6c 69 73 74 20 6f 66 20 6f 70 63 6f 64 65 73 5d  list of opcodes]
7120: 20 6c 65 73 73 20 74 68 61 6e 20 31 30 30 20 69   less than 100 i
7130: 73 20 61 76 61 69 6c 61 62 6c 65 2e 0a 2a 2a 20  s available..** 
7140: 41 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61  Applications tha
7150: 74 20 64 65 66 69 6e 65 20 61 20 63 75 73 74 6f  t define a custo
7160: 6d 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d  m xFileControl m
7170: 65 74 68 6f 64 20 73 68 6f 75 6c 64 20 75 73 65  ethod should use
7180: 20 6f 70 63 6f 64 65 73 0a 2a 2a 20 67 72 65 61   opcodes.** grea
7190: 74 65 72 20 74 68 61 6e 20 31 30 30 20 74 6f 20  ter than 100 to 
71a0: 61 76 6f 69 64 20 63 6f 6e 66 6c 69 63 74 73 2e  avoid conflicts.
71b0: 20 20 56 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61    VFS implementa
71c0: 74 69 6f 6e 73 20 73 68 6f 75 6c 64 0a 2a 2a 20  tions should.** 
71d0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4e  return [SQLITE_N
71e0: 4f 54 46 4f 55 4e 44 5d 20 66 6f 72 20 66 69 6c  OTFOUND] for fil
71f0: 65 20 63 6f 6e 74 72 6f 6c 20 6f 70 63 6f 64 65  e control opcode
7200: 73 20 74 68 61 74 20 74 68 65 79 20 64 6f 20 6e  s that they do n
7210: 6f 74 0a 2a 2a 20 72 65 63 6f 67 6e 69 7a 65 2e  ot.** recognize.
7220: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 65 63 74  .**.** The xSect
7230: 6f 72 53 69 7a 65 28 29 20 6d 65 74 68 6f 64 20  orSize() method 
7240: 72 65 74 75 72 6e 73 20 74 68 65 20 73 65 63 74  returns the sect
7250: 6f 72 20 73 69 7a 65 20 6f 66 20 74 68 65 0a 2a  or size of the.*
7260: 2a 20 64 65 76 69 63 65 20 74 68 61 74 20 75 6e  * device that un
7270: 64 65 72 6c 69 65 73 20 74 68 65 20 66 69 6c 65  derlies the file
7280: 2e 20 20 54 68 65 20 73 65 63 74 6f 72 20 73 69  .  The sector si
7290: 7a 65 20 69 73 20 74 68 65 0a 2a 2a 20 6d 69 6e  ze is the.** min
72a0: 69 6d 75 6d 20 77 72 69 74 65 20 74 68 61 74 20  imum write that 
72b0: 63 61 6e 20 62 65 20 70 65 72 66 6f 72 6d 65 64  can be performed
72c0: 20 77 69 74 68 6f 75 74 20 64 69 73 74 75 72 62   without disturb
72d0: 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 62 79 74  ing.** other byt
72e0: 65 73 20 69 6e 20 74 68 65 20 66 69 6c 65 2e 20  es in the file. 
72f0: 20 54 68 65 20 78 44 65 76 69 63 65 43 68 61 72   The xDeviceChar
7300: 61 63 74 65 72 69 73 74 69 63 73 28 29 0a 2a 2a  acteristics().**
7310: 20 6d 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20   method returns 
7320: 61 20 62 69 74 20 76 65 63 74 6f 72 20 64 65 73  a bit vector des
7330: 63 72 69 62 69 6e 67 20 62 65 68 61 76 69 6f 72  cribing behavior
7340: 73 20 6f 66 20 74 68 65 0a 2a 2a 20 75 6e 64 65  s of the.** unde
7350: 72 6c 79 69 6e 67 20 64 65 76 69 63 65 3a 0a 2a  rlying device:.*
7360: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
7370: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7380: 41 54 4f 4d 49 43 5d 0a 2a 2a 20 3c 6c 69 3e 20  ATOMIC].** <li> 
7390: 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54  [SQLITE_IOCAP_AT
73a0: 4f 4d 49 43 35 31 32 5d 0a 2a 2a 20 3c 6c 69 3e  OMIC512].** <li>
73b0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
73c0: 54 4f 4d 49 43 31 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC1K].** <li>
73d0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
73e0: 54 4f 4d 49 43 32 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC2K].** <li>
73f0: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7400: 54 4f 4d 49 43 34 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC4K].** <li>
7410: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7420: 54 4f 4d 49 43 38 4b 5d 0a 2a 2a 20 3c 6c 69 3e  TOMIC8K].** <li>
7430: 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41   [SQLITE_IOCAP_A
7440: 54 4f 4d 49 43 31 36 4b 5d 0a 2a 2a 20 3c 6c 69  TOMIC16K].** <li
7450: 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  > [SQLITE_IOCAP_
7460: 41 54 4f 4d 49 43 33 32 4b 5d 0a 2a 2a 20 3c 6c  ATOMIC32K].** <l
7470: 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41 50  i> [SQLITE_IOCAP
7480: 5f 41 54 4f 4d 49 43 36 34 4b 5d 0a 2a 2a 20 3c  _ATOMIC64K].** <
7490: 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43 41  li> [SQLITE_IOCA
74a0: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 5d 0a 2a  P_SAFE_APPEND].*
74b0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
74c0: 4f 43 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 5d  OCAP_SEQUENTIAL]
74d0: 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20  .** </ul>.**.** 
74e0: 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50  The SQLITE_IOCAP
74f0: 5f 41 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79  _ATOMIC property
7500: 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20   means that all 
7510: 77 72 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79  writes of.** any
7520: 20 73 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63   size are atomic
7530: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
7540: 43 41 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61  CAP_ATOMICnnn va
7550: 6c 75 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61  lues.** mean tha
7560: 74 20 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63  t writes of bloc
7570: 6b 73 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20  ks that are nnn 
7580: 62 79 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e  bytes in size an
7590: 64 0a 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64  d.** are aligned
75a0: 20 74 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77   to an address w
75b0: 68 69 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67  hich is an integ
75c0: 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a  er multiple of.*
75d0: 2a 20 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63  * nnn are atomic
75e0: 2e 20 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f  .  The SQLITE_IO
75f0: 43 41 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20  CAP_SAFE_APPEND 
7600: 76 61 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74  value means.** t
7610: 68 61 74 20 77 68 65 6e 20 64 61 74 61 20 69 73  hat when data is
7620: 20 61 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66   appended to a f
7630: 69 6c 65 2c 20 74 68 65 20 64 61 74 61 20 69 73  ile, the data is
7640: 20 61 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72   appended.** fir
7650: 73 74 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65  st then the size
7660: 20 6f 66 20 74 68 65 20 66 69 6c 65 20 69 73 20   of the file is 
7670: 65 78 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20  extended, never 
7680: 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79  the other.** way
7690: 20 61 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51   around.  The SQ
76a0: 4c 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45  LITE_IOCAP_SEQUE
76b0: 4e 54 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d  NTIAL property m
76c0: 65 61 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66  eans that.** inf
76d0: 6f 72 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74  ormation is writ
76e0: 74 65 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74  ten to disk in t
76f0: 68 65 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73  he same order as
7700: 20 63 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72   calls.** to xWr
7710: 69 74 65 28 29 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  ite()..**.** If 
7720: 78 52 65 61 64 28 29 20 72 65 74 75 72 6e 73 20  xRead() returns 
7730: 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 53 48 4f  SQLITE_IOERR_SHO
7740: 52 54 5f 52 45 41 44 20 69 74 20 6d 75 73 74 20  RT_READ it must 
7750: 61 6c 73 6f 20 66 69 6c 6c 0a 2a 2a 20 69 6e 20  also fill.** in 
7760: 74 68 65 20 75 6e 72 65 61 64 20 70 6f 72 74 69  the unread porti
7770: 6f 6e 73 20 6f 66 20 74 68 65 20 62 75 66 66 65  ons of the buffe
7780: 72 20 77 69 74 68 20 7a 65 72 6f 73 2e 20 20 41  r with zeros.  A
7790: 20 56 46 53 20 74 68 61 74 0a 2a 2a 20 66 61 69   VFS that.** fai
77a0: 6c 73 20 74 6f 20 7a 65 72 6f 2d 66 69 6c 6c 20  ls to zero-fill 
77b0: 73 68 6f 72 74 20 72 65 61 64 73 20 6d 69 67 68  short reads migh
77c0: 74 20 73 65 65 6d 20 74 6f 20 77 6f 72 6b 2e 20  t seem to work. 
77d0: 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 61 69   However,.** fai
77e0: 6c 75 72 65 20 74 6f 20 7a 65 72 6f 2d 66 69 6c  lure to zero-fil
77f0: 6c 20 73 68 6f 72 74 20 72 65 61 64 73 20 77 69  l short reads wi
7800: 6c 6c 20 65 76 65 6e 74 75 61 6c 6c 79 20 6c 65  ll eventually le
7810: 61 64 20 74 6f 0a 2a 2a 20 64 61 74 61 62 61 73  ad to.** databas
7820: 65 20 63 6f 72 72 75 70 74 69 6f 6e 2e 0a 2a 2f  e corruption..*/
7830: 0a 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20  .typedef struct 
7840: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
7850: 64 73 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ds sqlite3_io_me
7860: 74 68 6f 64 73 3b 0a 73 74 72 75 63 74 20 73 71  thods;.struct sq
7870: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7880: 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73 69 6f   {.  int iVersio
7890: 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6c 6f 73  n;.  int (*xClos
78a0: 65 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  e)(sqlite3_file*
78b0: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 61 64  );.  int (*xRead
78c0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
78d0: 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d 74   void*, int iAmt
78e0: 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  , sqlite3_int64 
78f0: 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28 2a  iOfst);.  int (*
7900: 78 57 72 69 74 65 29 28 73 71 6c 69 74 65 33 5f  xWrite)(sqlite3_
7910: 66 69 6c 65 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  file*, const voi
7920: 64 2a 2c 20 69 6e 74 20 69 41 6d 74 2c 20 73 71  d*, int iAmt, sq
7930: 6c 69 74 65 33 5f 69 6e 74 36 34 20 69 4f 66 73  lite3_int64 iOfs
7940: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 54 72 75  t);.  int (*xTru
7950: 6e 63 61 74 65 29 28 73 71 6c 69 74 65 33 5f 66  ncate)(sqlite3_f
7960: 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69 6e  ile*, sqlite3_in
7970: 74 36 34 20 73 69 7a 65 29 3b 0a 20 20 69 6e 74  t64 size);.  int
7980: 20 28 2a 78 53 79 6e 63 29 28 73 71 6c 69 74 65   (*xSync)(sqlite
7990: 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 66 6c 61  3_file*, int fla
79a0: 67 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69  gs);.  int (*xFi
79b0: 6c 65 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f  leSize)(sqlite3_
79c0: 66 69 6c 65 2a 2c 20 73 71 6c 69 74 65 33 5f 69  file*, sqlite3_i
79d0: 6e 74 36 34 20 2a 70 53 69 7a 65 29 3b 0a 20 20  nt64 *pSize);.  
79e0: 69 6e 74 20 28 2a 78 4c 6f 63 6b 29 28 73 71 6c  int (*xLock)(sql
79f0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 29  ite3_file*, int)
7a00: 3b 0a 20 20 69 6e 74 20 28 2a 78 55 6e 6c 6f 63  ;.  int (*xUnloc
7a10: 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a  k)(sqlite3_file*
7a20: 2c 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a  , int);.  int (*
7a30: 78 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f  xCheckReservedLo
7a40: 63 6b 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  ck)(sqlite3_file
7a50: 2a 2c 20 69 6e 74 20 2a 70 52 65 73 4f 75 74 29  *, int *pResOut)
7a60: 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 65 43  ;.  int (*xFileC
7a70: 6f 6e 74 72 6f 6c 29 28 73 71 6c 69 74 65 33 5f  ontrol)(sqlite3_
7a80: 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 70 2c 20 76  file*, int op, v
7a90: 6f 69 64 20 2a 70 41 72 67 29 3b 0a 20 20 69 6e  oid *pArg);.  in
7aa0: 74 20 28 2a 78 53 65 63 74 6f 72 53 69 7a 65 29  t (*xSectorSize)
7ab0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7ac0: 0a 20 20 69 6e 74 20 28 2a 78 44 65 76 69 63 65  .  int (*xDevice
7ad0: 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73 29  Characteristics)
7ae0: 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b  (sqlite3_file*);
7af0: 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61 62  .  /* Methods ab
7b00: 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66 6f  ove are valid fo
7b10: 72 20 76 65 72 73 69 6f 6e 20 31 20 2a 2f 0a 20  r version 1 */. 
7b20: 20 69 6e 74 20 28 2a 78 53 68 6d 4d 61 70 29 28   int (*xShmMap)(
7b30: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7b40: 6e 74 20 69 50 67 2c 20 69 6e 74 20 70 67 73 7a  nt iPg, int pgsz
7b50: 2c 20 69 6e 74 2c 20 76 6f 69 64 20 76 6f 6c 61  , int, void vola
7b60: 74 69 6c 65 2a 2a 29 3b 0a 20 20 69 6e 74 20 28  tile**);.  int (
7b70: 2a 78 53 68 6d 4c 6f 63 6b 29 28 73 71 6c 69 74  *xShmLock)(sqlit
7b80: 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 6f 66  e3_file*, int of
7b90: 66 73 65 74 2c 20 69 6e 74 20 6e 2c 20 69 6e 74  fset, int n, int
7ba0: 20 66 6c 61 67 73 29 3b 0a 20 20 76 6f 69 64 20   flags);.  void 
7bb0: 28 2a 78 53 68 6d 42 61 72 72 69 65 72 29 28 73  (*xShmBarrier)(s
7bc0: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 29 3b 0a 20  qlite3_file*);. 
7bd0: 20 69 6e 74 20 28 2a 78 53 68 6d 55 6e 6d 61 70   int (*xShmUnmap
7be0: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7bf0: 20 69 6e 74 20 64 65 6c 65 74 65 46 6c 61 67 29   int deleteFlag)
7c00: 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f 64 73 20 61  ;.  /* Methods a
7c10: 62 6f 76 65 20 61 72 65 20 76 61 6c 69 64 20 66  bove are valid f
7c20: 6f 72 20 76 65 72 73 69 6f 6e 20 32 20 2a 2f 0a  or version 2 */.
7c30: 20 20 2f 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20    /* Additional 
7c40: 6d 65 74 68 6f 64 73 20 6d 61 79 20 62 65 20 61  methods may be a
7c50: 64 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72  dded in future r
7c60: 65 6c 65 61 73 65 73 20 2a 2f 0a 7d 3b 0a 0a 2f  eleases */.};../
7c70: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
7c80: 74 61 6e 64 61 72 64 20 46 69 6c 65 20 43 6f 6e  tandard File Con
7c90: 74 72 6f 6c 20 4f 70 63 6f 64 65 73 0a 2a 2a 0a  trol Opcodes.**.
7ca0: 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65 72  ** These integer
7cb0: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 6f   constants are o
7cc0: 70 63 6f 64 65 73 20 66 6f 72 20 74 68 65 20 78  pcodes for the x
7cd0: 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68  FileControl meth
7ce0: 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20 5b 73 71  od.** of the [sq
7cf0: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
7d00: 5d 20 6f 62 6a 65 63 74 20 61 6e 64 20 66 6f 72  ] object and for
7d10: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69   the [sqlite3_fi
7d20: 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 0a 2a 2a  le_control()].**
7d30: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
7d40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
7d50: 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 5d 20 6f  NTL_LOCKSTATE] o
7d60: 70 63 6f 64 65 20 69 73 20 75 73 65 64 20 66 6f  pcode is used fo
7d70: 72 20 64 65 62 75 67 67 69 6e 67 2e 20 20 54 68  r debugging.  Th
7d80: 69 73 0a 2a 2a 20 6f 70 63 6f 64 65 20 63 61 75  is.** opcode cau
7d90: 73 65 73 20 74 68 65 20 78 46 69 6c 65 43 6f 6e  ses the xFileCon
7da0: 74 72 6f 6c 20 6d 65 74 68 6f 64 20 74 6f 20 77  trol method to w
7db0: 72 69 74 65 20 74 68 65 20 63 75 72 72 65 6e 74  rite the current
7dc0: 20 73 74 61 74 65 20 6f 66 0a 2a 2a 20 74 68 65   state of.** the
7dd0: 20 6c 6f 63 6b 20 28 6f 6e 65 20 6f 66 20 5b 53   lock (one of [S
7de0: 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d  QLITE_LOCK_NONE]
7df0: 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 53  , [SQLITE_LOCK_S
7e00: 48 41 52 45 44 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  HARED],.** [SQLI
7e10: 54 45 5f 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44  TE_LOCK_RESERVED
7e20: 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  ], [SQLITE_LOCK_
7e30: 50 45 4e 44 49 4e 47 5d 2c 20 6f 72 20 5b 53 51  PENDING], or [SQ
7e40: 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53  LITE_LOCK_EXCLUS
7e50: 49 56 45 5d 29 0a 2a 2a 20 69 6e 74 6f 20 61 6e  IVE]).** into an
7e60: 20 69 6e 74 65 67 65 72 20 74 68 61 74 20 74 68   integer that th
7e70: 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e 74 20  e pArg argument 
7e80: 70 6f 69 6e 74 73 20 74 6f 2e 20 54 68 69 73 20  points to. This 
7e90: 63 61 70 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73  capability.** is
7ea0: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
7eb0: 74 69 6e 67 20 61 6e 64 20 6f 6e 6c 79 20 6e 65  ting and only ne
7ec0: 65 64 73 20 74 6f 20 62 65 20 73 75 70 70 6f 72  eds to be suppor
7ed0: 74 65 64 20 77 68 65 6e 20 53 51 4c 49 54 45 5f  ted when SQLITE_
7ee0: 54 45 53 54 0a 2a 2a 20 69 73 20 64 65 66 69 6e  TEST.** is defin
7ef0: 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53  ed..**.** The [S
7f00: 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45  QLITE_FCNTL_SIZE
7f10: 5f 48 49 4e 54 5d 20 6f 70 63 6f 64 65 20 69 73  _HINT] opcode is
7f20: 20 75 73 65 64 20 62 79 20 53 51 4c 69 74 65 20   used by SQLite 
7f30: 74 6f 20 67 69 76 65 20 74 68 65 20 56 46 53 0a  to give the VFS.
7f40: 2a 2a 20 6c 61 79 65 72 20 61 20 68 69 6e 74 20  ** layer a hint 
7f50: 6f 66 20 68 6f 77 20 6c 61 72 67 65 20 74 68 65  of how large the
7f60: 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 77   database file w
7f70: 69 6c 6c 20 67 72 6f 77 20 74 6f 20 62 65 20 64  ill grow to be d
7f80: 75 72 69 6e 67 20 74 68 65 0a 2a 2a 20 63 75 72  uring the.** cur
7f90: 72 65 6e 74 20 74 72 61 6e 73 61 63 74 69 6f 6e  rent transaction
7fa0: 2e 20 20 54 68 69 73 20 68 69 6e 74 20 69 73 20  .  This hint is 
7fb0: 6e 6f 74 20 67 75 61 72 61 6e 74 65 65 64 20 74  not guaranteed t
7fc0: 6f 20 62 65 20 61 63 63 75 72 61 74 65 20 62 75  o be accurate bu
7fd0: 74 20 69 74 0a 2a 2a 20 69 73 20 6f 66 74 65 6e  t it.** is often
7fe0: 20 63 6c 6f 73 65 2e 20 20 54 68 65 20 75 6e 64   close.  The und
7ff0: 65 72 6c 79 69 6e 67 20 56 46 53 20 6d 69 67 68  erlying VFS migh
8000: 74 20 63 68 6f 6f 73 65 20 74 6f 20 70 72 65 61  t choose to prea
8010: 6c 6c 6f 63 61 74 65 20 64 61 74 61 62 61 73 65  llocate database
8020: 0a 2a 2a 20 66 69 6c 65 20 73 70 61 63 65 20 62  .** file space b
8030: 61 73 65 64 20 6f 6e 20 74 68 69 73 20 68 69 6e  ased on this hin
8040: 74 20 69 6e 20 6f 72 64 65 72 20 74 6f 20 68 65  t in order to he
8050: 6c 70 20 77 72 69 74 65 73 20 74 6f 20 74 68 65  lp writes to the
8060: 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c   database.** fil
8070: 65 20 72 75 6e 20 66 61 73 74 65 72 2e 0a 2a 2a  e run faster..**
8080: 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f  .** The [SQLITE_
8090: 46 43 4e 54 4c 5f 43 48 55 4e 4b 5f 53 49 5a 45  FCNTL_CHUNK_SIZE
80a0: 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65 64  ] opcode is used
80b0: 20 74 6f 20 72 65 71 75 65 73 74 20 74 68 61 74   to request that
80c0: 20 74 68 65 20 56 46 53 0a 2a 2a 20 65 78 74 65   the VFS.** exte
80d0: 6e 64 73 20 61 6e 64 20 74 72 75 6e 63 61 74 65  nds and truncate
80e0: 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  s the database f
80f0: 69 6c 65 20 69 6e 20 63 68 75 6e 6b 73 20 6f 66  ile in chunks of
8100: 20 61 20 73 69 7a 65 20 73 70 65 63 69 66 69 65   a size specifie
8110: 64 0a 2a 2a 20 62 79 20 74 68 65 20 75 73 65 72  d.** by the user
8120: 2e 20 54 68 65 20 66 6f 75 72 74 68 20 61 72 67  . The fourth arg
8130: 75 6d 65 6e 74 20 74 6f 20 5b 73 71 6c 69 74 65  ument to [sqlite
8140: 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29  3_file_control()
8150: 5d 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 70 6f 69  ] should .** poi
8160: 6e 74 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72  nt to an integer
8170: 20 28 74 79 70 65 20 69 6e 74 29 20 63 6f 6e 74   (type int) cont
8180: 61 69 6e 69 6e 67 20 74 68 65 20 6e 65 77 20 63  aining the new c
8190: 68 75 6e 6b 2d 73 69 7a 65 20 74 6f 20 75 73 65  hunk-size to use
81a0: 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6e 6f 6d 69  .** for the nomi
81b0: 6e 61 74 65 64 20 64 61 74 61 62 61 73 65 2e 20  nated database. 
81c0: 41 6c 6c 6f 63 61 74 69 6e 67 20 64 61 74 61 62  Allocating datab
81d0: 61 73 65 20 66 69 6c 65 20 73 70 61 63 65 20 69  ase file space i
81e0: 6e 20 6c 61 72 67 65 0a 2a 2a 20 63 68 75 6e 6b  n large.** chunk
81f0: 73 20 28 73 61 79 20 31 4d 42 20 61 74 20 61 20  s (say 1MB at a 
8200: 74 69 6d 65 29 2c 20 6d 61 79 20 72 65 64 75 63  time), may reduc
8210: 65 20 66 69 6c 65 2d 73 79 73 74 65 6d 20 66 72  e file-system fr
8220: 61 67 6d 65 6e 74 61 74 69 6f 6e 20 61 6e 64 0a  agmentation and.
8230: 2a 2a 20 69 6d 70 72 6f 76 65 20 70 65 72 66 6f  ** improve perfo
8240: 72 6d 61 6e 63 65 20 6f 6e 20 73 6f 6d 65 20 73  rmance on some s
8250: 79 73 74 65 6d 73 2e 0a 2a 2a 0a 2a 2a 20 54 68  ystems..**.** Th
8260: 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f  e [SQLITE_FCNTL_
8270: 46 49 4c 45 5f 50 4f 49 4e 54 45 52 5d 20 6f 70  FILE_POINTER] op
8280: 63 6f 64 65 20 69 73 20 75 73 65 64 20 74 6f 20  code is used to 
8290: 6f 62 74 61 69 6e 20 61 20 70 6f 69 6e 74 65 72  obtain a pointer
82a0: 0a 2a 2a 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  .** to the [sqli
82b0: 74 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74  te3_file] object
82c0: 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
82d0: 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 64 61   a particular da
82e0: 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e 65 63  tabase.** connec
82f0: 74 69 6f 6e 2e 20 20 53 65 65 20 74 68 65 20 5b  tion.  See the [
8300: 73 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e  sqlite3_file_con
8310: 74 72 6f 6c 28 29 5d 20 64 6f 63 75 6d 65 6e 74  trol()] document
8320: 61 74 69 6f 6e 20 66 6f 72 0a 2a 2a 20 61 64 64  ation for.** add
8330: 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d 61 74  itional informat
8340: 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ion..**.** ^(The
8350: 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53   [SQLITE_FCNTL_S
8360: 59 4e 43 5f 4f 4d 49 54 54 45 44 5d 20 6f 70 63  YNC_OMITTED] opc
8370: 6f 64 65 20 69 73 20 67 65 6e 65 72 61 74 65 64  ode is generated
8380: 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79 0a 2a   internally by.*
8390: 2a 20 53 51 4c 69 74 65 20 61 6e 64 20 73 65 6e  * SQLite and sen
83a0: 74 20 74 6f 20 61 6c 6c 20 56 46 53 65 73 20 69  t to all VFSes i
83b0: 6e 20 70 6c 61 63 65 20 6f 66 20 61 20 63 61 6c  n place of a cal
83c0: 6c 20 74 6f 20 74 68 65 20 78 53 79 6e 63 20 6d  l to the xSync m
83d0: 65 74 68 6f 64 0a 2a 2a 20 77 68 65 6e 20 74 68  ethod.** when th
83e0: 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
83f0: 63 74 69 6f 6e 20 68 61 73 20 5b 50 52 41 47 4d  ction has [PRAGM
8400: 41 20 73 79 6e 63 68 72 6f 6e 6f 75 73 5d 20 73  A synchronous] s
8410: 65 74 20 74 6f 20 4f 46 46 2e 29 5e 0a 2a 2a 20  et to OFF.)^.** 
8420: 53 6f 6d 65 20 73 70 65 63 69 61 6c 69 7a 65 64  Some specialized
8430: 20 56 46 53 65 73 20 6e 65 65 64 20 74 68 69 73   VFSes need this
8440: 20 73 69 67 6e 61 6c 20 69 6e 20 6f 72 64 65 72   signal in order
8450: 20 74 6f 20 6f 70 65 72 61 74 65 20 63 6f 72 72   to operate corr
8460: 65 63 74 6c 79 0a 2a 2a 20 77 68 65 6e 20 5b 50  ectly.** when [P
8470: 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f 75  RAGMA synchronou
8480: 73 20 7c 20 50 52 41 47 4d 41 20 73 79 6e 63 68  s | PRAGMA synch
8490: 72 6f 6e 6f 75 73 3d 4f 46 46 5d 20 69 73 20 73  ronous=OFF] is s
84a0: 65 74 2c 20 62 75 74 20 6d 6f 73 74 20 0a 2a 2a  et, but most .**
84b0: 20 56 46 53 65 73 20 64 6f 20 6e 6f 74 20 6e 65   VFSes do not ne
84c0: 65 64 20 74 68 69 73 20 73 69 67 6e 61 6c 20 61  ed this signal a
84d0: 6e 64 20 73 68 6f 75 6c 64 20 73 69 6c 65 6e 74  nd should silent
84e0: 6c 79 20 69 67 6e 6f 72 65 20 74 68 69 73 20 6f  ly ignore this o
84f0: 70 63 6f 64 65 2e 0a 2a 2a 20 41 70 70 6c 69 63  pcode..** Applic
8500: 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20 6e 6f  ations should no
8510: 74 20 63 61 6c 6c 20 5b 73 71 6c 69 74 65 33 5f  t call [sqlite3_
8520: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
8530: 77 69 74 68 20 74 68 69 73 0a 2a 2a 20 6f 70 63  with this.** opc
8540: 6f 64 65 20 61 73 20 64 6f 69 6e 67 20 73 6f 20  ode as doing so 
8550: 6d 61 79 20 64 69 73 72 75 70 74 20 74 68 65 20  may disrupt the 
8560: 6f 70 65 72 61 74 69 6f 6e 20 6f 66 20 74 68 65  operation of the
8570: 20 73 70 65 63 69 61 6c 69 7a 65 64 20 56 46 53   specialized VFS
8580: 65 73 0a 2a 2a 20 74 68 61 74 20 64 6f 20 72 65  es.** that do re
8590: 71 75 69 72 65 20 69 74 2e 20 20 0a 2a 2a 0a 2a  quire it.  .**.*
85a0: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  * The [SQLITE_FC
85b0: 4e 54 4c 5f 52 45 41 44 4f 4e 4c 59 5f 53 48 4d  NTL_READONLY_SHM
85c0: 5d 20 6d 61 79 20 62 65 20 67 65 6e 65 72 61 74  ] may be generat
85d0: 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 20 62 79  ed internally by
85e0: 20 53 51 4c 69 74 65 20 69 66 0a 2a 2a 20 74 68   SQLite if.** th
85f0: 65 20 22 72 65 61 64 6f 6e 6c 79 5f 73 68 6d 3d  e "readonly_shm=
8600: 31 22 20 55 52 49 20 6f 70 74 69 6f 6e 20 69 73  1" URI option is
8610: 20 73 70 65 63 69 66 69 65 64 20 77 68 65 6e 20   specified when 
8620: 74 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  the database is 
8630: 6f 70 65 6e 65 64 2e 0a 2a 2a 20 54 68 65 20 66  opened..** The f
8640: 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 20 70  ourth argument p
8650: 61 73 73 65 64 20 74 6f 20 74 68 65 20 56 46 53  assed to the VFS
8660: 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65   xFileControl me
8670: 74 68 6f 64 73 20 69 73 20 61 20 70 6f 69 6e 74  thods is a point
8680: 65 72 0a 2a 2a 20 74 6f 20 61 20 76 61 72 69 61  er.** to a varia
8690: 62 6c 65 20 6f 66 20 74 79 70 65 20 22 69 6e 74  ble of type "int
86a0: 22 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  " containing the
86b0: 20 76 61 6c 75 65 20 31 20 6f 72 20 30 2e 20 49   value 1 or 0. I
86c0: 66 20 74 68 65 20 76 61 72 69 61 62 6c 65 0a 2a  f the variable.*
86d0: 2a 20 63 6f 6e 74 61 69 6e 73 20 74 68 65 20 76  * contains the v
86e0: 61 6c 75 65 20 31 2c 20 74 68 65 6e 20 74 68 69  alue 1, then thi
86f0: 73 20 69 6e 64 69 63 61 74 65 73 20 74 6f 20 74  s indicates to t
8700: 68 65 20 56 46 53 20 74 68 61 74 20 61 20 72 65  he VFS that a re
8710: 61 64 2d 6f 6e 6c 79 0a 2a 2a 20 6d 61 70 70 69  ad-only.** mappi
8720: 6e 67 20 6f 66 20 74 68 65 20 73 68 61 72 65 64  ng of the shared
8730: 2d 6d 65 6d 6f 72 79 20 72 65 67 69 6f 6e 20 69  -memory region i
8740: 73 20 61 63 63 65 70 74 61 62 6c 65 2e 20 49 66  s acceptable. If
8750: 20 69 74 20 69 73 20 73 65 74 20 74 6f 20 30 2c   it is set to 0,
8760: 20 74 68 65 6e 0a 2a 2a 20 74 68 69 73 20 69 6e   then.** this in
8770: 64 69 63 61 74 65 73 20 74 68 61 74 20 61 20 72  dicates that a r
8780: 65 61 64 2d 77 72 69 74 65 20 6d 61 70 70 69 6e  ead-write mappin
8790: 67 20 69 73 20 72 65 71 75 69 72 65 64 20 28 61  g is required (a
87a0: 73 20 6e 6f 72 6d 61 6c 29 2e 20 49 66 0a 2a 2a  s normal). If.**
87b0: 20 61 20 72 65 61 64 2d 6f 6e 6c 79 20 6d 61 70   a read-only map
87c0: 70 69 6e 67 20 69 73 20 72 65 74 75 72 6e 65 64  ping is returned
87d0: 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20 6d  , then the VFS m
87e0: 61 79 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 72  ay also return r
87f0: 65 61 64 2d 6f 6e 6c 79 0a 2a 2a 20 6d 61 70 70  ead-only.** mapp
8800: 69 6e 67 73 20 66 6f 72 20 61 6e 79 20 73 75 62  ings for any sub
8810: 73 65 71 75 65 6e 74 20 72 65 71 75 65 73 74 73  sequent requests
8820: 20 76 69 61 20 74 68 65 20 73 61 6d 65 20 66 69   via the same fi
8830: 6c 65 2d 64 65 73 63 72 69 70 74 6f 72 20 2d 0a  le-descriptor -.
8840: 2a 2a 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66  ** regardless of
8850: 20 74 68 65 20 76 61 6c 75 65 20 6d 6f 73 74 20   the value most 
8860: 72 65 63 65 6e 74 6c 79 20 63 6f 6e 66 69 67 75  recently configu
8870: 72 65 64 20 75 73 69 6e 67 0a 2a 2a 20 53 51 4c  red using.** SQL
8880: 49 54 45 5f 46 43 4e 54 4c 5f 52 45 41 44 4f 4e  ITE_FCNTL_READON
8890: 4c 59 5f 53 48 4d 2e 0a 2a 2a 0a 2a 2a 20 49 6e  LY_SHM..**.** In
88a0: 20 70 72 61 63 74 69 63 65 2c 20 69 66 20 22 72   practice, if "r
88b0: 65 61 64 6f 6e 6c 79 5f 73 68 6d 3d 31 22 20 69  eadonly_shm=1" i
88c0: 73 20 73 70 65 63 69 66 69 65 64 20 61 6e 64 20  s specified and 
88d0: 74 68 65 20 66 69 72 73 74 20 61 74 74 65 6d 70  the first attemp
88e0: 74 20 74 6f 0a 2a 2a 20 6d 61 70 20 61 20 73 68  t to.** map a sh
88f0: 61 72 65 64 2d 6d 65 6d 6f 72 79 20 72 65 67 69  ared-memory regi
8900: 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20 74  on fails, then t
8910: 68 69 73 20 66 69 6c 65 2d 63 6f 6e 74 72 6f 6c  his file-control
8920: 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 69 74 68   is invoked with
8930: 0a 2a 2a 20 74 68 65 20 61 72 67 75 6d 65 6e 74  .** the argument
8940: 20 76 61 72 69 61 62 6c 65 20 73 65 74 20 74 6f   variable set to
8950: 20 31 20 61 6e 64 20 61 20 73 65 63 6f 6e 64 20   1 and a second 
8960: 61 74 74 65 6d 70 74 20 74 6f 20 6d 61 70 20 74  attempt to map t
8970: 68 65 20 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79  he shared-memory
8980: 0a 2a 2a 20 72 65 67 69 6f 6e 20 69 73 20 6d 61  .** region is ma
8990: 64 65 2e 20 49 66 20 74 68 69 73 20 6d 61 70 70  de. If this mapp
89a0: 69 6e 67 20 73 75 63 63 65 65 64 73 2c 20 74 68  ing succeeds, th
89b0: 65 6e 20 74 68 65 20 63 6f 6e 6e 65 63 74 69 6f  en the connectio
89c0: 6e 20 63 6f 6e 74 69 6e 75 65 73 0a 2a 2a 20 77  n continues.** w
89d0: 69 74 68 20 74 68 65 20 72 65 61 64 2d 6f 6e 6c  ith the read-onl
89e0: 79 20 6d 61 70 70 69 6e 67 2e 20 4f 74 68 65 72  y mapping. Other
89f0: 77 69 73 65 2c 20 69 66 20 69 74 20 66 61 69 6c  wise, if it fail
8a00: 73 2c 20 53 51 4c 49 54 45 5f 43 41 4e 54 4f 50  s, SQLITE_CANTOP
8a10: 45 4e 20 69 73 0a 2a 2a 20 72 65 74 75 72 6e 65  EN is.** returne
8a20: 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
8a30: 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20   Whether or not 
8a40: 74 68 65 20 73 65 63 6f 6e 64 20 28 72 65 61 64  the second (read
8a50: 2d 6f 6e 6c 79 29 20 6d 61 70 70 69 6e 67 0a 2a  -only) mapping.*
8a60: 2a 20 61 74 74 65 6d 70 74 20 73 75 63 63 65 65  * attempt succee
8a70: 64 73 2c 20 74 68 65 20 66 69 6c 65 2d 63 6f 6e  ds, the file-con
8a80: 74 72 6f 6c 20 69 73 20 69 6e 76 6f 6b 65 64 20  trol is invoked 
8a90: 61 67 61 69 6e 20 77 69 74 68 20 74 68 65 20 61  again with the a
8aa0: 72 67 75 6d 65 6e 74 0a 2a 2a 20 76 61 72 69 61  rgument.** varia
8ab0: 62 6c 65 20 73 65 74 20 74 6f 20 30 2e 0a 2a 2f  ble set to 0..*/
8ac0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8ad0: 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41 54 45 20  FCNTL_LOCKSTATE 
8ae0: 20 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65         1.#define
8af0: 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c 4f 43 4b   SQLITE_GET_LOCK
8b00: 50 52 4f 58 59 46 49 4c 45 20 20 20 20 20 20 32  PROXYFILE      2
8b10: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8b20: 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59 46 49 4c  SET_LOCKPROXYFIL
8b30: 45 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65  E      3.#define
8b40: 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f 45 52 52   SQLITE_LAST_ERR
8b50: 4e 4f 20 20 20 20 20 20 20 20 20 20 20 20 20 34  NO             4
8b60: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8b70: 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49 4e 54 20  FCNTL_SIZE_HINT 
8b80: 20 20 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65         5.#define
8b90: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48   SQLITE_FCNTL_CH
8ba0: 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20 20 20 36  UNK_SIZE       6
8bb0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8bc0: 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54  FCNTL_FILE_POINT
8bd0: 45 52 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65  ER     7.#define
8be0: 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c 5f 53 59   SQLITE_FCNTL_SY
8bf0: 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20 20 20 38  NC_OMITTED     8
8c00: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
8c10: 46 43 4e 54 4c 5f 52 45 41 44 4f 4e 4c 59 5f 53  FCNTL_READONLY_S
8c20: 48 4d 20 20 20 20 20 39 0a 0a 0a 2f 2a 0a 2a 2a  HM     9.../*.**
8c30: 20 43 41 50 49 33 52 45 46 3a 20 4d 75 74 65 78   CAPI3REF: Mutex
8c40: 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a 20 54 68   Handle.**.** Th
8c50: 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c 65 20 77  e mutex module w
8c60: 69 74 68 69 6e 20 53 51 4c 69 74 65 20 64 65 66  ithin SQLite def
8c70: 69 6e 65 73 20 5b 73 71 6c 69 74 65 33 5f 6d 75  ines [sqlite3_mu
8c80: 74 65 78 5d 20 74 6f 20 62 65 20 61 6e 0a 2a 2a  tex] to be an.**
8c90: 20 61 62 73 74 72 61 63 74 20 74 79 70 65 20 66   abstract type f
8ca0: 6f 72 20 61 20 6d 75 74 65 78 20 6f 62 6a 65 63  or a mutex objec
8cb0: 74 2e 20 20 54 68 65 20 53 51 4c 69 74 65 20 63  t.  The SQLite c
8cc0: 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f 6b 73 0a  ore never looks.
8cd0: 2a 2a 20 61 74 20 74 68 65 20 69 6e 74 65 72 6e  ** at the intern
8ce0: 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  al representatio
8cf0: 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65 33  n of an [sqlite3
8d00: 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20 6f 6e 6c  _mutex].  It onl
8d10: 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69 74 68 20  y.** deals with 
8d20: 70 6f 69 6e 74 65 72 73 20 74 6f 20 74 68 65 20  pointers to the 
8d30: 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5d 20  [sqlite3_mutex] 
8d40: 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a 20 4d 75  object..**.** Mu
8d50: 74 65 78 65 73 20 61 72 65 20 63 72 65 61 74 65  texes are create
8d60: 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
8d70: 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28 29 5d 2e  _mutex_alloc()].
8d80: 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
8d90: 63 74 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78  ct sqlite3_mutex
8da0: 20 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 3b 0a   sqlite3_mutex;.
8db0: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
8dc0: 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20 4f 62   OS Interface Ob
8dd0: 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e  ject.**.** An in
8de0: 73 74 61 6e 63 65 20 6f 66 20 74 68 65 20 73 71  stance of the sq
8df0: 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a 65 63 74  lite3_vfs object
8e00: 20 64 65 66 69 6e 65 73 20 74 68 65 20 69 6e 74   defines the int
8e10: 65 72 66 61 63 65 20 62 65 74 77 65 65 6e 0a 2a  erface between.*
8e20: 2a 20 74 68 65 20 53 51 4c 69 74 65 20 63 6f 72  * the SQLite cor
8e30: 65 20 61 6e 64 20 74 68 65 20 75 6e 64 65 72 6c  e and the underl
8e40: 79 69 6e 67 20 6f 70 65 72 61 74 69 6e 67 20 73  ying operating s
8e50: 79 73 74 65 6d 2e 20 20 54 68 65 20 22 76 66 73  ystem.  The "vfs
8e60: 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 6d 65  ".** in the name
8e70: 20 6f 66 20 74 68 65 20 6f 62 6a 65 63 74 20 73   of the object s
8e80: 74 61 6e 64 73 20 66 6f 72 20 22 76 69 72 74 75  tands for "virtu
8e90: 61 6c 20 66 69 6c 65 20 73 79 73 74 65 6d 22 2e  al file system".
8ea0: 20 20 53 65 65 0a 2a 2a 20 74 68 65 20 5b 56 46    See.** the [VF
8eb0: 53 20 7c 20 56 46 53 20 64 6f 63 75 6d 65 6e 74  S | VFS document
8ec0: 61 74 69 6f 6e 5d 20 66 6f 72 20 66 75 72 74 68  ation] for furth
8ed0: 65 72 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a  er information..
8ee0: 2a 2a 0a 2a 2a 20 54 68 65 20 76 61 6c 75 65 20  **.** The value 
8ef0: 6f 66 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20  of the iVersion 
8f00: 66 69 65 6c 64 20 69 73 20 69 6e 69 74 69 61 6c  field is initial
8f10: 6c 79 20 31 20 62 75 74 20 6d 61 79 20 62 65 20  ly 1 but may be 
8f20: 6c 61 72 67 65 72 20 69 6e 0a 2a 2a 20 66 75 74  larger in.** fut
8f30: 75 72 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20  ure versions of 
8f40: 53 51 4c 69 74 65 2e 20 20 41 64 64 69 74 69 6f  SQLite.  Additio
8f50: 6e 61 6c 20 66 69 65 6c 64 73 20 6d 61 79 20 62  nal fields may b
8f60: 65 20 61 70 70 65 6e 64 65 64 20 74 6f 20 74 68  e appended to th
8f70: 69 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 77 68 65  is.** object whe
8f80: 6e 20 74 68 65 20 69 56 65 72 73 69 6f 6e 20 76  n the iVersion v
8f90: 61 6c 75 65 20 69 73 20 69 6e 63 72 65 61 73 65  alue is increase
8fa0: 64 2e 20 20 4e 6f 74 65 20 74 68 61 74 20 74 68  d.  Note that th
8fb0: 65 20 73 74 72 75 63 74 75 72 65 0a 2a 2a 20 6f  e structure.** o
8fc0: 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  f the sqlite3_vf
8fd0: 73 20 6f 62 6a 65 63 74 20 63 68 61 6e 67 65 73  s object changes
8fe0: 20 69 6e 20 74 68 65 20 74 72 61 6e 73 61 63 74   in the transact
8ff0: 69 6f 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20 53  ion between.** S
9000: 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 33 2e  QLite version 3.
9010: 35 2e 39 20 61 6e 64 20 33 2e 36 2e 30 20 61 6e  5.9 and 3.6.0 an
9020: 64 20 79 65 74 20 74 68 65 20 69 56 65 72 73 69  d yet the iVersi
9030: 6f 6e 20 66 69 65 6c 64 20 77 61 73 20 6e 6f 74  on field was not
9040: 0a 2a 2a 20 6d 6f 64 69 66 69 65 64 2e 0a 2a 2a  .** modified..**
9050: 0a 2a 2a 20 54 68 65 20 73 7a 4f 73 46 69 6c 65  .** The szOsFile
9060: 20 66 69 65 6c 64 20 69 73 20 74 68 65 20 73 69   field is the si
9070: 7a 65 20 6f 66 20 74 68 65 20 73 75 62 63 6c 61  ze of the subcla
9080: 73 73 65 64 20 5b 73 71 6c 69 74 65 33 5f 66 69  ssed [sqlite3_fi
9090: 6c 65 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  le].** structure
90a0: 20 75 73 65 64 20 62 79 20 74 68 69 73 20 56 46   used by this VF
90b0: 53 2e 20 20 6d 78 50 61 74 68 6e 61 6d 65 20 69  S.  mxPathname i
90c0: 73 20 74 68 65 20 6d 61 78 69 6d 75 6d 20 6c 65  s the maximum le
90d0: 6e 67 74 68 20 6f 66 0a 2a 2a 20 61 20 70 61 74  ngth of.** a pat
90e0: 68 6e 61 6d 65 20 69 6e 20 74 68 69 73 20 56 46  hname in this VF
90f0: 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67 69 73 74 65  S..**.** Registe
9100: 72 65 64 20 73 71 6c 69 74 65 33 5f 76 66 73 20  red sqlite3_vfs 
9110: 6f 62 6a 65 63 74 73 20 61 72 65 20 6b 65 70 74  objects are kept
9120: 20 6f 6e 20 61 20 6c 69 6e 6b 65 64 20 6c 69 73   on a linked lis
9130: 74 20 66 6f 72 6d 65 64 20 62 79 0a 2a 2a 20 74  t formed by.** t
9140: 68 65 20 70 4e 65 78 74 20 70 6f 69 6e 74 65 72  he pNext pointer
9150: 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  .  The [sqlite3_
9160: 76 66 73 5f 72 65 67 69 73 74 65 72 28 29 5d 0a  vfs_register()].
9170: 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  ** and [sqlite3_
9180: 76 66 73 5f 75 6e 72 65 67 69 73 74 65 72 28 29  vfs_unregister()
9190: 5d 20 69 6e 74 65 72 66 61 63 65 73 20 6d 61 6e  ] interfaces man
91a0: 61 67 65 20 74 68 69 73 20 6c 69 73 74 0a 2a 2a  age this list.**
91b0: 20 69 6e 20 61 20 74 68 72 65 61 64 2d 73 61 66   in a thread-saf
91c0: 65 20 77 61 79 2e 20 20 54 68 65 20 5b 73 71 6c  e way.  The [sql
91d0: 69 74 65 33 5f 76 66 73 5f 66 69 6e 64 28 29 5d  ite3_vfs_find()]
91e0: 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 73 65   interface.** se
91f0: 61 72 63 68 65 73 20 74 68 65 20 6c 69 73 74 2e  arches the list.
9200: 20 20 4e 65 69 74 68 65 72 20 74 68 65 20 61 70    Neither the ap
9210: 70 6c 69 63 61 74 69 6f 6e 20 63 6f 64 65 20 6e  plication code n
9220: 6f 72 20 74 68 65 20 56 46 53 0a 2a 2a 20 69 6d  or the VFS.** im
9230: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 73 68 6f  plementation sho
9240: 75 6c 64 20 75 73 65 20 74 68 65 20 70 4e 65 78  uld use the pNex
9250: 74 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  t pointer..**.**
9260: 20 54 68 65 20 70 4e 65 78 74 20 66 69 65 6c 64   The pNext field
9270: 20 69 73 20 74 68 65 20 6f 6e 6c 79 20 66 69 65   is the only fie
9280: 6c 64 20 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ld in the sqlite
9290: 33 5f 76 66 73 0a 2a 2a 20 73 74 72 75 63 74 75  3_vfs.** structu
92a0: 72 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 77  re that SQLite w
92b0: 69 6c 6c 20 65 76 65 72 20 6d 6f 64 69 66 79 2e  ill ever modify.
92c0: 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 20 6f 6e    SQLite will on
92d0: 6c 79 20 61 63 63 65 73 73 0a 2a 2a 20 6f 72 20  ly access.** or 
92e0: 6d 6f 64 69 66 79 20 74 68 69 73 20 66 69 65 6c  modify this fiel
92f0: 64 20 77 68 69 6c 65 20 68 6f 6c 64 69 6e 67 20  d while holding 
9300: 61 20 70 61 72 74 69 63 75 6c 61 72 20 73 74 61  a particular sta
9310: 74 69 63 20 6d 75 74 65 78 2e 0a 2a 2a 20 54 68  tic mutex..** Th
9320: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
9330: 6f 75 6c 64 20 6e 65 76 65 72 20 6d 6f 64 69 66  ould never modif
9340: 79 20 61 6e 79 74 68 69 6e 67 20 77 69 74 68 69  y anything withi
9350: 6e 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 66  n the sqlite3_vf
9360: 73 0a 2a 2a 20 6f 62 6a 65 63 74 20 6f 6e 63 65  s.** object once
9370: 20 74 68 65 20 6f 62 6a 65 63 74 20 68 61 73 20   the object has 
9380: 62 65 65 6e 20 72 65 67 69 73 74 65 72 65 64 2e  been registered.
9390: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 4e 61 6d 65  .**.** The zName
93a0: 20 66 69 65 6c 64 20 68 6f 6c 64 73 20 74 68 65   field holds the
93b0: 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 56 46 53   name of the VFS
93c0: 20 6d 6f 64 75 6c 65 2e 20 20 54 68 65 20 6e 61   module.  The na
93d0: 6d 65 20 6d 75 73 74 0a 2a 2a 20 62 65 20 75 6e  me must.** be un
93e0: 69 71 75 65 20 61 63 72 6f 73 73 20 61 6c 6c 20  ique across all 
93f0: 56 46 53 20 6d 6f 64 75 6c 65 73 2e 0a 2a 2a 0a  VFS modules..**.
9400: 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76 66 73  ** [[sqlite3_vfs
9410: 2e 78 4f 70 65 6e 5d 5d 0a 2a 2a 20 5e 53 51 4c  .xOpen]].** ^SQL
9420: 69 74 65 20 67 75 61 72 61 6e 74 65 65 73 20 74  ite guarantees t
9430: 68 61 74 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d  hat the zFilenam
9440: 65 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 78  e parameter to x
9450: 4f 70 65 6e 0a 2a 2a 20 69 73 20 65 69 74 68 65  Open.** is eithe
9460: 72 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  r a NULL pointer
9470: 20 6f 72 20 73 74 72 69 6e 67 20 6f 62 74 61 69   or string obtai
9480: 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 78 46 75 6c  ned.** from xFul
9490: 6c 50 61 74 68 6e 61 6d 65 28 29 20 77 69 74 68  lPathname() with
94a0: 20 61 6e 20 6f 70 74 69 6f 6e 61 6c 20 73 75 66   an optional suf
94b0: 66 69 78 20 61 64 64 65 64 2e 0a 2a 2a 20 5e 49  fix added..** ^I
94c0: 66 20 61 20 73 75 66 66 69 78 20 69 73 20 61 64  f a suffix is ad
94d0: 64 65 64 20 74 6f 20 74 68 65 20 7a 46 69 6c 65  ded to the zFile
94e0: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 2c 20  name parameter, 
94f0: 69 74 20 77 69 6c 6c 0a 2a 2a 20 63 6f 6e 73 69  it will.** consi
9500: 73 74 20 6f 66 20 61 20 73 69 6e 67 6c 65 20 22  st of a single "
9510: 2d 22 20 63 68 61 72 61 63 74 65 72 20 66 6f 6c  -" character fol
9520: 6c 6f 77 65 64 20 62 79 20 6e 6f 20 6d 6f 72 65  lowed by no more
9530: 20 74 68 61 6e 0a 2a 2a 20 31 30 20 61 6c 70 68   than.** 10 alph
9540: 61 6e 75 6d 65 72 69 63 20 61 6e 64 2f 6f 72 20  anumeric and/or 
9550: 22 2d 22 20 63 68 61 72 61 63 74 65 72 73 2e 0a  "-" characters..
9560: 2a 2a 20 5e 53 51 4c 69 74 65 20 66 75 72 74 68  ** ^SQLite furth
9570: 65 72 20 67 75 61 72 61 6e 74 65 65 73 20 74 68  er guarantees th
9580: 61 74 0a 2a 2a 20 74 68 65 20 73 74 72 69 6e 67  at.** the string
9590: 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20 61   will be valid a
95a0: 6e 64 20 75 6e 63 68 61 6e 67 65 64 20 75 6e 74  nd unchanged unt
95b0: 69 6c 20 78 43 6c 6f 73 65 28 29 20 69 73 0a 2a  il xClose() is.*
95c0: 2a 20 63 61 6c 6c 65 64 2e 20 42 65 63 61 75 73  * called. Becaus
95d0: 65 20 6f 66 20 74 68 65 20 70 72 65 76 69 6f 75  e of the previou
95e0: 73 20 73 65 6e 74 65 6e 63 65 2c 0a 2a 2a 20 74  s sentence,.** t
95f0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65  he [sqlite3_file
9600: 5d 20 63 61 6e 20 73 61 66 65 6c 79 20 73 74 6f  ] can safely sto
9610: 72 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  re a pointer to 
9620: 74 68 65 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 20  the.** filename 
9630: 69 66 20 69 74 20 6e 65 65 64 73 20 74 6f 20 72  if it needs to r
9640: 65 6d 65 6d 62 65 72 20 74 68 65 20 66 69 6c 65  emember the file
9650: 6e 61 6d 65 20 66 6f 72 20 73 6f 6d 65 20 72 65  name for some re
9660: 61 73 6f 6e 2e 0a 2a 2a 20 49 66 20 74 68 65 20  ason..** If the 
9670: 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d 65  zFilename parame
9680: 74 65 72 20 74 6f 20 78 4f 70 65 6e 20 69 73 20  ter to xOpen is 
9690: 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 74  a NULL pointer t
96a0: 68 65 6e 20 78 4f 70 65 6e 0a 2a 2a 20 6d 75 73  hen xOpen.** mus
96b0: 74 20 69 6e 76 65 6e 74 20 69 74 73 20 6f 77 6e  t invent its own
96c0: 20 74 65 6d 70 6f 72 61 72 79 20 6e 61 6d 65 20   temporary name 
96d0: 66 6f 72 20 74 68 65 20 66 69 6c 65 2e 20 20 5e  for the file.  ^
96e0: 57 68 65 6e 65 76 65 72 20 74 68 65 20 0a 2a 2a  Whenever the .**
96f0: 20 78 46 69 6c 65 6e 61 6d 65 20 70 61 72 61 6d   xFilename param
9700: 65 74 65 72 20 69 73 20 4e 55 4c 4c 20 69 74 20  eter is NULL it 
9710: 77 69 6c 6c 20 61 6c 73 6f 20 62 65 20 74 68 65  will also be the
9720: 20 63 61 73 65 20 74 68 61 74 20 74 68 65 0a 2a   case that the.*
9730: 2a 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65  * flags paramete
9740: 72 20 77 69 6c 6c 20 69 6e 63 6c 75 64 65 20 5b  r will include [
9750: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
9760: 54 45 4f 4e 43 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a  TEONCLOSE]..**.*
9770: 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72 67 75  * The flags argu
9780: 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 28 29 20  ment to xOpen() 
9790: 69 6e 63 6c 75 64 65 73 20 61 6c 6c 20 62 69 74  includes all bit
97a0: 73 20 73 65 74 20 69 6e 0a 2a 2a 20 74 68 65 20  s set in.** the 
97b0: 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20 74  flags argument t
97c0: 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  o [sqlite3_open_
97d0: 76 32 28 29 5d 2e 20 20 4f 72 20 69 66 20 5b 73  v2()].  Or if [s
97e0: 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a  qlite3_open()].*
97f0: 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
9800: 65 6e 31 36 28 29 5d 20 69 73 20 75 73 65 64 2c  en16()] is used,
9810: 20 74 68 65 6e 20 66 6c 61 67 73 20 69 6e 63 6c   then flags incl
9820: 75 64 65 73 20 61 74 20 6c 65 61 73 74 0a 2a 2a  udes at least.**
9830: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45   [SQLITE_OPEN_RE
9840: 41 44 57 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49  ADWRITE] | [SQLI
9850: 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d 2e  TE_OPEN_CREATE].
9860: 20 0a 2a 2a 20 49 66 20 78 4f 70 65 6e 28 29 20   .** If xOpen() 
9870: 6f 70 65 6e 73 20 61 20 66 69 6c 65 20 72 65 61  opens a file rea
9880: 64 2d 6f 6e 6c 79 20 74 68 65 6e 20 69 74 20 73  d-only then it s
9890: 65 74 73 20 2a 70 4f 75 74 46 6c 61 67 73 20 74  ets *pOutFlags t
98a0: 6f 0a 2a 2a 20 69 6e 63 6c 75 64 65 20 5b 53 51  o.** include [SQ
98b0: 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
98c0: 4c 59 5d 2e 20 20 4f 74 68 65 72 20 62 69 74 73  LY].  Other bits
98d0: 20 69 6e 20 2a 70 4f 75 74 46 6c 61 67 73 20 6d   in *pOutFlags m
98e0: 61 79 20 62 65 20 73 65 74 2e 0a 2a 2a 0a 2a 2a  ay be set..**.**
98f0: 20 5e 28 53 51 4c 69 74 65 20 77 69 6c 6c 20 61   ^(SQLite will a
9900: 6c 73 6f 20 61 64 64 20 6f 6e 65 20 6f 66 20 74  lso add one of t
9910: 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61  he following fla
9920: 67 73 20 74 6f 20 74 68 65 20 78 4f 70 65 6e 28  gs to the xOpen(
9930: 29 0a 2a 2a 20 63 61 6c 6c 2c 20 64 65 70 65 6e  ).** call, depen
9940: 64 69 6e 67 20 6f 6e 20 74 68 65 20 6f 62 6a 65  ding on the obje
9950: 63 74 20 62 65 69 6e 67 20 6f 70 65 6e 65 64 3a  ct being opened:
9960: 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c  .**.** <ul>.** <
9970: 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45  li>  [SQLITE_OPE
9980: 4e 5f 4d 41 49 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c  N_MAIN_DB].** <l
9990: 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  i>  [SQLITE_OPEN
99a0: 5f 4d 41 49 4e 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a  _MAIN_JOURNAL].*
99b0: 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f  * <li>  [SQLITE_
99c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 5d 0a 2a 2a  OPEN_TEMP_DB].**
99d0: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
99e0: 50 45 4e 5f 54 45 4d 50 5f 4a 4f 55 52 4e 41 4c  PEN_TEMP_JOURNAL
99f0: 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49  ].** <li>  [SQLI
9a00: 54 45 5f 4f 50 45 4e 5f 54 52 41 4e 53 49 45 4e  TE_OPEN_TRANSIEN
9a10: 54 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  T_DB].** <li>  [
9a20: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53 55 42 4a  SQLITE_OPEN_SUBJ
9a30: 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20  OURNAL].** <li> 
9a40: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41   [SQLITE_OPEN_MA
9a50: 53 54 45 52 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a  STER_JOURNAL].**
9a60: 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f   <li>  [SQLITE_O
9a70: 50 45 4e 5f 57 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c  PEN_WAL].** </ul
9a80: 3e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 66 69  >)^.**.** The fi
9a90: 6c 65 20 49 2f 4f 20 69 6d 70 6c 65 6d 65 6e 74  le I/O implement
9aa0: 61 74 69 6f 6e 20 63 61 6e 20 75 73 65 20 74 68  ation can use th
9ab0: 65 20 6f 62 6a 65 63 74 20 74 79 70 65 20 66 6c  e object type fl
9ac0: 61 67 73 20 74 6f 0a 2a 2a 20 63 68 61 6e 67 65  ags to.** change
9ad0: 20 74 68 65 20 77 61 79 20 69 74 20 64 65 61 6c   the way it deal
9ae0: 73 20 77 69 74 68 20 66 69 6c 65 73 2e 20 20 46  s with files.  F
9af0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61  or example, an a
9b00: 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20 74 68  pplication.** th
9b10: 61 74 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65  at does not care
9b20: 20 61 62 6f 75 74 20 63 72 61 73 68 20 72 65 63   about crash rec
9b30: 6f 76 65 72 79 20 6f 72 20 72 6f 6c 6c 62 61 63  overy or rollbac
9b40: 6b 20 6d 69 67 68 74 20 6d 61 6b 65 0a 2a 2a 20  k might make.** 
9b50: 74 68 65 20 6f 70 65 6e 20 6f 66 20 61 20 6a 6f  the open of a jo
9b60: 75 72 6e 61 6c 20 66 69 6c 65 20 61 20 6e 6f 2d  urnal file a no-
9b70: 6f 70 2e 20 20 57 72 69 74 65 73 20 74 6f 20 74  op.  Writes to t
9b80: 68 69 73 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c  his journal woul
9b90: 64 0a 2a 2a 20 61 6c 73 6f 20 62 65 20 6e 6f 2d  d.** also be no-
9ba0: 6f 70 73 2c 20 61 6e 64 20 61 6e 79 20 61 74 74  ops, and any att
9bb0: 65 6d 70 74 20 74 6f 20 72 65 61 64 20 74 68 65  empt to read the
9bc0: 20 6a 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 20 72   journal would r
9bd0: 65 74 75 72 6e 0a 2a 2a 20 53 51 4c 49 54 45 5f  eturn.** SQLITE_
9be0: 49 4f 45 52 52 2e 20 20 4f 72 20 74 68 65 20 69  IOERR.  Or the i
9bf0: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 69  mplementation mi
9c00: 67 68 74 20 72 65 63 6f 67 6e 69 7a 65 20 74 68  ght recognize th
9c10: 61 74 20 61 20 64 61 74 61 62 61 73 65 0a 2a 2a  at a database.**
9c20: 20 66 69 6c 65 20 77 69 6c 6c 20 62 65 20 64 6f   file will be do
9c30: 69 6e 67 20 70 61 67 65 2d 61 6c 69 67 6e 65 64  ing page-aligned
9c40: 20 73 65 63 74 6f 72 20 72 65 61 64 73 20 61 6e   sector reads an
9c50: 64 20 77 72 69 74 65 73 20 69 6e 20 61 20 72 61  d writes in a ra
9c60: 6e 64 6f 6d 0a 2a 2a 20 6f 72 64 65 72 20 61 6e  ndom.** order an
9c70: 64 20 73 65 74 20 75 70 20 69 74 73 20 49 2f 4f  d set up its I/O
9c80: 20 73 75 62 73 79 73 74 65 6d 20 61 63 63 6f 72   subsystem accor
9c90: 64 69 6e 67 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 51  dingly..**.** SQ
9ca0: 4c 69 74 65 20 6d 69 67 68 74 20 61 6c 73 6f 20  Lite might also 
9cb0: 61 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66  add one of the f
9cc0: 6f 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74  ollowing flags t
9cd0: 6f 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74 68  o the xOpen meth
9ce0: 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  od:.**.** <ul>.*
9cf0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f  * <li> [SQLITE_O
9d00: 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53  PEN_DELETEONCLOS
9d10: 45 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49  E].** <li> [SQLI
9d20: 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56  TE_OPEN_EXCLUSIV
9d30: 45 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a  E].** </ul>.**.*
9d40: 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50  * The [SQLITE_OP
9d50: 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45  EN_DELETEONCLOSE
9d60: 5d 20 66 6c 61 67 20 6d 65 61 6e 73 20 74 68 65  ] flag means the
9d70: 20 66 69 6c 65 20 73 68 6f 75 6c 64 20 62 65 0a   file should be.
9d80: 2a 2a 20 64 65 6c 65 74 65 64 20 77 68 65 6e 20  ** deleted when 
9d90: 69 74 20 69 73 20 63 6c 6f 73 65 64 2e 20 20 5e  it is closed.  ^
9da0: 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  The [SQLITE_OPEN
9db0: 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a  _DELETEONCLOSE].
9dc0: 2a 2a 20 77 69 6c 6c 20 62 65 20 73 65 74 20 66  ** will be set f
9dd0: 6f 72 20 54 45 4d 50 20 64 61 74 61 62 61 73 65  or TEMP database
9de0: 73 20 61 6e 64 20 74 68 65 69 72 20 6a 6f 75 72  s and their jour
9df0: 6e 61 6c 73 2c 20 74 72 61 6e 73 69 65 6e 74 0a  nals, transient.
9e00: 2a 2a 20 64 61 74 61 62 61 73 65 73 2c 20 61 6e  ** databases, an
9e10: 64 20 73 75 62 6a 6f 75 72 6e 61 6c 73 2e 0a 2a  d subjournals..*
9e20: 2a 0a 2a 2a 20 5e 54 68 65 20 5b 53 51 4c 49 54  *.** ^The [SQLIT
9e30: 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45  E_OPEN_EXCLUSIVE
9e40: 5d 20 66 6c 61 67 20 69 73 20 61 6c 77 61 79 73  ] flag is always
9e50: 20 75 73 65 64 20 69 6e 20 63 6f 6e 6a 75 6e 63   used in conjunc
9e60: 74 69 6f 6e 0a 2a 2a 20 77 69 74 68 20 74 68 65  tion.** with the
9e70: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52   [SQLITE_OPEN_CR
9e80: 45 41 54 45 5d 20 66 6c 61 67 2c 20 77 68 69 63  EATE] flag, whic
9e90: 68 20 61 72 65 20 62 6f 74 68 20 64 69 72 65 63  h are both direc
9ea0: 74 6c 79 0a 2a 2a 20 61 6e 61 6c 6f 67 6f 75 73  tly.** analogous
9eb0: 20 74 6f 20 74 68 65 20 4f 5f 45 58 43 4c 20 61   to the O_EXCL a
9ec0: 6e 64 20 4f 5f 43 52 45 41 54 20 66 6c 61 67 73  nd O_CREAT flags
9ed0: 20 6f 66 20 74 68 65 20 50 4f 53 49 58 20 6f 70   of the POSIX op
9ee0: 65 6e 28 29 0a 2a 2a 20 41 50 49 2e 20 20 54 68  en().** API.  Th
9ef0: 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 45 58  e SQLITE_OPEN_EX
9f00: 43 4c 55 53 49 56 45 20 66 6c 61 67 2c 20 77 68  CLUSIVE flag, wh
9f10: 65 6e 20 70 61 69 72 65 64 20 77 69 74 68 20 74  en paired with t
9f20: 68 65 20 0a 2a 2a 20 53 51 4c 49 54 45 5f 4f 50  he .** SQLITE_OP
9f30: 45 4e 5f 43 52 45 41 54 45 2c 20 69 73 20 75 73  EN_CREATE, is us
9f40: 65 64 20 74 6f 20 69 6e 64 69 63 61 74 65 20 74  ed to indicate t
9f50: 68 61 74 20 66 69 6c 65 20 73 68 6f 75 6c 64 20  hat file should 
9f60: 61 6c 77 61 79 73 0a 2a 2a 20 62 65 20 63 72 65  always.** be cre
9f70: 61 74 65 64 2c 20 61 6e 64 20 74 68 61 74 20 69  ated, and that i
9f80: 74 20 69 73 20 61 6e 20 65 72 72 6f 72 20 69 66  t is an error if
9f90: 20 69 74 20 61 6c 72 65 61 64 79 20 65 78 69 73   it already exis
9fa0: 74 73 2e 0a 2a 2a 20 49 74 20 69 73 20 3c 69 3e  ts..** It is <i>
9fb0: 6e 6f 74 3c 2f 69 3e 20 75 73 65 64 20 74 6f 20  not</i> used to 
9fc0: 69 6e 64 69 63 61 74 65 20 74 68 65 20 66 69 6c  indicate the fil
9fd0: 65 20 73 68 6f 75 6c 64 20 62 65 20 6f 70 65 6e  e should be open
9fe0: 65 64 20 0a 2a 2a 20 66 6f 72 20 65 78 63 6c 75  ed .** for exclu
9ff0: 73 69 76 65 20 61 63 63 65 73 73 2e 0a 2a 2a 0a  sive access..**.
a000: 2a 2a 20 5e 41 74 20 6c 65 61 73 74 20 73 7a 4f  ** ^At least szO
a010: 73 46 69 6c 65 20 62 79 74 65 73 20 6f 66 20 6d  sFile bytes of m
a020: 65 6d 6f 72 79 20 61 72 65 20 61 6c 6c 6f 63 61  emory are alloca
a030: 74 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a  ted by SQLite.**
a040: 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 20 5b 73   to hold the  [s
a050: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 73 74 72  qlite3_file] str
a060: 75 63 74 75 72 65 20 70 61 73 73 65 64 20 61 73  ucture passed as
a070: 20 74 68 65 20 74 68 69 72 64 0a 2a 2a 20 61 72   the third.** ar
a080: 67 75 6d 65 6e 74 20 74 6f 20 78 4f 70 65 6e 2e  gument to xOpen.
a090: 20 20 54 68 65 20 78 4f 70 65 6e 20 6d 65 74 68    The xOpen meth
a0a0: 6f 64 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65  od does not have
a0b0: 20 74 6f 0a 2a 2a 20 61 6c 6c 6f 63 61 74 65 20   to.** allocate 
a0c0: 74 68 65 20 73 74 72 75 63 74 75 72 65 3b 20 69  the structure; i
a0d0: 74 20 73 68 6f 75 6c 64 20 6a 75 73 74 20 66 69  t should just fi
a0e0: 6c 6c 20 69 74 20 69 6e 2e 20 20 4e 6f 74 65 20  ll it in.  Note 
a0f0: 74 68 61 74 0a 2a 2a 20 74 68 65 20 78 4f 70 65  that.** the xOpe
a100: 6e 20 6d 65 74 68 6f 64 20 6d 75 73 74 20 73 65  n method must se
a110: 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66 69  t the sqlite3_fi
a120: 6c 65 2e 70 4d 65 74 68 6f 64 73 20 74 6f 20 65  le.pMethods to e
a130: 69 74 68 65 72 0a 2a 2a 20 61 20 76 61 6c 69 64  ither.** a valid
a140: 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74   [sqlite3_io_met
a150: 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 6f 72 20  hods] object or 
a160: 74 6f 20 4e 55 4c 4c 2e 20 20 78 4f 70 65 6e 20  to NULL.  xOpen 
a170: 6d 75 73 74 20 64 6f 0a 2a 2a 20 74 68 69 73 20  must do.** this 
a180: 65 76 65 6e 20 69 66 20 74 68 65 20 6f 70 65 6e  even if the open
a190: 20 66 61 69 6c 73 2e 20 20 53 51 4c 69 74 65 20   fails.  SQLite 
a1a0: 65 78 70 65 63 74 73 20 74 68 61 74 20 74 68 65  expects that the
a1b0: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
a1c0: 65 74 68 6f 64 73 0a 2a 2a 20 65 6c 65 6d 65 6e  ethods.** elemen
a1d0: 74 20 77 69 6c 6c 20 62 65 20 76 61 6c 69 64 20  t will be valid 
a1e0: 61 66 74 65 72 20 78 4f 70 65 6e 20 72 65 74 75  after xOpen retu
a1f0: 72 6e 73 20 72 65 67 61 72 64 6c 65 73 73 20 6f  rns regardless o
a200: 66 20 74 68 65 20 73 75 63 63 65 73 73 0a 2a 2a  f the success.**
a210: 20 6f 72 20 66 61 69 6c 75 72 65 20 6f 66 20 74   or failure of t
a220: 68 65 20 78 4f 70 65 6e 20 63 61 6c 6c 2e 0a 2a  he xOpen call..*
a230: 2a 0a 2a 2a 20 5b 5b 73 71 6c 69 74 65 33 5f 76  *.** [[sqlite3_v
a240: 66 73 2e 78 41 63 63 65 73 73 5d 5d 0a 2a 2a 20  fs.xAccess]].** 
a250: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
a260: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
a270: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
a280: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
a290: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
a2a0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
a2b0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
a2c0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
a2d0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
a2e0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
a2f0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
a300: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
a310: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
a320: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
a330: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
a340: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
a350: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
a360: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
a370: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
a380: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
a390: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
a3a0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
a3b0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
a3c0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
a3d0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
a3e0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
a3f0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
a400: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
a410: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
a420: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
a430: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
a440: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
a450: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
a460: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
a470: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
a480: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
a490: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
a4a0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
a4b0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
a4c0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
a4d0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
a4e0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
a4f0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
a500: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
a510: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
a520: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
a530: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
a540: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
a550: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
a560: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
a570: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
a580: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
a590: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
a5a0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
a5b0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
a5c0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
a5d0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
a5e0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
a5f0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
a600: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
a610: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
a620: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
a630: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
a640: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
a650: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
a660: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
a670: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
a680: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
a690: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
a6a0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
a6b0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
a6c0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
a6d0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
a6e0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
a6f0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
a700: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
a710: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
a720: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
a730: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
a740: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
a750: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
a760: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
a770: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
a780: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
a790: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
a7a0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
a7b0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
a7c0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
a7d0: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38  r multipled by 8
a7e0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
a7f0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
a800: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
a810: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
a820: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
a830: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
a840: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
a850: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
a860: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
a870: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
a880: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
a890: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
a8a0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
a8b0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
a8c0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
a8d0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
a8e0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
a8f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
a900: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
a910: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
a920: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
a930: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
a940: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
a950: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
a960: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
a970: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
a980: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
a990: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
a9a0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
a9b0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
a9c0: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
a9d0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
a9e0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
a9f0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
aa00: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
aa10: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
aa20: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
aa30: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
aa40: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
aa50: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
aa60: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
aa70: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
aa80: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
aa90: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
aaa0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
aab0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
aac0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
aad0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
aae0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
aaf0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
ab00: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
ab10: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
ab20: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
ab30: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
ab40: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
ab50: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
ab60: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
ab70: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
ab80: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
ab90: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
aba0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
abb0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
abc0: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
abd0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
abe0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
abf0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
ac00: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
ac10: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
ac20: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
ac30: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
ac40: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
ac50: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
ac60: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
ac70: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
ac80: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
ac90: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
aca0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
acb0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
acc0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
acd0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
ace0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
acf0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
ad00: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
ad10: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
ad20: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
ad30: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
ad40: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
ad50: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
ad60: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
ad70: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
ad80: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
ad90: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
ada0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
adb0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
adc0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
add0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
ade0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
adf0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
ae00: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
ae10: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
ae20: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
ae30: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
ae40: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
ae50: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
ae60: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
ae70: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
ae80: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
ae90: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
aea0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
aeb0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
aec0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
aed0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
aee0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
aef0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
af00: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
af10: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
af20: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
af30: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
af40: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
af50: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
af60: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
af70: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
af80: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
af90: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
afa0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
afb0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
afc0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
afd0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
afe0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
aff0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
b000: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
b010: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
b020: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
b030: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
b040: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
b050: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
b060: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
b070: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
b080: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
b090: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
b0a0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
b0b0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
b0c0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
b0d0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
b0e0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
b0f0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
b100: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
b110: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
b120: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
b130: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
b140: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
b150: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
b160: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
b170: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
b180: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
b190: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
b1a0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
b1b0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
b1c0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
b1d0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
b1e0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
b1f0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
b200: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
b210: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
b220: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
b230: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
b240: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
b250: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
b260: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
b270: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
b280: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
b290: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
b2a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
b2b0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
b2c0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
b2d0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
b2e0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
b2f0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
b300: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
b310: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
b320: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
b330: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
b340: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
b350: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
b360: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
b370: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
b380: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
b390: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
b3a0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
b3b0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
b3c0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
b3d0: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
b3e0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
b3f0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
b400: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
b410: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
b420: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
b430: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
b440: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
b450: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
b460: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
b470: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
b480: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
b490: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
b4a0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
b4b0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
b4c0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
b4d0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
b4e0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
b4f0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
b500: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
b510: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
b520: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
b530: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
b540: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
b550: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
b560: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
b570: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
b580: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
b590: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
b5a0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
b5b0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
b5c0: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
b5d0: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
b5e0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
b5f0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
b600: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
b610: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
b620: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
b630: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
b640: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
b650: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
b660: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
b670: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
b680: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
b690: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
b6a0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
b6b0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
b6c0: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
b6d0: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
b6e0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
b6f0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
b700: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
b710: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
b720: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
b730: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
b740: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
b750: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
b760: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
b770: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
b780: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
b790: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
b7a0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
b7b0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
b7c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b7d0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
b7e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b7f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
b800: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
b810: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
b820: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
b830: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b840: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
b850: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
b860: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b870: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
b880: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
b890: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
b8a0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
b8b0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
b8c0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
b8d0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
b8e0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
b8f0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
b900: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b910: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
b920: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
b930: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
b940: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
b950: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
b960: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
b970: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
b980: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
b990: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
b9a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b9b0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
b9c0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b9d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b9e0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
b9f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
ba00: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
ba10: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
ba20: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
ba30: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
ba40: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
ba50: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
ba60: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
ba70: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
ba80: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
ba90: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
baa0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
bab0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
bac0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
bad0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
bae0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
baf0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
bb00: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
bb10: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
bb20: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
bb30: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
bb40: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
bb50: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
bb60: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
bb70: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
bb80: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
bb90: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
bba0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
bbb0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
bbc0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
bbd0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
bbe0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
bbf0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
bc00: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
bc10: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
bc20: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
bc30: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
bc40: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
bc50: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
bc60: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
bc70: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
bc80: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
bc90: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
bca0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
bcb0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
bcc0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
bcd0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
bce0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
bcf0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
bd00: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
bd10: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
bd20: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
bd30: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
bd40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bd50: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
bd60: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
bd70: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
bd80: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
bd90: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
bda0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
bdb0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
bdc0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
bdd0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
bde0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
bdf0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
be00: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
be10: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
be20: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
be30: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
be40: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
be50: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
be60: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
be70: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
be80: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
be90: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
bea0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
beb0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
bec0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
bed0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
bee0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
bef0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
bf00: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
bf10: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
bf20: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
bf30: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
bf40: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
bf50: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
bf60: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
bf70: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
bf80: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
bf90: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
bfa0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
bfb0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
bfc0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
bfd0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
bfe0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
bff0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
c000: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
c010: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
c020: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
c030: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
c040: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c050: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
c060: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
c070: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
c080: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
c090: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
c0a0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
c0b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
c0c0: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
c0d0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
c0e0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c0f0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
c100: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
c110: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
c120: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
c130: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
c140: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
c150: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
c160: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c170: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
c180: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
c190: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
c1a0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
c1b0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
c1c0: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
c1d0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
c1e0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
c1f0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
c200: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
c210: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
c220: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
c230: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
c240: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
c250: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
c260: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
c270: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
c280: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
c290: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
c2a0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
c2b0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
c2c0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
c2d0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
c2e0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
c2f0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
c300: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
c310: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
c320: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
c330: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
c340: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
c350: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
c360: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
c370: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
c380: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
c390: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
c3a0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
c3b0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
c3c0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
c3d0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
c3e0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
c3f0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
c400: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
c410: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
c420: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
c430: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
c440: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c450: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
c460: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
c470: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
c480: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
c490: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
c4a0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
c4b0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
c4c0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
c4d0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
c4e0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
c4f0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
c500: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
c510: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
c520: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
c530: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
c540: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
c550: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
c560: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
c570: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
c580: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
c590: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
c5a0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
c5b0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
c5c0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
c5d0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
c5e0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
c5f0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
c600: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
c610: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
c620: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
c630: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
c640: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
c650: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
c660: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
c670: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
c680: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
c690: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
c6a0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c6b0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
c6c0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
c6d0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
c6e0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
c6f0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
c700: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c710: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
c720: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
c730: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
c740: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
c750: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
c760: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
c770: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
c780: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
c790: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
c7a0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
c7b0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
c7c0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
c7d0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
c7e0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
c7f0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
c800: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
c810: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
c820: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
c830: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
c840: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
c850: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
c860: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
c870: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
c880: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
c890: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
c8a0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
c8b0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
c8c0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
c8d0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
c8e0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
c8f0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
c900: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
c910: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
c920: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
c930: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
c940: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c950: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
c960: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
c970: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
c980: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
c990: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
c9a0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
c9b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
c9c0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
c9d0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
c9e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c9f0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
ca00: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
ca10: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
ca20: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
ca30: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
ca40: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
ca50: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
ca60: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
ca70: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
ca80: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
ca90: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
caa0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
cab0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
cac0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
cad0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
cae0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
caf0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
cb00: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
cb10: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
cb20: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
cb30: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
cb40: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
cb50: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
cb60: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
cb70: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
cb80: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
cb90: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
cba0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
cbb0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
cbc0: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
cbd0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
cbe0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
cbf0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
cc00: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
cc10: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
cc20: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
cc30: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
cc40: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
cc50: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
cc60: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
cc70: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
cc80: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
cc90: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
cca0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
ccb0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
ccc0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
ccd0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
cce0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
ccf0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
cd00: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
cd10: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
cd20: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
cd30: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
cd40: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
cd50: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
cd60: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
cd70: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
cd80: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
cd90: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
cda0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
cdb0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
cdc0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
cdd0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
cde0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
cdf0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
ce00: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
ce10: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
ce20: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
ce30: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
ce40: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
ce50: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
ce60: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
ce70: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
ce80: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
ce90: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
cea0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
ceb0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
cec0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
ced0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
cee0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
cef0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
cf00: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
cf10: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
cf20: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
cf30: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
cf40: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
cf50: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
cf60: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
cf70: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
cf80: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
cf90: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
cfa0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
cfb0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
cfc0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
cfd0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
cfe0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
cff0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
d000: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
d010: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
d020: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
d030: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
d040: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
d050: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
d060: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
d070: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
d080: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
d090: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
d0a0: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
d0b0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
d0c0: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
d0d0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
d0e0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
d0f0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
d100: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
d110: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
d120: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
d130: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
d140: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
d150: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
d160: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
d170: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
d180: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
d190: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
d1a0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
d1b0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
d1c0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 63 6f 6e 66 69  nteger.** [confi
d1d0: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
d1e0: 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 73   that determines
d1f0: 0a 2a 2a 20 77 68 61 74 20 70 72 6f 70 65 72 74  .** what propert
d200: 79 20 6f 66 20 53 51 4c 69 74 65 20 69 73 20 74  y of SQLite is t
d210: 6f 20 62 65 20 63 6f 6e 66 69 67 75 72 65 64 2e  o be configured.
d220: 20 20 53 75 62 73 65 71 75 65 6e 74 20 61 72 67    Subsequent arg
d230: 75 6d 65 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64  uments.** vary d
d240: 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20  epending on the 
d250: 5b 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f  [configuration o
d260: 70 74 69 6f 6e 5d 0a 2a 2a 20 69 6e 20 74 68 65  ption].** in the
d270: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 2e   first argument.
d280: 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20 61 20 63  .**.** ^When a c
d290: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
d2a0: 69 6f 6e 20 69 73 20 73 65 74 2c 20 73 71 6c 69  ion is set, sqli
d2b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 72 65 74  te3_config() ret
d2c0: 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  urns [SQLITE_OK]
d2d0: 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6f 70 74  ..** ^If the opt
d2e0: 69 6f 6e 20 69 73 20 75 6e 6b 6e 6f 77 6e 20 6f  ion is unknown o
d2f0: 72 20 53 51 4c 69 74 65 20 69 73 20 75 6e 61 62  r SQLite is unab
d300: 6c 65 20 74 6f 20 73 65 74 20 74 68 65 20 6f 70  le to set the op
d310: 74 69 6f 6e 0a 2a 2a 20 74 68 65 6e 20 74 68 69  tion.** then thi
d320: 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e  s routine return
d330: 73 20 61 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72  s a non-zero [er
d340: 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2f 0a 69 6e  ror code]..*/.in
d350: 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  t sqlite3_config
d360: 28 69 6e 74 2c 20 2e 2e 2e 29 3b 0a 0a 2f 2a 0a  (int, ...);../*.
d370: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e  ** CAPI3REF: Con
d380: 66 69 67 75 72 65 20 64 61 74 61 62 61 73 65 20  figure database 
d390: 63 6f 6e 6e 65 63 74 69 6f 6e 73 0a 2a 2a 0a 2a  connections.**.*
d3a0: 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 64 62  * The sqlite3_db
d3b0: 5f 63 6f 6e 66 69 67 28 29 20 69 6e 74 65 72 66  _config() interf
d3c0: 61 63 65 20 69 73 20 75 73 65 64 20 74 6f 20 6d  ace is used to m
d3d0: 61 6b 65 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ake configuratio
d3e0: 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20  n.** changes to 
d3f0: 61 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  a [database conn
d400: 65 63 74 69 6f 6e 5d 2e 20 20 54 68 65 20 69 6e  ection].  The in
d410: 74 65 72 66 61 63 65 20 69 73 20 73 69 6d 69 6c  terface is simil
d420: 61 72 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65  ar to.** [sqlite
d430: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 65 78 63 65  3_config()] exce
d440: 70 74 20 74 68 61 74 20 74 68 65 20 63 68 61 6e  pt that the chan
d450: 67 65 73 20 61 70 70 6c 79 20 74 6f 20 61 20 73  ges apply to a s
d460: 69 6e 67 6c 65 0a 2a 2a 20 5b 64 61 74 61 62 61  ingle.** [databa
d470: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 28  se connection] (
d480: 73 70 65 63 69 66 69 65 64 20 69 6e 20 74 68 65  specified in the
d490: 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 29   first argument)
d4a0: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65 63 6f  ..**.** The seco
d4b0: 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73  nd argument to s
d4c0: 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
d4d0: 28 44 2c 56 2c 2e 2e 2e 29 20 20 69 73 20 74 68  (D,V,...)  is th
d4e0: 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 42 43  e.** [SQLITE_DBC
d4f0: 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20  ONFIG_LOOKASIDE 
d500: 7c 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  | configuration 
d510: 76 65 72 62 5d 20 2d 20 61 6e 20 69 6e 74 65 67  verb] - an integ
d520: 65 72 20 63 6f 64 65 20 0a 2a 2a 20 74 68 61 74  er code .** that
d530: 20 69 6e 64 69 63 61 74 65 73 20 77 68 61 74 20   indicates what 
d540: 61 73 70 65 63 74 20 6f 66 20 74 68 65 20 5b 64  aspect of the [d
d550: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
d560: 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 63 6f 6e  on] is being con
d570: 66 69 67 75 72 65 64 2e 0a 2a 2a 20 53 75 62 73  figured..** Subs
d580: 65 71 75 65 6e 74 20 61 72 67 75 6d 65 6e 74 73  equent arguments
d590: 20 76 61 72 79 20 64 65 70 65 6e 64 69 6e 67 20   vary depending 
d5a0: 6f 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  on the configura
d5b0: 74 69 6f 6e 20 76 65 72 62 2e 0a 2a 2a 0a 2a 2a  tion verb..**.**
d5c0: 20 5e 43 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74   ^Calls to sqlit
d5d0: 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 20 72  e3_db_config() r
d5e0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4f 4b 20  eturn SQLITE_OK 
d5f0: 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66 0a 2a  if and only if.*
d600: 2a 20 74 68 65 20 63 61 6c 6c 20 69 73 20 63 6f  * the call is co
d610: 6e 73 69 64 65 72 65 64 20 73 75 63 63 65 73 73  nsidered success
d620: 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ful..*/.int sqli
d630: 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 73 71  te3_db_config(sq
d640: 6c 69 74 65 33 2a 2c 20 69 6e 74 20 6f 70 2c 20  lite3*, int op, 
d650: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
d660: 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c  I3REF: Memory Al
d670: 6c 6f 63 61 74 69 6f 6e 20 52 6f 75 74 69 6e 65  location Routine
d680: 73 0a 2a 2a 0a 2a 2a 20 41 6e 20 69 6e 73 74 61  s.**.** An insta
d690: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
d6a0: 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20 69  ct defines the i
d6b0: 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65 6e  nterface between
d6c0: 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20 6c   SQLite.** and l
d6d0: 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f 72 79 20  ow-level memory 
d6e0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69  allocation routi
d6f0: 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  nes..**.** This 
d700: 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 20 69  object is used i
d710: 6e 20 6f 6e 6c 79 20 6f 6e 65 20 70 6c 61 63 65  n only one place
d720: 20 69 6e 20 74 68 65 20 53 51 4c 69 74 65 20 69   in the SQLite i
d730: 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 41 20 70  nterface..** A p
d740: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
d750: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
d760: 6a 65 63 74 20 69 73 20 74 68 65 20 61 72 67 75  ject is the argu
d770: 6d 65 6e 74 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  ment to.** [sqli
d780: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 68  te3_config()] wh
d790: 65 6e 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  en the configura
d7a0: 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 0a 2a  tion option is.*
d7b0: 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  * [SQLITE_CONFIG
d7c0: 5f 4d 41 4c 4c 4f 43 5d 20 6f 72 20 5b 53 51 4c  _MALLOC] or [SQL
d7d0: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
d7e0: 4c 4c 4f 43 5d 2e 20 20 0a 2a 2a 20 42 79 20 63  LLOC].  .** By c
d7f0: 72 65 61 74 69 6e 67 20 61 6e 20 69 6e 73 74 61  reating an insta
d800: 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62 6a 65  nce of this obje
d810: 63 74 0a 2a 2a 20 61 6e 64 20 70 61 73 73 69 6e  ct.** and passin
d820: 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65 33  g it to [sqlite3
d830: 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
d840: 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 29  _CONFIG_MALLOC])
d850: 0a 2a 2a 20 64 75 72 69 6e 67 20 63 6f 6e 66 69  .** during confi
d860: 67 75 72 61 74 69 6f 6e 2c 20 61 6e 20 61 70 70  guration, an app
d870: 6c 69 63 61 74 69 6f 6e 20 63 61 6e 20 73 70 65  lication can spe
d880: 63 69 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74  cify an alternat
d890: 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c  ive.** memory al
d8a0: 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74  location subsyst
d8b0: 65 6d 20 66 6f 72 20 53 51 4c 69 74 65 20 74 6f  em for SQLite to
d8c0: 20 75 73 65 20 66 6f 72 20 61 6c 6c 20 6f 66 20   use for all of 
d8d0: 69 74 73 0a 2a 2a 20 64 79 6e 61 6d 69 63 20 6d  its.** dynamic m
d8e0: 65 6d 6f 72 79 20 6e 65 65 64 73 2e 0a 2a 2a 0a  emory needs..**.
d8f0: 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20 53 51 4c  ** Note that SQL
d900: 69 74 65 20 63 6f 6d 65 73 20 77 69 74 68 20 73  ite comes with s
d910: 65 76 65 72 61 6c 20 5b 62 75 69 6c 74 2d 69 6e  everal [built-in
d920: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
d930: 72 73 5d 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  rs].** that are 
d940: 70 65 72 66 65 63 74 6c 79 20 61 64 65 71 75 61  perfectly adequa
d950: 74 65 20 66 6f 72 20 74 68 65 20 6f 76 65 72 77  te for the overw
d960: 68 65 6c 6d 69 6e 67 20 6d 61 6a 6f 72 69 74 79  helming majority
d970: 20 6f 66 20 61 70 70 6c 69 63 61 74 69 6f 6e 73   of applications
d980: 0a 2a 2a 20 61 6e 64 20 74 68 61 74 20 74 68 69  .** and that thi
d990: 73 20 6f 62 6a 65 63 74 20 69 73 20 6f 6e 6c 79  s object is only
d9a0: 20 75 73 65 66 75 6c 20 74 6f 20 61 20 74 69 6e   useful to a tin
d9b0: 79 20 6d 69 6e 6f 72 69 74 79 20 6f 66 20 61 70  y minority of ap
d9c0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 77 69  plications.** wi
d9d0: 74 68 20 73 70 65 63 69 61 6c 69 7a 65 64 20 6d  th specialized m
d9e0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
d9f0: 20 72 65 71 75 69 72 65 6d 65 6e 74 73 2e 20 20   requirements.  
da00: 54 68 69 73 20 6f 62 6a 65 63 74 20 69 73 0a 2a  This object is.*
da10: 2a 20 61 6c 73 6f 20 75 73 65 64 20 64 75 72 69  * also used duri
da20: 6e 67 20 74 65 73 74 69 6e 67 20 6f 66 20 53 51  ng testing of SQ
da30: 4c 69 74 65 20 69 6e 20 6f 72 64 65 72 20 74 6f  Lite in order to
da40: 20 73 70 65 63 69 66 79 20 61 6e 20 61 6c 74 65   specify an alte
da50: 72 6e 61 74 69 76 65 0a 2a 2a 20 6d 65 6d 6f 72  rnative.** memor
da60: 79 20 61 6c 6c 6f 63 61 74 6f 72 20 74 68 61 74  y allocator that
da70: 20 73 69 6d 75 6c 61 74 65 73 20 6d 65 6d 6f 72   simulates memor
da80: 79 20 6f 75 74 2d 6f 66 2d 6d 65 6d 6f 72 79 20  y out-of-memory 
da90: 63 6f 6e 64 69 74 69 6f 6e 73 20 69 6e 0a 2a 2a  conditions in.**
daa0: 20 6f 72 64 65 72 20 74 6f 20 76 65 72 69 66 79   order to verify
dab0: 20 74 68 61 74 20 53 51 4c 69 74 65 20 72 65 63   that SQLite rec
dac0: 6f 76 65 72 73 20 67 72 61 63 65 66 75 6c 6c 79  overs gracefully
dad0: 20 66 72 6f 6d 20 73 75 63 68 0a 2a 2a 20 63 6f   from such.** co
dae0: 6e 64 69 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20  nditions..**.** 
daf0: 54 68 65 20 78 4d 61 6c 6c 6f 63 20 61 6e 64 20  The xMalloc and 
db00: 78 46 72 65 65 20 6d 65 74 68 6f 64 73 20 6d 75  xFree methods mu
db10: 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 74 68 65  st work like the
db20: 0a 2a 2a 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  .** malloc() and
db30: 20 66 72 65 65 28 29 20 66 75 6e 63 74 69 6f 6e   free() function
db40: 73 20 66 72 6f 6d 20 74 68 65 20 73 74 61 6e 64  s from the stand
db50: 61 72 64 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a  ard C library..*
db60: 2a 20 54 68 65 20 78 52 65 61 6c 6c 6f 63 20 6d  * The xRealloc m
db70: 65 74 68 6f 64 20 6d 75 73 74 20 77 6f 72 6b 20  ethod must work 
db80: 6c 69 6b 65 20 72 65 61 6c 6c 6f 63 28 29 20 66  like realloc() f
db90: 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
dba0: 20 43 20 6c 69 62 72 61 72 79 0a 2a 2a 20 77 69   C library.** wi
dbb0: 74 68 20 74 68 65 20 65 78 63 65 70 74 69 6f 6e  th the exception
dbc0: 20 74 68 61 74 20 69 66 20 74 68 65 20 73 65 63   that if the sec
dbd0: 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
dbe0: 78 52 65 61 6c 6c 6f 63 20 69 73 20 7a 65 72 6f  xRealloc is zero
dbf0: 2c 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 6d 75  ,.** xRealloc mu
dc00: 73 74 20 62 65 20 61 20 6e 6f 2d 6f 70 20 2d 20  st be a no-op - 
dc10: 69 74 20 6d 75 73 74 20 6e 6f 74 20 70 65 72 66  it must not perf
dc20: 6f 72 6d 20 61 6e 79 20 61 6c 6c 6f 63 61 74 69  orm any allocati
dc30: 6f 6e 20 6f 72 0a 2a 2a 20 64 65 61 6c 6c 6f 63  on or.** dealloc
dc40: 61 74 69 6f 6e 2e 20 20 5e 53 51 4c 69 74 65 20  ation.  ^SQLite 
dc50: 67 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20  guarantees that 
dc60: 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
dc70: 65 6e 74 20 74 6f 0a 2a 2a 20 78 52 65 61 6c 6c  ent to.** xReall
dc80: 6f 63 20 69 73 20 61 6c 77 61 79 73 20 61 20 76  oc is always a v
dc90: 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
dca0: 20 61 20 70 72 69 6f 72 20 63 61 6c 6c 20 74 6f   a prior call to
dcb0: 20 78 52 6f 75 6e 64 75 70 2e 0a 2a 2a 20 41 6e   xRoundup..** An
dcc0: 64 20 73 6f 20 69 6e 20 63 61 73 65 73 20 77 68  d so in cases wh
dcd0: 65 72 65 20 78 52 6f 75 6e 64 75 70 20 61 6c 77  ere xRoundup alw
dce0: 61 79 73 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ays returns a po
dcf0: 73 69 74 69 76 65 20 6e 75 6d 62 65 72 2c 0a 2a  sitive number,.*
dd00: 2a 20 78 52 65 61 6c 6c 6f 63 20 63 61 6e 20 70  * xRealloc can p
dd10: 65 72 66 6f 72 6d 20 65 78 61 63 74 6c 79 20 61  erform exactly a
dd20: 73 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 6c  s the standard l
dd30: 69 62 72 61 72 79 20 72 65 61 6c 6c 6f 63 28 29  ibrary realloc()
dd40: 20 61 6e 64 0a 2a 2a 20 73 74 69 6c 6c 20 62 65   and.** still be
dd50: 20 69 6e 20 63 6f 6d 70 6c 69 61 6e 63 65 20 77   in compliance w
dd60: 69 74 68 20 74 68 69 73 20 73 70 65 63 69 66 69  ith this specifi
dd70: 63 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 78 53  cation..**.** xS
dd80: 69 7a 65 20 73 68 6f 75 6c 64 20 72 65 74 75 72  ize should retur
dd90: 6e 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20  n the allocated 
dda0: 73 69 7a 65 20 6f 66 20 61 20 6d 65 6d 6f 72 79  size of a memory
ddb0: 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 70   allocation.** p
ddc0: 72 65 76 69 6f 75 73 6c 79 20 6f 62 74 61 69 6e  reviously obtain
ddd0: 65 64 20 66 72 6f 6d 20 78 4d 61 6c 6c 6f 63 20  ed from xMalloc 
dde0: 6f 72 20 78 52 65 61 6c 6c 6f 63 2e 20 20 54 68  or xRealloc.  Th
ddf0: 65 20 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65  e allocated size
de00: 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20 61 74  .** is always at
de10: 20 6c 65 61 73 74 20 61 73 20 62 69 67 20 61 73   least as big as
de20: 20 74 68 65 20 72 65 71 75 65 73 74 65 64 20 73   the requested s
de30: 69 7a 65 20 62 75 74 20 6d 61 79 20 62 65 20 6c  ize but may be l
de40: 61 72 67 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  arger..**.** The
de50: 20 78 52 6f 75 6e 64 75 70 20 6d 65 74 68 6f 64   xRoundup method
de60: 20 72 65 74 75 72 6e 73 20 77 68 61 74 20 77 6f   returns what wo
de70: 75 6c 64 20 62 65 20 74 68 65 20 61 6c 6c 6f 63  uld be the alloc
de80: 61 74 65 64 20 73 69 7a 65 20 6f 66 0a 2a 2a 20  ated size of.** 
de90: 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
dea0: 69 6f 6e 20 67 69 76 65 6e 20 61 20 70 61 72 74  ion given a part
deb0: 69 63 75 6c 61 72 20 72 65 71 75 65 73 74 65 64  icular requested
dec0: 20 73 69 7a 65 2e 20 20 4d 6f 73 74 20 6d 65 6d   size.  Most mem
ded0: 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63 61 74 6f 72  ory.** allocator
dee0: 73 20 72 6f 75 6e 64 20 75 70 20 6d 65 6d 6f 72  s round up memor
def0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 20 61 74  y allocations at
df00: 20 6c 65 61 73 74 20 74 6f 20 74 68 65 20 6e 65   least to the ne
df10: 78 74 20 6d 75 6c 74 69 70 6c 65 0a 2a 2a 20 6f  xt multiple.** o
df20: 66 20 38 2e 20 20 53 6f 6d 65 20 61 6c 6c 6f 63  f 8.  Some alloc
df30: 61 74 6f 72 73 20 72 6f 75 6e 64 20 75 70 20 74  ators round up t
df40: 6f 20 61 20 6c 61 72 67 65 72 20 6d 75 6c 74 69  o a larger multi
df50: 70 6c 65 20 6f 72 20 74 6f 20 61 20 70 6f 77 65  ple or to a powe
df60: 72 20 6f 66 20 32 2e 0a 2a 2a 20 45 76 65 72 79  r of 2..** Every
df70: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
df80: 6f 6e 20 72 65 71 75 65 73 74 20 63 6f 6d 69 6e  on request comin
df90: 67 20 69 6e 20 74 68 72 6f 75 67 68 20 5b 73 71  g in through [sq
dfa0: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 0a  lite3_malloc()].
dfb0: 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72  ** or [sqlite3_r
dfc0: 65 61 6c 6c 6f 63 28 29 5d 20 66 69 72 73 74 20  ealloc()] first 
dfd0: 63 61 6c 6c 73 20 78 52 6f 75 6e 64 75 70 2e 20  calls xRoundup. 
dfe0: 20 49 66 20 78 52 6f 75 6e 64 75 70 20 72 65 74   If xRoundup ret
dff0: 75 72 6e 73 20 30 2c 20 0a 2a 2a 20 74 68 61 74  urns 0, .** that
e000: 20 63 61 75 73 65 73 20 74 68 65 20 63 6f 72 72   causes the corr
e010: 65 73 70 6f 6e 64 69 6e 67 20 6d 65 6d 6f 72 79  esponding memory
e020: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 74 6f 20 66   allocation to f
e030: 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  ail..**.** The x
e040: 49 6e 69 74 20 6d 65 74 68 6f 64 20 69 6e 69 74  Init method init
e050: 69 61 6c 69 7a 65 73 20 74 68 65 20 6d 65 6d 6f  ializes the memo
e060: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 2e 20 20 28  ry allocator.  (
e070: 46 6f 72 20 65 78 61 6d 70 6c 65 2c 0a 2a 2a 20  For example,.** 
e080: 69 74 20 6d 69 67 68 74 20 61 6c 6c 6f 63 61 74  it might allocat
e090: 65 20 61 6e 79 20 72 65 71 75 69 72 65 20 6d 75  e any require mu
e0a0: 74 65 78 65 73 20 6f 72 20 69 6e 69 74 69 61 6c  texes or initial
e0b0: 69 7a 65 20 69 6e 74 65 72 6e 61 6c 20 64 61 74  ize internal dat
e0c0: 61 0a 2a 2a 20 73 74 72 75 63 74 75 72 65 73 2e  a.** structures.
e0d0: 20 20 54 68 65 20 78 53 68 75 74 64 6f 77 6e 20    The xShutdown 
e0e0: 6d 65 74 68 6f 64 20 69 73 20 69 6e 76 6f 6b 65  method is invoke
e0f0: 64 20 28 69 6e 64 69 72 65 63 74 6c 79 29 20 62  d (indirectly) b
e100: 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 68  y.** [sqlite3_sh
e110: 75 74 64 6f 77 6e 28 29 5d 20 61 6e 64 20 73 68  utdown()] and sh
e120: 6f 75 6c 64 20 64 65 61 6c 6c 6f 63 61 74 65 20  ould deallocate 
e130: 61 6e 79 20 72 65 73 6f 75 72 63 65 73 20 61 63  any resources ac
e140: 71 75 69 72 65 64 0a 2a 2a 20 62 79 20 78 49 6e  quired.** by xIn
e150: 69 74 2e 20 20 54 68 65 20 70 41 70 70 44 61 74  it.  The pAppDat
e160: 61 20 70 6f 69 6e 74 65 72 20 69 73 20 75 73 65  a pointer is use
e170: 64 20 61 73 20 74 68 65 20 6f 6e 6c 79 20 70 61  d as the only pa
e180: 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 78 49  rameter to.** xI
e190: 6e 69 74 20 61 6e 64 20 78 53 68 75 74 64 6f 77  nit and xShutdow
e1a0: 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  n..**.** SQLite 
e1b0: 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c 49 54  holds the [SQLIT
e1c0: 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43 5f 4d  E_MUTEX_STATIC_M
e1d0: 41 53 54 45 52 5d 20 6d 75 74 65 78 20 77 68 65  ASTER] mutex whe
e1e0: 6e 20 69 74 20 69 6e 76 6f 6b 65 73 0a 2a 2a 20  n it invokes.** 
e1f0: 74 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64  the xInit method
e200: 2c 20 73 6f 20 74 68 65 20 78 49 6e 69 74 20 6d  , so the xInit m
e210: 65 74 68 6f 64 20 6e 65 65 64 20 6e 6f 74 20 62  ethod need not b
e220: 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 20 54  e threadsafe.  T
e230: 68 65 0a 2a 2a 20 78 53 68 75 74 64 6f 77 6e 20  he.** xShutdown 
e240: 6d 65 74 68 6f 64 20 69 73 20 6f 6e 6c 79 20 63  method is only c
e250: 61 6c 6c 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  alled from [sqli
e260: 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 20  te3_shutdown()] 
e270: 73 6f 20 69 74 20 64 6f 65 73 0a 2a 2a 20 6e 6f  so it does.** no
e280: 74 20 6e 65 65 64 20 74 6f 20 62 65 20 74 68 72  t need to be thr
e290: 65 61 64 73 61 66 65 20 65 69 74 68 65 72 2e 20  eadsafe either. 
e2a0: 20 46 6f 72 20 61 6c 6c 20 6f 74 68 65 72 20 6d   For all other m
e2b0: 65 74 68 6f 64 73 2c 20 53 51 4c 69 74 65 0a 2a  ethods, SQLite.*
e2c0: 2a 20 68 6f 6c 64 73 20 74 68 65 20 5b 53 51 4c  * holds the [SQL
e2d0: 49 54 45 5f 4d 55 54 45 58 5f 53 54 41 54 49 43  ITE_MUTEX_STATIC
e2e0: 5f 4d 45 4d 5d 20 6d 75 74 65 78 20 61 73 20 6c  _MEM] mutex as l
e2f0: 6f 6e 67 20 61 73 20 74 68 65 0a 2a 2a 20 5b 53  ong as the.** [S
e300: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
e310: 53 54 41 54 55 53 5d 20 63 6f 6e 66 69 67 75 72  STATUS] configur
e320: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73 20  ation option is 
e330: 74 75 72 6e 65 64 20 6f 6e 20 28 77 68 69 63 68  turned on (which
e340: 0a 2a 2a 20 69 74 20 69 73 20 62 79 20 64 65 66  .** it is by def
e350: 61 75 6c 74 29 20 61 6e 64 20 73 6f 20 74 68 65  ault) and so the
e360: 20 6d 65 74 68 6f 64 73 20 61 72 65 20 61 75 74   methods are aut
e370: 6f 6d 61 74 69 63 61 6c 6c 79 20 73 65 72 69 61  omatically seria
e380: 6c 69 7a 65 64 2e 0a 2a 2a 20 48 6f 77 65 76 65  lized..** Howeve
e390: 72 2c 20 69 66 20 5b 53 51 4c 49 54 45 5f 43 4f  r, if [SQLITE_CO
e3a0: 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 5d 20  NFIG_MEMSTATUS] 
e3b0: 69 73 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65  is disabled, the
e3c0: 6e 20 74 68 65 20 6f 74 68 65 72 0a 2a 2a 20 6d  n the other.** m
e3d0: 65 74 68 6f 64 73 20 6d 75 73 74 20 62 65 20 74  ethods must be t
e3e0: 68 72 65 61 64 73 61 66 65 20 6f 72 20 65 6c 73  hreadsafe or els
e3f0: 65 20 6d 61 6b 65 20 74 68 65 69 72 20 6f 77 6e  e make their own
e400: 20 61 72 72 61 6e 67 65 6d 65 6e 74 73 20 66 6f   arrangements fo
e410: 72 0a 2a 2a 20 73 65 72 69 61 6c 69 7a 61 74 69  r.** serializati
e420: 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65  on..**.** SQLite
e430: 20 77 69 6c 6c 20 6e 65 76 65 72 20 69 6e 76 6f   will never invo
e440: 6b 65 20 78 49 6e 69 74 28 29 20 6d 6f 72 65 20  ke xInit() more 
e450: 74 68 61 6e 20 6f 6e 63 65 20 77 69 74 68 6f 75  than once withou
e460: 74 20 61 6e 20 69 6e 74 65 72 76 65 6e 69 6e 67  t an intervening
e470: 0a 2a 2a 20 63 61 6c 6c 20 74 6f 20 78 53 68 75  .** call to xShu
e480: 74 64 6f 77 6e 28 29 2e 0a 2a 2f 0a 74 79 70 65  tdown()..*/.type
e490: 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
e4a0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 73  e3_mem_methods s
e4b0: 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f  qlite3_mem_metho
e4c0: 64 73 3b 0a 73 74 72 75 63 74 20 73 71 6c 69 74  ds;.struct sqlit
e4d0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 20 7b  e3_mem_methods {
e4e0: 0a 20 20 76 6f 69 64 20 2a 28 2a 78 4d 61 6c 6c  .  void *(*xMall
e4f0: 6f 63 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20  oc)(int);       
e500: 20 20 2f 2a 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f    /* Memory allo
e510: 63 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 20  cation function 
e520: 2a 2f 0a 20 20 76 6f 69 64 20 28 2a 78 46 72 65  */.  void (*xFre
e530: 65 29 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20  e)(void*);      
e540: 20 20 20 20 2f 2a 20 46 72 65 65 20 61 20 70 72      /* Free a pr
e550: 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a  ior allocation *
e560: 2f 0a 20 20 76 6f 69 64 20 2a 28 2a 78 52 65 61  /.  void *(*xRea
e570: 6c 6c 6f 63 29 28 76 6f 69 64 2a 2c 69 6e 74 29  lloc)(void*,int)
e580: 3b 20 20 2f 2a 20 52 65 73 69 7a 65 20 61 6e 20  ;  /* Resize an 
e590: 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20  allocation */.  
e5a0: 69 6e 74 20 28 2a 78 53 69 7a 65 29 28 76 6f 69  int (*xSize)(voi
e5b0: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 20 2f  d*);           /
e5c0: 2a 20 52 65 74 75 72 6e 20 74 68 65 20 73 69 7a  * Return the siz
e5d0: 65 20 6f 66 20 61 6e 20 61 6c 6c 6f 63 61 74 69  e of an allocati
e5e0: 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 52  on */.  int (*xR
e5f0: 6f 75 6e 64 75 70 29 28 69 6e 74 29 3b 20 20 20  oundup)(int);   
e600: 20 20 20 20 20 20 20 2f 2a 20 52 6f 75 6e 64 20         /* Round 
e610: 75 70 20 72 65 71 75 65 73 74 20 73 69 7a 65 20  up request size 
e620: 74 6f 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 69  to allocation si
e630: 7a 65 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 49  ze */.  int (*xI
e640: 6e 69 74 29 28 76 6f 69 64 2a 29 3b 20 20 20 20  nit)(void*);    
e650: 20 20 20 20 20 20 20 2f 2a 20 49 6e 69 74 69 61         /* Initia
e660: 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f 72 79 20  lize the memory 
e670: 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a 20 20 76  allocator */.  v
e680: 6f 69 64 20 28 2a 78 53 68 75 74 64 6f 77 6e 29  oid (*xShutdown)
e690: 28 76 6f 69 64 2a 29 3b 20 20 20 20 20 20 2f 2a  (void*);      /*
e6a0: 20 44 65 69 6e 69 74 69 61 6c 69 7a 65 20 74 68   Deinitialize th
e6b0: 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
e6c0: 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 2a 70 41  or */.  void *pA
e6d0: 70 70 44 61 74 61 3b 20 20 20 20 20 20 20 20 20  ppData;         
e6e0: 20 20 20 20 20 20 20 2f 2a 20 41 72 67 75 6d 65         /* Argume
e6f0: 6e 74 20 74 6f 20 78 49 6e 69 74 28 29 20 61 6e  nt to xInit() an
e700: 64 20 78 53 68 75 74 64 6f 77 6e 28 29 20 2a 2f  d xShutdown() */
e710: 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .};../*.** CAPI3
e720: 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 61 74 69  REF: Configurati
e730: 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 20 4b 45  on Options.** KE
e740: 59 57 4f 52 44 53 3a 20 7b 63 6f 6e 66 69 67 75  YWORDS: {configu
e750: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 7d 0a 2a  ration option}.*
e760: 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73 74  *.** These const
e770: 61 6e 74 73 20 61 72 65 20 74 68 65 20 61 76 61  ants are the ava
e780: 69 6c 61 62 6c 65 20 69 6e 74 65 67 65 72 20 63  ilable integer c
e790: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
e7a0: 69 6f 6e 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e  ions that.** can
e7b0: 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
e7c0: 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
e7d0: 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
e7e0: 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72  _config()] inter
e7f0: 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20  face..**.** New 
e800: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e810: 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64  tions may be add
e820: 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c  ed in future rel
e830: 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e  eases of SQLite.
e840: 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e  .** Existing con
e850: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
e860: 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63  ns might be disc
e870: 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69  ontinued.  Appli
e880: 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c  cations.** shoul
e890: 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75  d check the retu
e8a0: 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71  rn code from [sq
e8b0: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20  lite3_config()] 
e8c0: 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74 68 61  to make sure tha
e8d0: 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20 77 6f  t.** the call wo
e8e0: 72 6b 65 64 2e 20 20 54 68 65 20 5b 73 71 6c 69  rked.  The [sqli
e8f0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e  te3_config()] in
e900: 74 65 72 66 61 63 65 20 77 69 6c 6c 20 72 65 74  terface will ret
e910: 75 72 6e 20 61 0a 2a 2a 20 6e 6f 6e 2d 7a 65 72  urn a.** non-zer
e920: 6f 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69  o [error code] i
e930: 66 20 61 20 64 69 73 63 6f 6e 74 69 6e 75 65 64  f a discontinued
e940: 20 6f 72 20 75 6e 73 75 70 70 6f 72 74 65 64 20   or unsupported 
e950: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
e960: 74 69 6f 6e 0a 2a 2a 20 69 73 20 69 6e 76 6f 6b  tion.** is invok
e970: 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a  ed..**.** <dl>.*
e980: 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  * [[SQLITE_CONFI
e990: 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 5d  G_SINGLETHREAD]]
e9a0: 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46   <dt>SQLITE_CONF
e9b0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 3c  IG_SINGLETHREAD<
e9c0: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 72  /dt>.** <dd>Ther
e9d0: 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d 65 6e  e are no argumen
e9e0: 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74 69 6f  ts to this optio
e9f0: 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e  n.  ^This option
ea00: 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b 74 68   sets the.** [th
ea10: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 74 6f  reading mode] to
ea20: 20 53 69 6e 67 6c 65 2d 74 68 72 65 61 64 2e 20   Single-thread. 
ea30: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
ea40: 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a 20   it disables.** 
ea50: 61 6c 6c 20 6d 75 74 65 78 69 6e 67 20 61 6e 64  all mutexing and
ea60: 20 70 75 74 73 20 53 51 4c 69 74 65 20 69 6e 74   puts SQLite int
ea70: 6f 20 61 20 6d 6f 64 65 20 77 68 65 72 65 20 69  o a mode where i
ea80: 74 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 75 73  t can only be us
ea90: 65 64 0a 2a 2a 20 62 79 20 61 20 73 69 6e 67 6c  ed.** by a singl
eaa0: 65 20 74 68 72 65 61 64 2e 20 20 20 5e 49 66 20  e thread.   ^If 
eab0: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
eac0: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
ead0: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
eae0: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
eaf0: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
eb00: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
eb10: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
eb20: 6f 73 73 69 62 6c 65 20 74 6f 20 63 68 61 6e 67  ossible to chang
eb30: 65 20 74 68 65 20 5b 74 68 72 65 61 64 69 6e 67  e the [threading
eb40: 20 6d 6f 64 65 5d 20 66 72 6f 6d 20 69 74 73 20   mode] from its 
eb50: 64 65 66 61 75 6c 74 0a 2a 2a 20 76 61 6c 75 65  default.** value
eb60: 20 6f 66 20 53 69 6e 67 6c 65 2d 74 68 72 65 61   of Single-threa
eb70: 64 20 61 6e 64 20 73 6f 20 5b 73 71 6c 69 74 65  d and so [sqlite
eb80: 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c  3_config()] will
eb90: 20 72 65 74 75 72 6e 20 0a 2a 2a 20 5b 53 51 4c   return .** [SQL
eba0: 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61  ITE_ERROR] if ca
ebb0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 53 51  lled with the SQ
ebc0: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
ebd0: 4c 45 54 48 52 45 41 44 0a 2a 2a 20 63 6f 6e 66  LETHREAD.** conf
ebe0: 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
ebf0: 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
ec00: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
ec10: 54 49 54 48 52 45 41 44 5d 5d 20 3c 64 74 3e 53  TITHREAD]] <dt>S
ec20: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c  QLITE_CONFIG_MUL
ec30: 54 49 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a  TITHREAD</dt>.**
ec40: 20 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e   <dd>There are n
ec50: 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  o arguments to t
ec60: 68 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68  his option.  ^Th
ec70: 69 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74  is option sets t
ec80: 68 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67  he.** [threading
ec90: 20 6d 6f 64 65 5d 20 74 6f 20 4d 75 6c 74 69 2d   mode] to Multi-
eca0: 74 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65  thread.  In othe
ecb0: 72 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61  r words, it disa
ecc0: 62 6c 65 73 0a 2a 2a 20 6d 75 74 65 78 69 6e 67  bles.** mutexing
ecd0: 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
ece0: 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e 64 20 5b 70  nnection] and [p
ecf0: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
ed00: 74 5d 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 20 54  t] objects..** T
ed10: 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 69  he application i
ed20: 73 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f  s responsible fo
ed30: 72 20 73 65 72 69 61 6c 69 7a 69 6e 67 20 61 63  r serializing ac
ed40: 63 65 73 73 20 74 6f 0a 2a 2a 20 5b 64 61 74 61  cess to.** [data
ed50: 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  base connections
ed60: 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20  ] and [prepared 
ed70: 73 74 61 74 65 6d 65 6e 74 73 5d 2e 20 20 42 75  statements].  Bu
ed80: 74 20 6f 74 68 65 72 20 6d 75 74 65 78 65 73 0a  t other mutexes.
ed90: 2a 2a 20 61 72 65 20 65 6e 61 62 6c 65 64 20 73  ** are enabled s
eda0: 6f 20 74 68 61 74 20 53 51 4c 69 74 65 20 77 69  o that SQLite wi
edb0: 6c 6c 20 62 65 20 73 61 66 65 20 74 6f 20 75 73  ll be safe to us
edc0: 65 20 69 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  e in a multi-thr
edd0: 65 61 64 65 64 0a 2a 2a 20 65 6e 76 69 72 6f 6e  eaded.** environ
ede0: 6d 65 6e 74 20 61 73 20 6c 6f 6e 67 20 61 73 20  ment as long as 
edf0: 6e 6f 20 74 77 6f 20 74 68 72 65 61 64 73 20 61  no two threads a
ee00: 74 74 65 6d 70 74 20 74 6f 20 75 73 65 20 74 68  ttempt to use th
ee10: 65 20 73 61 6d 65 0a 2a 2a 20 5b 64 61 74 61 62  e same.** [datab
ee20: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ee30: 61 74 20 74 68 65 20 73 61 6d 65 20 74 69 6d 65  at the same time
ee40: 2e 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73  .  ^If SQLite is
ee50: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
ee60: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
ee70: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
ee80: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
ee90: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
eea0: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
eeb0: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
eec0: 6f 20 73 65 74 20 74 68 65 20 4d 75 6c 74 69 2d  o set the Multi-
eed0: 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
eee0: 67 20 6d 6f 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b  g mode] and.** [
eef0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
ef00: 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53  ] will return [S
ef10: 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 69 66 20  QLITE_ERROR] if 
ef20: 63 61 6c 6c 65 64 20 77 69 74 68 20 74 68 65 0a  called with the.
ef30: 2a 2a 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  ** SQLITE_CONFIG
ef40: 5f 4d 55 4c 54 49 54 48 52 45 41 44 20 63 6f 6e  _MULTITHREAD con
ef50: 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f  figuration optio
ef60: 6e 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  n.</dd>.**.** [[
ef70: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45  SQLITE_CONFIG_SE
ef80: 52 49 41 4c 49 5a 45 44 5d 5d 20 3c 64 74 3e 53  RIALIZED]] <dt>S
ef90: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
efa0: 49 41 4c 49 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20  IALIZED</dt>.** 
efb0: 3c 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f  <dd>There are no
efc0: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
efd0: 69 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69  is option.  ^Thi
efe0: 73 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68  s option sets th
eff0: 65 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20  e.** [threading 
f000: 6d 6f 64 65 5d 20 74 6f 20 53 65 72 69 61 6c 69  mode] to Seriali
f010: 7a 65 64 2e 20 49 6e 20 6f 74 68 65 72 20 77 6f  zed. In other wo
f020: 72 64 73 2c 20 74 68 69 73 20 6f 70 74 69 6f 6e  rds, this option
f030: 20 65 6e 61 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20   enables.** all 
f040: 6d 75 74 65 78 65 73 20 69 6e 63 6c 75 64 69 6e  mutexes includin
f050: 67 20 74 68 65 20 72 65 63 75 72 73 69 76 65 0a  g the recursive.
f060: 2a 2a 20 6d 75 74 65 78 65 73 20 6f 6e 20 5b 64  ** mutexes on [d
f070: 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
f080: 6f 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65  on] and [prepare
f090: 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a  d statement] obj
f0a0: 65 63 74 73 2e 0a 2a 2a 20 49 6e 20 74 68 69 73  ects..** In this
f0b0: 20 6d 6f 64 65 20 28 77 68 69 63 68 20 69 73 20   mode (which is 
f0c0: 74 68 65 20 64 65 66 61 75 6c 74 20 77 68 65 6e  the default when
f0d0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
f0e0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 5b 53 51 4c  led with.** [SQL
f0f0: 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 3d 31  ITE_THREADSAFE=1
f100: 5d 29 20 74 68 65 20 53 51 4c 69 74 65 20 6c 69  ]) the SQLite li
f110: 62 72 61 72 79 20 77 69 6c 6c 20 69 74 73 65 6c  brary will itsel
f120: 66 20 73 65 72 69 61 6c 69 7a 65 20 61 63 63 65  f serialize acce
f130: 73 73 0a 2a 2a 20 74 6f 20 5b 64 61 74 61 62 61  ss.** to [databa
f140: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20  se connections] 
f150: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
f160: 61 74 65 6d 65 6e 74 73 5d 20 73 6f 20 74 68 61  atements] so tha
f170: 74 20 74 68 65 0a 2a 2a 20 61 70 70 6c 69 63 61  t the.** applica
f180: 74 69 6f 6e 20 69 73 20 66 72 65 65 20 74 6f 20  tion is free to 
f190: 75 73 65 20 74 68 65 20 73 61 6d 65 20 5b 64 61  use the same [da
f1a0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
f1b0: 6e 5d 20 6f 72 20 74 68 65 0a 2a 2a 20 73 61 6d  n] or the.** sam
f1c0: 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
f1d0: 65 6d 65 6e 74 5d 20 69 6e 20 64 69 66 66 65 72  ement] in differ
f1e0: 65 6e 74 20 74 68 72 65 61 64 73 20 61 74 20 74  ent threads at t
f1f0: 68 65 20 73 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a  he same time..**
f200: 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
f210: 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
f220: 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
f230: 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
f240: 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
f250: 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
f260: 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69 73 20  n then.** it is 
f270: 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74 6f 20  not possible to 
f280: 73 65 74 20 74 68 65 20 53 65 72 69 61 6c 69 7a  set the Serializ
f290: 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f  ed [threading mo
f2a0: 64 65 5d 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  de] and.** [sqli
f2b0: 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69  te3_config()] wi
f2c0: 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  ll return [SQLIT
f2d0: 45 5f 45 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c  E_ERROR] if call
f2e0: 65 64 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 53  ed with the.** S
f2f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
f300: 49 41 4c 49 5a 45 44 20 63 6f 6e 66 69 67 75 72  IALIZED configur
f310: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64  ation option.</d
f320: 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
f330: 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d  E_CONFIG_MALLOC]
f340: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
f350: 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a  FIG_MALLOC</dt>.
f360: 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
f370: 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
f380: 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
f390: 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
f3a0: 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e   to an.** instan
f3b0: 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74  ce of the [sqlit
f3c0: 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20  e3_mem_methods] 
f3d0: 73 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20  structure.  The 
f3e0: 61 72 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69  argument specifi
f3f0: 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76  es.** alternativ
f400: 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d 65 6d 6f  e low-level memo
f410: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f  ry allocation ro
f420: 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75 73 65  utines to be use
f430: 64 20 69 6e 20 70 6c 61 63 65 20 6f 66 0a 2a 2a  d in place of.**
f440: 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f   the memory allo
f450: 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 20  cation routines 
f460: 62 75 69 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74  built into SQLit
f470: 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20 6d 61 6b  e.)^ ^SQLite mak
f480: 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e 20 70 72  es.** its own pr
f490: 69 76 61 74 65 20 63 6f 70 79 20 6f 66 20 74 68  ivate copy of th
f4a0: 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68 65  e content of the
f4b0: 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65   [sqlite3_mem_me
f4c0: 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65  thods] structure
f4d0: 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68 65 20 5b  .** before the [
f4e0: 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
f4f0: 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e 3c  ] call returns.<
f500: 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c  /dd>.**.** [[SQL
f510: 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41  ITE_CONFIG_GETMA
f520: 4c 4c 4f 43 5d 5d 20 3c 64 74 3e 53 51 4c 49 54  LLOC]] <dt>SQLIT
f530: 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 41 4c 4c  E_CONFIG_GETMALL
f540: 4f 43 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  OC</dt>.** <dd> 
f550: 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61  ^(This option ta
f560: 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67  kes a single arg
f570: 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61  ument which is a
f580: 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a   pointer to an.*
f590: 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
f5a0: 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d  e [sqlite3_mem_m
f5b0: 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75 72  ethods] structur
f5c0: 65 2e 20 20 54 68 65 20 5b 73 71 6c 69 74 65 33  e.  The [sqlite3
f5d0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a  _mem_methods].**
f5e0: 20 73 74 72 75 63 74 75 72 65 20 69 73 20 66 69   structure is fi
f5f0: 6c 6c 65 64 20 77 69 74 68 20 74 68 65 20 63 75  lled with the cu
f600: 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 20  rrently defined 
f610: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f620: 6e 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a  n routines.)^.**
f630: 20 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e   This option can
f640: 20 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72   be used to over
f650: 6c 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74  load the default
f660: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
f670: 6f 6e 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77  on.** routines w
f680: 69 74 68 20 61 20 77 72 61 70 70 65 72 20 74 68  ith a wrapper th
f690: 61 74 20 73 69 6d 75 6c 61 74 69 6f 6e 73 20 6d  at simulations m
f6a0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
f6b0: 20 66 61 69 6c 75 72 65 20 6f 72 0a 2a 2a 20 74   failure or.** t
f6c0: 72 61 63 6b 73 20 6d 65 6d 6f 72 79 20 75 73 61  racks memory usa
f6d0: 67 65 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2e  ge, for example.
f6e0: 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53   </dd>.**.** [[S
f6f0: 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
f700: 53 54 41 54 55 53 5d 5d 20 3c 64 74 3e 53 51 4c  STATUS]] <dt>SQL
f710: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
f720: 41 54 55 53 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ATUS</dt>.** <dd
f730: 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 74  > ^This option t
f740: 61 6b 65 73 20 73 69 6e 67 6c 65 20 61 72 67 75  akes single argu
f750: 6d 65 6e 74 20 6f 66 20 74 79 70 65 20 69 6e 74  ment of type int
f760: 2c 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  , interpreted as
f770: 20 61 20 0a 2a 2a 20 62 6f 6f 6c 65 61 6e 2c 20   a .** boolean, 
f780: 77 68 69 63 68 20 65 6e 61 62 6c 65 73 20 6f 72  which enables or
f790: 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 63 6f   disables the co
f7a0: 6c 6c 65 63 74 69 6f 6e 20 6f 66 20 6d 65 6d 6f  llection of memo
f7b0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 0a 2a  ry allocation .*
f7c0: 2a 20 73 74 61 74 69 73 74 69 63 73 2e 20 5e 28  * statistics. ^(
f7d0: 57 68 65 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  When memory allo
f7e0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
f7f0: 73 20 61 72 65 20 64 69 73 61 62 6c 65 64 2c 20  s are disabled, 
f800: 74 68 65 20 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  the .** followin
f810: 67 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  g SQLite interfa
f820: 63 65 73 20 62 65 63 6f 6d 65 20 6e 6f 6e 2d 6f  ces become non-o
f830: 70 65 72 61 74 69 6f 6e 61 6c 3a 0a 2a 2a 20 20  perational:.**  
f840: 20 3c 75 6c 3e 0a 2a 2a 20 20 20 3c 6c 69 3e 20   <ul>.**   <li> 
f850: 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f  [sqlite3_memory_
f860: 75 73 65 64 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69  used()].**   <li
f870: 3e 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  > [sqlite3_memor
f880: 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 0a 2a  y_highwater()].*
f890: 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69 74 65  *   <li> [sqlite
f8a0: 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d 69  3_soft_heap_limi
f8b0: 74 36 34 28 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e  t64()].**   <li>
f8c0: 20 5b 73 71 6c 69 74 65 33 5f 73 74 61 74 75 73   [sqlite3_status
f8d0: 28 29 5d 0a 2a 2a 20 20 20 3c 2f 75 6c 3e 29 5e  ()].**   </ul>)^
f8e0: 0a 2a 2a 20 5e 4d 65 6d 6f 72 79 20 61 6c 6c 6f  .** ^Memory allo
f8f0: 63 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63  cation statistic
f900: 73 20 61 72 65 20 65 6e 61 62 6c 65 64 20 62 79  s are enabled by
f910: 20 64 65 66 61 75 6c 74 20 75 6e 6c 65 73 73 20   default unless 
f920: 53 51 4c 69 74 65 20 69 73 0a 2a 2a 20 63 6f 6d  SQLite is.** com
f930: 70 69 6c 65 64 20 77 69 74 68 20 5b 53 51 4c 49  piled with [SQLI
f940: 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
f950: 41 54 55 53 5d 3d 30 20 69 6e 20 77 68 69 63 68  ATUS]=0 in which
f960: 20 63 61 73 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20   case memory.** 
f970: 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 74 61 74 69  allocation stati
f980: 73 74 69 63 73 20 61 72 65 20 64 69 73 61 62 6c  stics are disabl
f990: 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a  ed by default..*
f9a0: 2a 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b  * </dd>.**.** [[
f9b0: 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43  SQLITE_CONFIG_SC
f9c0: 52 41 54 43 48 5d 5d 20 3c 64 74 3e 53 51 4c 49  RATCH]] <dt>SQLI
f9d0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
f9e0: 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  H</dt>.** <dd> ^
f9f0: 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65 63  This option spec
fa00: 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20 6d  ifies a static m
fa10: 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68 61  emory buffer tha
fa20: 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73 65  t SQLite can use
fa30: 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68 20   for.** scratch 
fa40: 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20 61  memory.  There a
fa50: 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e  re three argumen
fa60: 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20 61  ts:  A pointer a
fa70: 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69 67  n 8-byte.** alig
fa80: 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66 65  ned memory buffe
fa90: 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68 65  r from which the
faa0: 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74   scratch allocat
fab0: 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a 20  ions will be.** 
fac0: 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65 20  drawn, the size 
fad0: 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68 20  of each scratch 
fae0: 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29 2c  allocation (sz),
faf0: 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78 69  .** and the maxi
fb00: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73 63  mum number of sc
fb10: 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f 6e  ratch allocation
fb20: 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a 2a  s (N).  The sz.*
fb30: 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  * argument must 
fb40: 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f 66  be a multiple of
fb50: 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73   16..** The firs
fb60: 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74 20  t argument must 
fb70: 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  be a pointer to 
fb80: 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  an 8-byte aligne
fb90: 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20 61  d buffer.** of a
fba0: 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79 74  t least sz*N byt
fbb0: 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a 2a  es of memory..**
fbc0: 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73   ^SQLite will us
fbd0: 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20 74  e no more than t
fbe0: 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66 65  wo scratch buffe
fbf0: 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20 20  rs per thread.  
fc00: 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20 62  So.** N should b
fc10: 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20 74  e set to twice t
fc20: 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78 69  he expected maxi
fc30: 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 68  mum number of th
fc40: 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69 74  reads..** ^SQLit
fc50: 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65 71  e will never req
fc60: 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20 62  uire a scratch b
fc70: 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d 6f  uffer that is mo
fc80: 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69 6d  re than 6.** tim
fc90: 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
fca0: 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20 53  page size. ^If S
fcb0: 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65 64  QLite needs need
fcc0: 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  s additional.** 
fcd0: 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20 62  scratch memory b
fce0: 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72  eyond what is pr
fcf0: 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20 63  ovided by this c
fd00: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
fd10: 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b 73  ion, then .** [s
fd20: 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
fd30: 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74 6f   will be used to
fd40: 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d 6f   obtain the memo
fd50: 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e 0a  ry needed.</dd>.
fd60: 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
fd70: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
fd80: 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  ] <dt>SQLITE_CON
fd90: 46 49 47 5f 50 41 47 45 43 41 43 48 45 3c 2f 64  FIG_PAGECACHE</d
fda0: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73  t>.** <dd> ^This
fdb0: 20 6f 70 74 69 6f 6e 20 73 70 65 63 69 66 69 65   option specifie
fdc0: 73 20 61 20 73 74 61 74 69 63 20 6d 65 6d 6f 72  s a static memor
fdd0: 79 20 62 75 66 66 65 72 20 74 68 61 74 20 53 51  y buffer that SQ
fde0: 4c 69 74 65 20 63 61 6e 20 75 73 65 20 66 6f 72  Lite can use for
fdf0: 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
fe00: 20 70 61 67 65 20 63 61 63 68 65 20 77 69 74 68   page cache with
fe10: 20 74 68 65 20 64 65 66 61 75 6c 74 20 70 61 67   the default pag
fe20: 65 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e  e cache implemen
fe30: 61 74 69 6f 6e 2e 20 20 0a 2a 2a 20 54 68 69 73  ation.  .** This
fe40: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 73   configuration s
fe50: 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 75 73 65  hould not be use
fe60: 64 20 69 66 20 61 6e 20 61 70 70 6c 69 63 61 74  d if an applicat
fe70: 69 6f 6e 2d 64 65 66 69 6e 65 20 70 61 67 65 0a  ion-define page.
fe80: 2a 2a 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65  ** cache impleme
fe90: 6e 74 61 74 69 6f 6e 20 69 73 20 6c 6f 61 64 65  ntation is loade
fea0: 64 20 75 73 69 6e 67 20 74 68 65 20 53 51 4c 49  d using the SQLI
feb0: 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
fec0: 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 54 68 65 72   option..** Ther
fed0: 65 20 61 72 65 20 74 68 72 65 65 20 61 72 67 75  e are three argu
fee0: 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70  ments to this op
fef0: 74 69 6f 6e 3a 20 41 20 70 6f 69 6e 74 65 72 20  tion: A pointer 
ff00: 74 6f 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  to 8-byte aligne
ff10: 64 0a 2a 2a 20 6d 65 6d 6f 72 79 2c 20 74 68 65  d.** memory, the
ff20: 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 70 61   size of each pa
ff30: 67 65 20 62 75 66 66 65 72 20 28 73 7a 29 2c 20  ge buffer (sz), 
ff40: 61 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  and the number o
ff50: 66 20 70 61 67 65 73 20 28 4e 29 2e 0a 2a 2a 20  f pages (N)..** 
ff60: 54 68 65 20 73 7a 20 61 72 67 75 6d 65 6e 74 20  The sz argument 
ff70: 73 68 6f 75 6c 64 20 62 65 20 74 68 65 20 73 69  should be the si
ff80: 7a 65 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73  ze of the larges
ff90: 74 20 64 61 74 61 62 61 73 65 20 70 61 67 65 0a  t database page.
ffa0: 2a 2a 20 28 61 20 70 6f 77 65 72 20 6f 66 20 74  ** (a power of t
ffb0: 77 6f 20 62 65 74 77 65 65 6e 20 35 31 32 20 61  wo between 512 a
ffc0: 6e 64 20 33 32 37 36 38 29 20 70 6c 75 73 20 61  nd 32768) plus a
ffd0: 20 6c 69 74 74 6c 65 20 65 78 74 72 61 20 66 6f   little extra fo
ffe0: 72 20 65 61 63 68 0a 2a 2a 20 70 61 67 65 20 68  r each.** page h
fff0: 65 61 64 65 72 2e 20 20 5e 54 68 65 20 70 61 67  eader.  ^The pag
10000 65 20 68 65 61 64 65 72 20 73 69 7a 65 20 69 73  e header size is
10010 20 32 30 20 74 6f 20 34 30 20 62 79 74 65 73 20   20 to 40 bytes 
10020 64 65 70 65 6e 64 69 6e 67 20 6f 6e 0a 2a 2a 20  depending on.** 
10030 74 68 65 20 68 6f 73 74 20 61 72 63 68 69 74 65  the host archite
10040 63 74 75 72 65 2e 20 20 5e 49 74 20 69 73 20 68  cture.  ^It is h
10050 61 72 6d 6c 65 73 73 2c 20 61 70 61 72 74 20 66  armless, apart f
10060 72 6f 6d 20 74 68 65 20 77 61 73 74 65 64 20 6d  rom the wasted m
10070 65 6d 6f 72 79 2c 0a 2a 2a 20 74 6f 20 6d 61 6b  emory,.** to mak
10080 65 20 73 7a 20 61 20 6c 69 74 74 6c 65 20 74 6f  e sz a little to
10090 6f 20 6c 61 72 67 65 2e 20 20 54 68 65 20 66 69  o large.  The fi
100a0 72 73 74 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  rst.** argument 
100b0 73 68 6f 75 6c 64 20 70 6f 69 6e 74 20 74 6f 20  should point to 
100c0 61 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 66  an allocation of
100d0 20 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62   at least sz*N b
100e0 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a  ytes of memory..
100f0 2a 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20  ** ^SQLite will 
10100 75 73 65 20 74 68 65 20 6d 65 6d 6f 72 79 20 70  use the memory p
10110 72 6f 76 69 64 65 64 20 62 79 20 74 68 65 20 66  rovided by the f
10120 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
10130 20 73 61 74 69 73 66 79 20 69 74 73 0a 2a 2a 20   satisfy its.** 
10140 6d 65 6d 6f 72 79 20 6e 65 65 64 73 20 66 6f 72  memory needs for
10150 20 74 68 65 20 66 69 72 73 74 20 4e 20 70 61 67   the first N pag
10160 65 73 20 74 68 61 74 20 69 74 20 61 64 64 73 20  es that it adds 
10170 74 6f 20 63 61 63 68 65 2e 20 20 5e 49 66 20 61  to cache.  ^If a
10180 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 70 61 67  dditional.** pag
10190 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79 20 69  e cache memory i
101a0 73 20 6e 65 65 64 65 64 20 62 65 79 6f 6e 64 20  s needed beyond 
101b0 77 68 61 74 20 69 73 20 70 72 6f 76 69 64 65 64  what is provided
101c0 20 62 79 20 74 68 69 73 20 6f 70 74 69 6f 6e 2c   by this option,
101d0 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69 74 65 20   then.** SQLite 
101e0 67 6f 65 73 20 74 6f 20 5b 73 71 6c 69 74 65 33  goes to [sqlite3
101f0 5f 6d 61 6c 6c 6f 63 28 29 5d 20 66 6f 72 20 74  _malloc()] for t
10200 68 65 20 61 64 64 69 74 69 6f 6e 61 6c 20 73 74  he additional st
10210 6f 72 61 67 65 20 73 70 61 63 65 2e 0a 2a 2a 20  orage space..** 
10220 54 68 65 20 70 6f 69 6e 74 65 72 20 69 6e 20 74  The pointer in t
10230 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
10240 74 20 6d 75 73 74 0a 2a 2a 20 62 65 20 61 6c 69  t must.** be ali
10250 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
10260 65 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75  e boundary or su
10270 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f  bsequent behavio
10280 72 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 77  r of SQLite.** w
10290 69 6c 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64  ill be undefined
102a0 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53  .</dd>.**.** [[S
102b0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 48 45 41  QLITE_CONFIG_HEA
102c0 50 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  P]] <dt>SQLITE_C
102d0 4f 4e 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a  ONFIG_HEAP</dt>.
102e0 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70  ** <dd> ^This op
102f0 74 69 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61  tion specifies a
10300 20 73 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62   static memory b
10310 75 66 66 65 72 20 74 68 61 74 20 53 51 4c 69 74  uffer that SQLit
10320 65 20 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f  e will use.** fo
10330 72 20 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e  r all of its dyn
10340 61 6d 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  amic memory allo
10350 63 61 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79  cation needs bey
10360 6f 6e 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64  ond those provid
10370 65 64 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51  ed.** for by [SQ
10380 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41  LITE_CONFIG_SCRA
10390 54 43 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  TCH] and [SQLITE
103a0 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48  _CONFIG_PAGECACH
103b0 45 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65  E]..** There are
103c0 20 74 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73   three arguments
103d0 3a 20 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67  : An 8-byte alig
103e0 6e 65 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74  ned pointer to t
103f0 68 65 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68  he memory,.** th
10400 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
10410 73 20 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20  s in the memory 
10420 62 75 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20  buffer, and the 
10430 6d 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69  minimum allocati
10440 6f 6e 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20  on size..** ^If 
10450 74 68 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65  the first pointe
10460 72 20 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f  r (the memory po
10470 69 6e 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20  inter) is NULL, 
10480 74 68 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65  then SQLite reve
10490 72 74 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20  rts.** to using 
104a0 69 74 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f  its default memo
104b0 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68  ry allocator (th
104c0 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
104d0 29 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  ) implementation
104e0 29 2c 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e  ),.** undoing an
104f0 79 20 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69  y prior invocati
10500 6f 6e 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f  on of [SQLITE_CO
10510 4e 46 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e  NFIG_MALLOC].  ^
10520 49 66 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79  If the.** memory
10530 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20   pointer is not 
10540 4e 55 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20  NULL and either 
10550 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
10560 45 4d 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53  EMSYS3] or.** [S
10570 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
10580 53 59 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65  SYS5] are define
10590 64 2c 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65  d, then the alte
105a0 72 6e 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a  rnative memory.*
105b0 2a 20 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65  * allocator is e
105c0 6e 67 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65  ngaged to handle
105d0 20 61 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20   all of SQLites 
105e0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
105f0 6e 20 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20  n needs..** The 
10600 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74  first pointer (t
10610 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65  he memory pointe
10620 72 29 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e  r) must be align
10630 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a  ed to an 8-byte.
10640 2a 2a 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73  ** boundary or s
10650 75 62 73 65 71 75 65 6e 74 20 62 65 68 61 76 69  ubsequent behavi
10660 6f 72 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c  or of SQLite wil
10670 6c 20 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a  l be undefined..
10680 2a 2a 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61  ** The minimum a
10690 6c 6c 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69  llocation size i
106a0 73 20 63 61 70 70 65 64 20 61 74 20 32 5e 31 32  s capped at 2^12
106b0 2e 20 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c  . Reasonable val
106c0 75 65 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d  ues.** for the m
106d0 69 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f  inimum allocatio
106e0 6e 20 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74  n size are 2^5 t
106f0 68 72 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e  hrough 2^8.</dd>
10700 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10710 43 4f 4e 46 49 47 5f 4d 55 54 45 58 5d 5d 20 3c  CONFIG_MUTEX]] <
10720 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
10730 5f 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  _MUTEX</dt>.** <
10740 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10750 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10760 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10770 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10780 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
10790 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
107a0 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
107b0 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 61 72  ructure.  The ar
107c0 67 75 6d 65 6e 74 20 73 70 65 63 69 66 69 65 73  gument specifies
107d0 0a 2a 2a 20 61 6c 74 65 72 6e 61 74 69 76 65 20  .** alternative 
107e0 6c 6f 77 2d 6c 65 76 65 6c 20 6d 75 74 65 78 20  low-level mutex 
107f0 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 75  routines to be u
10800 73 65 64 20 69 6e 20 70 6c 61 63 65 0a 2a 2a 20  sed in place.** 
10810 74 68 65 20 6d 75 74 65 78 20 72 6f 75 74 69 6e  the mutex routin
10820 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
10830 4c 69 74 65 2e 29 5e 20 20 5e 53 51 4c 69 74 65  Lite.)^  ^SQLite
10840 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
10850 20 74 68 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20   the.** content 
10860 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
10870 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73  mutex_methods] s
10880 74 72 75 63 74 75 72 65 20 62 65 66 6f 72 65 20  tructure before 
10890 74 68 65 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  the call to.** [
108a0 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
108b0 5d 20 72 65 74 75 72 6e 73 2e 20 5e 49 66 20 53  ] returns. ^If S
108c0 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65  QLite is compile
108d0 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53  d with.** the [S
108e0 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
108f0 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44   | SQLITE_THREAD
10900 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d  SAFE=0] compile-
10910 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e  time option then
10920 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d  .** the entire m
10930 75 74 65 78 69 6e 67 20 73 75 62 73 79 73 74 65  utexing subsyste
10940 6d 20 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f  m is omitted fro
10950 6d 20 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20  m the build and 
10960 68 65 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a  hence calls to.*
10970 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  * [sqlite3_confi
10980 67 28 29 5d 20 77 69 74 68 20 74 68 65 20 53 51  g()] with the SQ
10990 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 54 45  LITE_CONFIG_MUTE
109a0 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  X configuration 
109b0 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20 72  option will.** r
109c0 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
109d0 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ROR].</dd>.**.**
109e0 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47   [[SQLITE_CONFIG
109f0 5f 47 45 54 4d 55 54 45 58 5d 5d 20 3c 64 74 3e  _GETMUTEX]] <dt>
10a00 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
10a10 54 4d 55 54 45 58 3c 2f 64 74 3e 0a 2a 2a 20 3c  TMUTEX</dt>.** <
10a20 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10a30 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10a40 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10a50 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  is a pointer to 
10a60 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63 65 20 6f  an.** instance o
10a70 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d  f the [sqlite3_m
10a80 75 74 65 78 5f 6d 65 74 68 6f 64 73 5d 20 73 74  utex_methods] st
10a90 72 75 63 74 75 72 65 2e 20 20 54 68 65 0a 2a 2a  ructure.  The.**
10aa0 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10ab0 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 73 74 72 75  methods].** stru
10ac0 63 74 75 72 65 20 69 73 20 66 69 6c 6c 65 64 20  cture is filled 
10ad0 77 69 74 68 20 74 68 65 20 63 75 72 72 65 6e 74  with the current
10ae0 6c 79 20 64 65 66 69 6e 65 64 20 6d 75 74 65 78  ly defined mutex
10af0 20 72 6f 75 74 69 6e 65 73 2e 29 5e 0a 2a 2a 20   routines.)^.** 
10b00 54 68 69 73 20 6f 70 74 69 6f 6e 20 63 61 6e 20  This option can 
10b10 62 65 20 75 73 65 64 20 74 6f 20 6f 76 65 72 6c  be used to overl
10b20 6f 61 64 20 74 68 65 20 64 65 66 61 75 6c 74 20  oad the default 
10b30 6d 75 74 65 78 20 61 6c 6c 6f 63 61 74 69 6f 6e  mutex allocation
10b40 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 77 69 74  .** routines wit
10b50 68 20 61 20 77 72 61 70 70 65 72 20 75 73 65 64  h a wrapper used
10b60 20 74 6f 20 74 72 61 63 6b 20 6d 75 74 65 78 20   to track mutex 
10b70 75 73 61 67 65 20 66 6f 72 20 70 65 72 66 6f 72  usage for perfor
10b80 6d 61 6e 63 65 0a 2a 2a 20 70 72 6f 66 69 6c 69  mance.** profili
10b90 6e 67 20 6f 72 20 74 65 73 74 69 6e 67 2c 20 66  ng or testing, f
10ba0 6f 72 20 65 78 61 6d 70 6c 65 2e 20 20 20 5e 49  or example.   ^I
10bb0 66 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70  f SQLite is comp
10bc0 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65  iled with.** the
10bd0 20 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53   [SQLITE_THREADS
10be0 41 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52  AFE | SQLITE_THR
10bf0 45 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69  EADSAFE=0] compi
10c00 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74  le-time option t
10c10 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e 74 69 72  hen.** the entir
10c20 65 20 6d 75 74 65 78 69 6e 67 20 73 75 62 73 79  e mutexing subsy
10c30 73 74 65 6d 20 69 73 20 6f 6d 69 74 74 65 64 20  stem is omitted 
10c40 66 72 6f 6d 20 74 68 65 20 62 75 69 6c 64 20 61  from the build a
10c50 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c 73 20 74  nd hence calls t
10c60 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
10c70 6e 66 69 67 28 29 5d 20 77 69 74 68 20 74 68 65  nfig()] with the
10c80 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47   SQLITE_CONFIG_G
10c90 45 54 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  ETMUTEX configur
10ca0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
10cb0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
10cc0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
10cd0 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f  .**.** [[SQLITE_
10ce0 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45  CONFIG_LOOKASIDE
10cf0 5d 5d 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f  ]] <dt>SQLITE_CO
10d00 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f  NFIG_LOOKASIDE</
10d10 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68  dt>.** <dd> ^(Th
10d20 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
10d30 74 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68  two arguments th
10d40 61 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65  at determine the
10d50 20 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f   default.** memo
10d60 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f  ry allocation fo
10d70 72 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20  r the lookaside 
10d80 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72  memory allocator
10d90 20 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74   on each.** [dat
10da0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
10db0 5d 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72  ].  The first ar
10dc0 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
10dd0 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
10de0 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
10df0 6c 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f  lot and the seco
10e00 6e 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72  nd is the number
10e10 20 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c   of.** slots all
10e20 6f 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64  ocated to each d
10e30 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
10e40 6f 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70  on.)^  ^(This op
10e50 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
10e60 20 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20   <i>default</i> 
10e70 6c 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20  lookaside size. 
10e80 54 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f  The [SQLITE_DBCO
10e90 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a  NFIG_LOOKASIDE].
10ea0 2a 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69  ** verb to [sqli
10eb0 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d  te3_db_config()]
10ec0 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
10ed0 63 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61  change the looka
10ee0 73 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72  side.** configur
10ef0 61 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64  ation on individ
10f00 75 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e  ual connections.
10f10 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b  )^ </dd>.**.** [
10f20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50  [SQLITE_CONFIG_P
10f30 43 41 43 48 45 5d 5d 20 3c 64 74 3e 53 51 4c 49  CACHE]] <dt>SQLI
10f40 54 45 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45  TE_CONFIG_PCACHE
10f50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28  </dt>.** <dd> ^(
10f60 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65  This option take
10f70 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d  s a single argum
10f80 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20 70  ent which is a p
10f90 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20 61 6e 20  ointer to.** an 
10fa0 5b 73 71 6c 69 74 65 33 5f 70 63 61 63 68 65 5f  [sqlite3_pcache_
10fb0 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 2e  methods] object.
10fc0 20 20 54 68 69 73 20 6f 62 6a 65 63 74 20 73 70    This object sp
10fd0 65 63 69 66 69 65 73 20 74 68 65 20 69 6e 74 65  ecifies the inte
10fe0 72 66 61 63 65 0a 2a 2a 20 74 6f 20 61 20 63 75  rface.** to a cu
10ff0 73 74 6f 6d 20 70 61 67 65 20 63 61 63 68 65 20  stom page cache 
11000 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 29  implementation.)
11010 5e 20 20 5e 53 51 4c 69 74 65 20 6d 61 6b 65 73  ^  ^SQLite makes
11020 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a   a copy of the.*
11030 2a 20 6f 62 6a 65 63 74 20 61 6e 64 20 75 73 65  * object and use
11040 73 20 69 74 20 66 6f 72 20 70 61 67 65 20 63 61  s it for page ca
11050 63 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  che memory alloc
11060 61 74 69 6f 6e 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a  ations.</dd>.**.
11070 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ** [[SQLITE_CONF
11080 49 47 5f 47 45 54 50 43 41 43 48 45 5d 5d 20 3c  IG_GETPCACHE]] <
11090 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  dt>SQLITE_CONFIG
110a0 5f 47 45 54 50 43 41 43 48 45 3c 2f 64 74 3e 0a  _GETPCACHE</dt>.
110b0 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f  ** <dd> ^(This o
110c0 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69  ption takes a si
110d0 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68  ngle argument wh
110e0 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ich is a pointer
110f0 20 74 6f 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74   to an.** [sqlit
11100 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
11110 73 5d 20 6f 62 6a 65 63 74 2e 20 20 53 51 4c 69  s] object.  SQLi
11120 74 65 20 63 6f 70 69 65 73 20 6f 66 20 74 68 65  te copies of the
11130 20 63 75 72 72 65 6e 74 0a 2a 2a 20 70 61 67 65   current.** page
11140 20 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74   cache implement
11150 61 74 69 6f 6e 20 69 6e 74 6f 20 74 68 61 74 20  ation into that 
11160 6f 62 6a 65 63 74 2e 29 5e 20 3c 2f 64 64 3e 0a  object.)^ </dd>.
11170 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 43  **.** [[SQLITE_C
11180 4f 4e 46 49 47 5f 4c 4f 47 5d 5d 20 3c 64 74 3e  ONFIG_LOG]] <dt>
11190 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f  SQLITE_CONFIG_LO
111a0 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  G</dt>.** <dd> ^
111b0 54 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  The SQLITE_CONFI
111c0 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e 20 74 61 6b  G_LOG option tak
111d0 65 73 20 74 77 6f 20 61 72 67 75 6d 65 6e 74 73  es two arguments
111e0 3a 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61  : a pointer to a
111f0 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77 69 74  .** function wit
11200 68 20 61 20 63 61 6c 6c 20 73 69 67 6e 61 74 75  h a call signatu
11210 72 65 20 6f 66 20 76 6f 69 64 28 2a 29 28 76 6f  re of void(*)(vo
11220 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 63 68  id*,int,const ch
11230 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e 64 20 61 20  ar*), .** and a 
11240 70 6f 69 6e 74 65 72 20 74 6f 20 76 6f 69 64 2e  pointer to void.
11250 20 5e 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f   ^If the functio
11260 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
11270 20 4e 55 4c 4c 2c 20 69 74 20 69 73 0a 2a 2a 20   NULL, it is.** 
11280 69 6e 76 6f 6b 65 64 20 62 79 20 5b 73 71 6c 69  invoked by [sqli
11290 74 65 33 5f 6c 6f 67 28 29 5d 20 74 6f 20 70 72  te3_log()] to pr
112a0 6f 63 65 73 73 20 65 61 63 68 20 6c 6f 67 67 69  ocess each loggi
112b0 6e 67 20 65 76 65 6e 74 2e 20 20 5e 49 66 20 74  ng event.  ^If t
112c0 68 65 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  he.** function p
112d0 6f 69 6e 74 65 72 20 69 73 20 4e 55 4c 4c 2c 20  ointer is NULL, 
112e0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 67  the [sqlite3_log
112f0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 62 65  ()] interface be
11300 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f 70 2e 0a 2a  comes a no-op..*
11310 2a 20 5e 54 68 65 20 76 6f 69 64 20 70 6f 69 6e  * ^The void poin
11320 74 65 72 20 74 68 61 74 20 69 73 20 74 68 65 20  ter that is the 
11330 73 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20  second argument 
11340 74 6f 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47  to SQLITE_CONFIG
11350 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70 61 73 73 65  _LOG is.** passe
11360 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
11370 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72   first parameter
11380 20 74 6f 20 74 68 65 20 61 70 70 6c 69 63 61 74   to the applicat
11390 69 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67  ion-defined logg
113a0 65 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 77  er.** function w
113b0 68 65 6e 65 76 65 72 20 74 68 61 74 20 66 75 6e  henever that fun
113c0 63 74 69 6f 6e 20 69 73 20 69 6e 76 6f 6b 65 64  ction is invoked
113d0 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70  .  ^The second p
113e0 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a 20 74  arameter to.** t
113f0 68 65 20 6c 6f 67 67 65 72 20 66 75 6e 63 74 69  he logger functi
11400 6f 6e 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20  on is a copy of 
11410 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
11420 74 65 72 20 74 6f 20 74 68 65 20 63 6f 72 72 65  ter to the corre
11430 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20 5b 73 71 6c  sponding.** [sql
11440 69 74 65 33 5f 6c 6f 67 28 29 5d 20 63 61 6c 6c  ite3_log()] call
11450 20 61 6e 64 20 69 73 20 69 6e 74 65 6e 64 65 64   and is intended
11460 20 74 6f 20 62 65 20 61 20 5b 72 65 73 75 6c 74   to be a [result
11470 20 63 6f 64 65 5d 20 6f 72 20 61 6e 0a 2a 2a 20   code] or an.** 
11480 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
11490 20 63 6f 64 65 5d 2e 20 20 5e 54 68 65 20 74 68   code].  ^The th
114a0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 70 61  ird parameter pa
114b0 73 73 65 64 20 74 6f 20 74 68 65 20 6c 6f 67 67  ssed to the logg
114c0 65 72 20 69 73 0a 2a 2a 20 6c 6f 67 20 6d 65 73  er is.** log mes
114d0 73 61 67 65 20 61 66 74 65 72 20 66 6f 72 6d 61  sage after forma
114e0 74 74 69 6e 67 20 76 69 61 20 5b 73 71 6c 69 74  tting via [sqlit
114f0 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 5d 2e 0a  e3_snprintf()]..
11500 2a 2a 20 54 68 65 20 53 51 4c 69 74 65 20 6c 6f  ** The SQLite lo
11510 67 67 69 6e 67 20 69 6e 74 65 72 66 61 63 65 20  gging interface 
11520 69 73 20 6e 6f 74 20 72 65 65 6e 74 72 61 6e 74  is not reentrant
11530 3b 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75 6e  ; the logger fun
11540 63 74 69 6f 6e 0a 2a 2a 20 73 75 70 70 6c 69 65  ction.** supplie
11550 64 20 62 79 20 74 68 65 20 61 70 70 6c 69 63 61  d by the applica
11560 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 69 6e  tion must not in
11570 76 6f 6b 65 20 61 6e 79 20 53 51 4c 69 74 65 20  voke any SQLite 
11580 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 20 49 6e  interface..** In
11590 20 61 20 6d 75 6c 74 69 2d 74 68 72 65 61 64 65   a multi-threade
115a0 64 20 61 70 70 6c 69 63 61 74 69 6f 6e 2c 20 74  d application, t
115b0 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  he application-d
115c0 65 66 69 6e 65 64 20 6c 6f 67 67 65 72 0a 2a 2a  efined logger.**
115d0 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 62   function must b
115e0 65 20 74 68 72 65 61 64 73 61 66 65 2e 20 3c 2f  e threadsafe. </
115f0 64 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49  dd>.**.** [[SQLI
11600 54 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 5d 20  TE_CONFIG_URI]] 
11610 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
11620 47 5f 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68  G_URI.** <dd> Th
11630 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
11640 61 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e  a single argumen
11650 74 20 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49  t of type int. I
11660 66 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e  f non-zero, then
11670 0a 2a 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67  .** URI handling
11680 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61   is globally ena
11690 62 6c 65 64 2e 20 49 66 20 74 68 65 20 70 61 72  bled. If the par
116a0 61 6d 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20  ameter is zero, 
116b0 74 68 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e  then URI handlin
116c0 67 0a 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79  g.** is globally
116d0 20 64 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52   disabled. If UR
116e0 49 20 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c  I handling is gl
116f0 6f 62 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20  obally enabled, 
11700 61 6c 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a  all filenames.**
11710 20 70 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69   passed to [sqli
11720 74 65 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71  te3_open()], [sq
11730 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
11740 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31  , [sqlite3_open1
11750 36 28 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69  6()] or.** speci
11760 66 69 65 64 20 61 73 20 70 61 72 74 20 6f 66 20  fied as part of 
11770 5b 41 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64  [ATTACH] command
11780 73 20 61 72 65 20 69 6e 74 65 72 70 72 65 74 65  s are interprete
11790 64 20 61 73 20 55 52 49 73 2c 20 72 65 67 61 72  d as URIs, regar
117a0 64 6c 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74  dless.** of whet
117b0 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b  her or not the [
117c0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d  SQLITE_OPEN_URI]
117d0 20 66 6c 61 67 20 69 73 20 73 65 74 20 77 68 65   flag is set whe
117e0 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  n the database.*
117f0 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  * connection is 
11800 6f 70 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73  opened. If it is
11810 20 67 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c   globally disabl
11820 65 64 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72  ed, filenames ar
11830 65 0a 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70  e.** only interp
11840 72 65 74 65 64 20 61 73 20 55 52 49 73 20 69 66  reted as URIs if
11850 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e   the SQLITE_OPEN
11860 5f 55 52 49 20 66 6c 61 67 20 69 73 20 73 65 74  _URI flag is set
11870 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74   when the.** dat
11880 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
11890 20 69 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64   is opened. By d
118a0 65 66 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64  efault, URI hand
118b0 6c 69 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79  ling is globally
118c0 0a 2a 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68  .** disabled. Th
118d0 65 20 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20  e default value 
118e0 6d 61 79 20 62 65 20 63 68 61 6e 67 65 64 20 62  may be changed b
118f0 79 20 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68  y compiling with
11900 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
11910 55 53 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20  USE_URI] symbol 
11920 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 3c 2f 64 6c  defined..** </dl
11930 3e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  >.*/.#define SQL
11940 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c  ITE_CONFIG_SINGL
11950 45 54 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e  ETHREAD  1  /* n
11960 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
11970 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54  LITE_CONFIG_MULT
11980 49 54 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20  ITHREAD   2  /* 
11990 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  nil */.#define S
119a0 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52  QLITE_CONFIG_SER
119b0 49 41 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a  IALIZED    3  /*
119c0 20 6e 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20   nil */.#define 
119d0 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41  SQLITE_CONFIG_MA
119e0 4c 4c 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f  LLOC        4  /
119f0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
11a00 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
11a10 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
11a20 47 45 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20  GETMALLOC     5 
11a30 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f   /* sqlite3_mem_
11a40 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66  methods* */.#def
11a50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11a60 47 5f 53 43 52 41 54 43 48 20 20 20 20 20 20 20  G_SCRATCH       
11a70 36 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  6  /* void*, int
11a80 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
11a90 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11aa0 46 49 47 5f 50 41 47 45 43 41 43 48 45 20 20 20  FIG_PAGECACHE   
11ab0 20 20 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    7  /* void*, i
11ac0 6e 74 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a  nt sz, int N */.
11ad0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11ae0 4f 4e 46 49 47 5f 48 45 41 50 20 20 20 20 20 20  ONFIG_HEAP      
11af0 20 20 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c      8  /* void*,
11b00 20 69 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20   int nByte, int 
11b10 6d 69 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53  min */.#define S
11b20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d  QLITE_CONFIG_MEM
11b30 53 54 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a  STATUS     9  /*
11b40 20 62 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66   boolean */.#def
11b50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11b60 47 5f 4d 55 54 45 58 20 20 20 20 20 20 20 20 31  G_MUTEX        1
11b70 30 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75  0  /* sqlite3_mu
11b80 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a  tex_methods* */.
11b90 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11ba0 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20  ONFIG_GETMUTEX  
11bb0 20 20 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65     11  /* sqlite
11bc0 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a  3_mutex_methods*
11bd0 20 2a 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c   */./* previousl
11be0 79 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  y SQLITE_CONFIG_
11bf0 43 48 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68  CHUNKALLOC 12 wh
11c00 69 63 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65  ich is now unuse
11c10 64 2e 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53  d. */ .#define S
11c20 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
11c30 4b 41 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a  KASIDE    13  /*
11c40 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
11c50 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11c60 47 5f 50 43 41 43 48 45 20 20 20 20 20 20 20 31  G_PCACHE       1
11c70 34 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63  4  /* sqlite3_pc
11c80 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f  ache_methods* */
11c90 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
11ca0 43 4f 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45  CONFIG_GETPCACHE
11cb0 20 20 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74      15  /* sqlit
11cc0 65 33 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64  e3_pcache_method
11cd0 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  s* */.#define SQ
11ce0 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20  LITE_CONFIG_LOG 
11cf0 20 20 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20           16  /* 
11d00 78 46 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a  xFunc, void* */.
11d10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
11d20 4f 4e 46 49 47 5f 55 52 49 20 20 20 20 20 20 20  ONFIG_URI       
11d30 20 20 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f     17  /* int */
11d40 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
11d50 3a 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65  : Database Conne
11d60 63 74 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74  ction Configurat
11d70 69 6f 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a  ion Options.**.*
11d80 2a 20 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74  * These constant
11d90 73 20 61 72 65 20 74 68 65 20 61 76 61 69 6c 61  s are the availa
11da0 62 6c 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66  ble integer conf
11db0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
11dc0 73 20 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65  s that.** can be
11dd0 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20 73   passed as the s
11de0 65 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74  econd argument t
11df0 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64  o the [sqlite3_d
11e00 62 5f 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65  b_config()] inte
11e10 72 66 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77  rface..**.** New
11e20 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
11e30 70 74 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64  ptions may be ad
11e40 64 65 64 20 69 6e 20 66 75 74 75 72 65 20 72 65  ded in future re
11e50 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65  leases of SQLite
11e60 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f  ..** Existing co
11e70 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69  nfiguration opti
11e80 6f 6e 73 20 6d 69 67 68 74 20 62 65 20 64 69 73  ons might be dis
11e90 63 6f 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c  continued.  Appl
11ea0 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75  ications.** shou
11eb0 6c 64 20 63 68 65 63 6b 20 74 68 65 20 72 65 74  ld check the ret
11ec0 75 72 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73  urn code from [s
11ed0 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11ee0 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65  ()] to make sure
11ef0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c   that.** the cal
11f00 6c 20 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20  l worked.  ^The 
11f10 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66  [sqlite3_db_conf
11f20 69 67 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20  ig()] interface 
11f30 77 69 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a  will return a.**
11f40 20 6e 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72   non-zero [error
11f50 20 63 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63   code] if a disc
11f60 6f 6e 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75  ontinued or unsu
11f70 70 70 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72  pported configur
11f80 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20  ation option.** 
11f90 69 73 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a  is invoked..**.*
11fa0 2a 20 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51  * <dl>.** <dt>SQ
11fb0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f  LITE_DBCONFIG_LO
11fc0 4f 4b 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20  OKASIDE</dt>.** 
11fd0 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f  <dd> ^This optio
11fe0 6e 20 74 61 6b 65 73 20 74 68 72 65 65 20 61 64  n takes three ad
11ff0 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e  ditional argumen
12000 74 73 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e  ts that determin
12010 65 20 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61  e the .** [looka
12020 73 69 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  side memory allo
12030 63 61 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61  cator] configura
12040 74 69 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61  tion for the [da
12050 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
12060 6e 5d 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73  n]..** ^The firs
12070 74 20 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20  t argument (the 
12080 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
12090 74 6f 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63  to [sqlite3_db_c
120a0 6f 6e 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a  onfig()] is a.**
120b0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65   pointer to a me
120c0 6d 6f 72 79 20 62 75 66 66 65 72 20 74 6f 20 75  mory buffer to u
120d0 73 65 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65  se for lookaside
120e0 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65   memory..** ^The
120f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
12100 61 66 74 65 72 20 74 68 65 20 53 51 4c 49 54 45  after the SQLITE
12110 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53  _DBCONFIG_LOOKAS
12120 49 44 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20  IDE verb.** may 
12130 62 65 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68  be NULL in which
12140 20 63 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c   case SQLite wil
12150 6c 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a  l allocate the.*
12160 2a 20 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66  * lookaside buff
12170 65 72 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20  er itself using 
12180 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
12190 29 5d 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20  )]. ^The second 
121a0 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a  argument is the.
121b0 2a 2a 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20  ** size of each 
121c0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
121d0 20 73 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69   slot.  ^The thi
121e0 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  rd argument is t
121f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20  he number of.** 
12200 73 6c 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65  slots.  The size
12210 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 20 69   of the buffer i
12220 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
12230 6d 65 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65  ment must be gre
12240 61 74 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20  ater than.** or 
12250 65 71 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f  equal to the pro
12260 64 75 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f  duct of the seco
12270 6e 64 20 61 6e 64 20 74 68 69 72 64 20 61 72 67  nd and third arg
12280 75 6d 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66  uments.  The buf
12290 66 65 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61  fer.** must be a
122a0 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62  ligned to an 8-b
122b0 79 74 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e  yte boundary.  ^
122c0 49 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  If the second ar
122d0 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c  gument to.** SQL
122e0 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f  ITE_DBCONFIG_LOO
122f0 4b 41 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20  KASIDE is not a 
12300 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69  multiple of 8, i
12310 74 20 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a  t is internally.
12320 2a 2a 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20  ** rounded down 
12330 74 6f 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c  to the next smal
12340 6c 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20  ler multiple of 
12350 38 2e 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73  8.  ^(The lookas
12360 69 64 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f  ide memory.** co
12370 6e 66 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20  nfiguration for 
12380 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  a database conne
12390 63 74 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62  ction can only b
123a0 65 20 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74  e changed when t
123b0 68 61 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f  hat.** connectio
123c0 6e 20 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74  n is not current
123d0 6c 79 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69  ly using lookasi
123e0 64 65 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e  de memory, or in
123f0 20 6f 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20   other words.** 
12400 77 68 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e  when the "curren
12410 74 20 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65  t value" returne
12420 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  d by.** [sqlite3
12430 5f 64 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53  _db_status](D,[S
12440 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f  QLITE_CONFIG_LOO
12450 4b 41 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20  KASIDE],...) is 
12460 7a 65 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74  zero..** Any att
12470 65 6d 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74  empt to change t
12480 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d  he lookaside mem
12490 6f 72 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ory configuratio
124a0 6e 20 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65  n when lookaside
124b0 0a 2a 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e  .** memory is in
124c0 20 75 73 65 20 6c 65 61 76 65 73 20 74 68 65 20   use leaves the 
124d0 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e  configuration un
124e0 63 68 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75  changed and retu
124f0 72 6e 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  rns .** [SQLITE_
12500 42 55 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a  BUSY].)^</dd>.**
12510 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44  .** <dt>SQLITE_D
12520 42 43 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46  BCONFIG_ENABLE_F
12530 4b 45 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  KEY</dt>.** <dd>
12540 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73   ^This option is
12550 20 75 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20   used to enable 
12560 6f 72 20 64 69 73 61 62 6c 65 20 74 68 65 20 65  or disable the e
12570 6e 66 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a  nforcement of.**
12580 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f   [foreign key co
12590 6e 73 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65  nstraints].  The
125a0 72 65 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f  re should be two
125b0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75   additional argu
125c0 6d 65 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69  ments..** The fi
125d0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
125e0 61 6e 20 69 6e 74 65 67 65 72 20 77 68 69 63 68  an integer which
125f0 20 69 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65   is 0 to disable
12600 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c   FK enforcement,
12610 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20  .** positive to 
12620 65 6e 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63  enable FK enforc
12630 65 6d 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76  ement or negativ
12640 65 20 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e  e to leave FK en
12650 66 6f 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63  forcement.** unc
12660 68 61 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63  hanged.  The sec
12670 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73  ond parameter is
12680 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
12690 20 69 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68   integer into wh
126a0 69 63 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65  ich.** is writte
126b0 6e 20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69  n 0 or 1 to indi
126c0 63 61 74 65 20 77 68 65 74 68 65 72 20 46 4b 20  cate whether FK 
126d0 65 6e 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f  enforcement is o
126e0 66 66 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c  ff or on.** foll
126f0 6f 77 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e  owing this call.
12700 20 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72    The second par
12710 61 6d 65 74 65 72 20 6d 61 79 20 62 65 20 61 20  ameter may be a 
12720 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e  NULL pointer, in
12730 0a 2a 2a 20 77 68 69 63 68 20 63 61 73 65 20 74  .** which case t
12740 68 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e  he FK enforcemen
12750 74 20 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74  t setting is not
12760 20 72 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20   reported back. 
12770 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e  </dd>.**.** <dt>
12780 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
12790 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f  ENABLE_TRIGGER</
127a0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69  dt>.** <dd> ^Thi
127b0 73 20 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64  s option is used
127c0 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69   to enable or di
127d0 73 61 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52  sable [CREATE TR
127e0 49 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 73  IGGER | triggers
127f0 5d 2e 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75  ]..** There shou
12800 6c 64 20 62 65 20 74 77 6f 20 61 64 64 69 74 69  ld be two additi
12810 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a  onal arguments..
12820 2a 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67  ** The first arg
12830 75 6d 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65  ument is an inte
12840 67 65 72 20 77 68 69 63 68 20 69 73 20 30 20 74  ger which is 0 t
12850 6f 20 64 69 73 61 62 6c 65 20 74 72 69 67 67 65  o disable trigge
12860 72 73 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20  rs,.** positive 
12870 74 6f 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65  to enable trigge
12880 72 73 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74  rs or negative t
12890 6f 20 6c 65 61 76 65 20 74 68 65 20 73 65 74 74  o leave the sett
128a0 69 6e 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a  ing unchanged..*
128b0 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72  * The second par
128c0 61 6d 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e  ameter is a poin
128d0 74 65 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65  ter to an intege
128e0 72 20 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20  r into which.** 
128f0 69 73 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20  is written 0 or 
12900 31 20 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68  1 to indicate wh
12910 65 74 68 65 72 20 74 72 69 67 67 65 72 73 20 61  ether triggers a
12920 72 65 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65  re disabled or e
12930 6e 61 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77  nabled.** follow
12940 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
12950 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12960 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
12970 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
12980 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
12990 20 74 72 69 67 67 65 72 20 73 65 74 74 69 6e 67   trigger setting
129a0 20 69 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64   is not reported
129b0 20 62 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a   back. </dd>.**.
129c0 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66  ** </dl>.*/.#def
129d0 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
129e0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20  FIG_LOOKASIDE   
129f0 20 20 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69      1001  /* voi
12a00 64 2a 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64  d* int int */.#d
12a10 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43  efine SQLITE_DBC
12a20 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
12a30 59 20 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69  Y     1002  /* i
12a40 6e 74 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69  nt int* */.#defi
12a50 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46  ne SQLITE_DBCONF
12a60 49 47 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45  IG_ENABLE_TRIGGE
12a70 52 20 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20  R  1003  /* int 
12a80 69 6e 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20  int* */.../*.** 
12a90 43 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65  CAPI3REF: Enable
12aa0 20 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65   Or Disable Exte
12ab0 6e 64 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65  nded Result Code
12ac0 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
12ad0 69 74 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65  ite3_extended_re
12ae0 73 75 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75  sult_codes() rou
12af0 74 69 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20  tine enables or 
12b00 64 69 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20  disables the.** 
12b10 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
12b20 20 63 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20   codes] feature 
12b30 6f 66 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20  of SQLite. ^The 
12b40 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a  extended result.
12b50 2a 2a 20 63 6f 64 65 73 20 61 72 65 20 64 69 73  ** codes are dis
12b60 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
12b70 20 66 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20   for historical 
12b80 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
12b90 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  /.int sqlite3_ex
12ba0 74 65 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f  tended_result_co
12bb0 64 65 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e  des(sqlite3*, in
12bc0 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
12bd0 20 43 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20   CAPI3REF: Last 
12be0 49 6e 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a  Insert Rowid.**.
12bf0 2a 2a 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69  ** ^Each entry i
12c00 6e 20 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c  n an SQLite tabl
12c10 65 20 68 61 73 20 61 20 75 6e 69 71 75 65 20 36  e has a unique 6
12c20 34 2d 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20  4-bit signed.** 
12c30 69 6e 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c  integer key call
12c40 65 64 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20  ed the [ROWID | 
12c50 22 72 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72  "rowid"]. ^The r
12c60 6f 77 69 64 20 69 73 20 61 6c 77 61 79 73 20 61  owid is always a
12c70 76 61 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61  vailable.** as a
12c80 6e 20 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c  n undeclared col
12c90 75 6d 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c  umn named ROWID,
12ca0 20 4f 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f   OID, or _ROWID_
12cb0 20 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73   as long as thos
12cc0 65 0a 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e  e.** names are n
12cd0 6f 74 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20  ot also used by 
12ce0 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61  explicitly decla
12cf0 72 65 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66  red columns. ^If
12d00 0a 2a 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61  .** the table ha
12d10 73 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79  s a column of ty
12d20 70 65 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d  pe [INTEGER PRIM
12d30 41 52 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68  ARY KEY] then th
12d40 61 74 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20  at column.** is 
12d50 61 6e 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f  another alias fo
12d60 72 20 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a  r the rowid..**.
12d70 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65  ** ^This routine
12d80 20 72 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f   returns the [ro
12d90 77 69 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74  wid] of the most
12da0 20 72 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65   recent.** succe
12db0 73 73 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69  ssful [INSERT] i
12dc0 6e 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65  nto the database
12dd0 20 66 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62   from the [datab
12de0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a  ase connection].
12df0 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ** in the first 
12e00 61 72 67 75 6d 65 6e 74 2e 20 20 5e 41 73 20 6f  argument.  ^As o
12e10 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
12e20 20 33 2e 37 2e 37 2c 20 74 68 69 73 20 72 6f 75   3.7.7, this rou
12e30 74 69 6e 65 73 0a 2a 2a 20 72 65 63 6f 72 64 73  tines.** records
12e40 20 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74   the last insert
12e50 20 72 6f 77 69 64 20 6f 66 20 62 6f 74 68 20 6f   rowid of both o
12e60 72 64 69 6e 61 72 79 20 74 61 62 6c 65 73 20 61  rdinary tables a
12e70 6e 64 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  nd [virtual tabl
12e80 65 73 5d 2e 0a 2a 2a 20 5e 49 66 20 6e 6f 20 73  es]..** ^If no s
12e90 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52  uccessful [INSER
12ea0 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65 72  T]s.** have ever
12eb0 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68 61   occurred on tha
12ec0 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  t database conne
12ed0 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20 72  ction, zero is r
12ee0 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
12ef0 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20  (If an [INSERT] 
12f00 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61 20  occurs within a 
12f10 74 72 69 67 67 65 72 20 6f 72 20 77 69 74 68 69  trigger or withi
12f20 6e 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62  n a [virtual tab
12f30 6c 65 5d 0a 2a 2a 20 6d 65 74 68 6f 64 2c 20 74  le].** method, t
12f40 68 65 6e 20 74 68 69 73 20 72 6f 75 74 69 6e 65  hen this routine
12f50 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 74 68 65   will return the
12f60 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68 65 20   [rowid] of the 
12f70 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f 77 20  inserted.** row 
12f80 61 73 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74  as long as the t
12f90 72 69 67 67 65 72 20 6f 72 20 76 69 72 74 75 61  rigger or virtua
12fa0 6c 20 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 69  l table method i
12fb0 73 20 72 75 6e 6e 69 6e 67 2e 0a 2a 2a 20 42 75  s running..** Bu
12fc0 74 20 6f 6e 63 65 20 74 68 65 20 74 72 69 67 67  t once the trigg
12fd0 65 72 20 6f 72 20 76 69 72 74 75 61 6c 20 74 61  er or virtual ta
12fe0 62 6c 65 20 6d 65 74 68 6f 64 20 65 6e 64 73 2c  ble method ends,
12ff0 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
13000 6e 65 64 20 0a 2a 2a 20 62 79 20 74 68 69 73 20  ned .** by this 
13010 72 6f 75 74 69 6e 65 20 72 65 76 65 72 74 73 20  routine reverts 
13020 74 6f 20 77 68 61 74 20 69 74 20 77 61 73 20 62  to what it was b
13030 65 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65  efore the trigge
13040 72 20 6f 72 20 76 69 72 74 75 61 6c 0a 2a 2a 20  r or virtual.** 
13050 74 61 62 6c 65 20 6d 65 74 68 6f 64 20 62 65 67  table method beg
13060 61 6e 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20  an.)^.**.** ^An 
13070 5b 49 4e 53 45 52 54 5d 20 74 68 61 74 20 66 61  [INSERT] that fa
13080 69 6c 73 20 64 75 65 20 74 6f 20 61 20 63 6f 6e  ils due to a con
13090 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69 6f  straint violatio
130a0 6e 20 69 73 20 6e 6f 74 20 61 0a 2a 2a 20 73 75  n is not a.** su
130b0 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45 52 54  ccessful [INSERT
130c0 5d 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 63  ] and does not c
130d0 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65 20  hange the value 
130e0 72 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73  returned by this
130f0 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e 20 20 5e 54  .** routine.  ^T
13100 68 75 73 20 49 4e 53 45 52 54 20 4f 52 20 46 41  hus INSERT OR FA
13110 49 4c 2c 20 49 4e 53 45 52 54 20 4f 52 20 49 47  IL, INSERT OR IG
13120 4e 4f 52 45 2c 20 49 4e 53 45 52 54 20 4f 52 20  NORE, INSERT OR 
13130 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a 20 61 6e 64  ROLLBACK,.** and
13140 20 49 4e 53 45 52 54 20 4f 52 20 41 42 4f 52 54   INSERT OR ABORT
13150 20 6d 61 6b 65 20 6e 6f 20 63 68 61 6e 67 65 73   make no changes
13160 20 74 6f 20 74 68 65 20 72 65 74 75 72 6e 20 76   to the return v
13170 61 6c 75 65 20 6f 66 20 74 68 69 73 0a 2a 2a 20  alue of this.** 
13180 72 6f 75 74 69 6e 65 20 77 68 65 6e 20 74 68 65  routine when the
13190 69 72 20 69 6e 73 65 72 74 69 6f 6e 20 66 61 69  ir insertion fai
131a0 6c 73 2e 20 20 5e 28 57 68 65 6e 20 49 4e 53 45  ls.  ^(When INSE
131b0 52 54 20 4f 52 20 52 45 50 4c 41 43 45 0a 2a 2a  RT OR REPLACE.**
131c0 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 20 63 6f   encounters a co
131d0 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c 61 74 69  nstraint violati
131e0 6f 6e 2c 20 69 74 20 64 6f 65 73 20 6e 6f 74 20  on, it does not 
131f0 66 61 69 6c 2e 20 20 54 68 65 0a 2a 2a 20 49 4e  fail.  The.** IN
13200 53 45 52 54 20 63 6f 6e 74 69 6e 75 65 73 20 74  SERT continues t
13210 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e 20 61 66 74  o completion aft
13220 65 72 20 64 65 6c 65 74 69 6e 67 20 72 6f 77 73  er deleting rows
13230 20 74 68 61 74 20 63 61 75 73 65 64 0a 2a 2a 20   that caused.** 
13240 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74 20 70  the constraint p
13250 72 6f 62 6c 65 6d 20 73 6f 20 49 4e 53 45 52 54  roblem so INSERT
13260 20 4f 52 20 52 45 50 4c 41 43 45 20 77 69 6c 6c   OR REPLACE will
13270 20 61 6c 77 61 79 73 20 63 68 61 6e 67 65 0a 2a   always change.*
13280 2a 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  * the return val
13290 75 65 20 6f 66 20 74 68 69 73 20 69 6e 74 65 72  ue of this inter
132a0 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 46  face.)^.**.** ^F
132b0 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73 20  or the purposes 
132c0 6f 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c  of this routine,
132d0 20 61 6e 20 5b 49 4e 53 45 52 54 5d 20 69 73 20   an [INSERT] is 
132e0 63 6f 6e 73 69 64 65 72 65 64 20 74 6f 0a 2a 2a  considered to.**
132f0 20 62 65 20 73 75 63 63 65 73 73 66 75 6c 20 65   be successful e
13300 76 65 6e 20 69 66 20 69 74 20 69 73 20 73 75 62  ven if it is sub
13310 73 65 71 75 65 6e 74 6c 79 20 72 6f 6c 6c 65 64  sequently rolled
13320 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 54 68 69   back..**.** Thi
13330 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 61 63  s function is ac
13340 63 65 73 73 69 62 6c 65 20 74 6f 20 53 51 4c 20  cessible to SQL 
13350 73 74 61 74 65 6d 65 6e 74 73 20 76 69 61 20 74  statements via t
13360 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f 69 6e 73 65  he.** [last_inse
13370 72 74 5f 72 6f 77 69 64 28 29 20 53 51 4c 20 66  rt_rowid() SQL f
13380 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20  unction]..**.** 
13390 49 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68  If a separate th
133a0 72 65 61 64 20 70 65 72 66 6f 72 6d 73 20 61 20  read performs a 
133b0 6e 65 77 20 5b 49 4e 53 45 52 54 5d 20 6f 6e 20  new [INSERT] on 
133c0 74 68 65 20 73 61 6d 65 0a 2a 2a 20 64 61 74 61  the same.** data
133d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
133e0 77 68 69 6c 65 20 74 68 65 20 5b 73 71 6c 69 74  while the [sqlit
133f0 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72  e3_last_insert_r
13400 6f 77 69 64 28 29 5d 0a 2a 2a 20 66 75 6e 63 74  owid()].** funct
13410 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 20 61  ion is running a
13420 6e 64 20 74 68 75 73 20 63 68 61 6e 67 65 73 20  nd thus changes 
13430 74 68 65 20 6c 61 73 74 20 69 6e 73 65 72 74 20  the last insert 
13440 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20 74 68 65 6e  [rowid],.** then
13450 20 74 68 65 20 76 61 6c 75 65 20 72 65 74 75 72   the value retur
13460 6e 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  ned by [sqlite3_
13470 6c 61 73 74 5f 69 6e 73 65 72 74 5f 72 6f 77 69  last_insert_rowi
13480 64 28 29 5d 20 69 73 0a 2a 2a 20 75 6e 70 72 65  d()] is.** unpre
13490 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6d 69 67  dictable and mig
134a0 68 74 20 6e 6f 74 20 65 71 75 61 6c 20 65 69 74  ht not equal eit
134b0 68 65 72 20 74 68 65 20 6f 6c 64 20 6f 72 20 74  her the old or t
134c0 68 65 20 6e 65 77 0a 2a 2a 20 6c 61 73 74 20 69  he new.** last i
134d0 6e 73 65 72 74 20 5b 72 6f 77 69 64 5d 2e 0a 2a  nsert [rowid]..*
134e0 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  /.sqlite3_int64 
134f0 73 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73  sqlite3_last_ins
13500 65 72 74 5f 72 6f 77 69 64 28 73 71 6c 69 74 65  ert_rowid(sqlite
13510 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  3*);../*.** CAPI
13520 33 52 45 46 3a 20 43 6f 75 6e 74 20 54 68 65 20  3REF: Count The 
13530 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d  Number Of Rows M
13540 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54  odified.**.** ^T
13550 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74  his function ret
13560 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
13570 6f 66 20 64 61 74 61 62 61 73 65 20 72 6f 77 73  of database rows
13580 20 74 68 61 74 20 77 65 72 65 20 63 68 61 6e 67   that were chang
13590 65 64 0a 2a 2a 20 6f 72 20 69 6e 73 65 72 74 65  ed.** or inserte
135a0 64 20 6f 72 20 64 65 6c 65 74 65 64 20 62 79 20  d or deleted by 
135b0 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
135c0 79 20 63 6f 6d 70 6c 65 74 65 64 20 53 51 4c 20  y completed SQL 
135d0 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 6f 6e 20  statement.** on 
135e0 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  the [database co
135f0 6e 6e 65 63 74 69 6f 6e 5d 20 73 70 65 63 69 66  nnection] specif
13600 69 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  ied by the first
13610 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
13620 28 4f 6e 6c 79 20 63 68 61 6e 67 65 73 20 74 68  (Only changes th
13630 61 74 20 61 72 65 20 64 69 72 65 63 74 6c 79 20  at are directly 
13640 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
13650 20 5b 49 4e 53 45 52 54 5d 2c 20 5b 55 50 44 41   [INSERT], [UPDA
13660 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b 44 45 4c 45  TE],.** or [DELE
13670 54 45 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 72  TE] statement ar
13680 65 20 63 6f 75 6e 74 65 64 2e 20 20 41 75 78 69  e counted.  Auxi
13690 6c 69 61 72 79 20 63 68 61 6e 67 65 73 20 63 61  liary changes ca
136a0 75 73 65 64 20 62 79 0a 2a 2a 20 74 72 69 67 67  used by.** trigg
136b0 65 72 73 20 6f 72 20 5b 66 6f 72 65 69 67 6e 20  ers or [foreign 
136c0 6b 65 79 20 61 63 74 69 6f 6e 73 5d 20 61 72 65  key actions] are
136d0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 29 5e 20   not counted.)^ 
136e0 55 73 65 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69  Use the.** [sqli
136f0 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
13700 73 28 29 5d 20 66 75 6e 63 74 69 6f 6e 20 74 6f  s()] function to
13710 20 66 69 6e 64 20 74 68 65 20 74 6f 74 61 6c 20   find the total 
13720 6e 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65  number of change
13730 73 0a 2a 2a 20 69 6e 63 6c 75 64 69 6e 67 20 63  s.** including c
13740 68 61 6e 67 65 73 20 63 61 75 73 65 64 20 62 79  hanges caused by
13750 20 74 72 69 67 67 65 72 73 20 61 6e 64 20 66 6f   triggers and fo
13760 72 65 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e  reign key action
13770 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68 61 6e 67 65  s..**.** ^Change
13780 73 20 74 6f 20 61 20 76 69 65 77 20 74 68 61 74  s to a view that
13790 20 61 72 65 20 73 69 6d 75 6c 61 74 65 64 20 62   are simulated b
137a0 79 20 61 6e 20 5b 49 4e 53 54 45 41 44 20 4f 46  y an [INSTEAD OF
137b0 20 74 72 69 67 67 65 72 5d 0a 2a 2a 20 61 72 65   trigger].** are
137c0 20 6e 6f 74 20 63 6f 75 6e 74 65 64 2e 20 20 4f   not counted.  O
137d0 6e 6c 79 20 72 65 61 6c 20 74 61 62 6c 65 20 63  nly real table c
137e0 68 61 6e 67 65 73 20 61 72 65 20 63 6f 75 6e 74  hanges are count
137f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 41 20 22 72  ed..**.** ^(A "r
13800 6f 77 20 63 68 61 6e 67 65 22 20 69 73 20 61 20  ow change" is a 
13810 63 68 61 6e 67 65 20 74 6f 20 61 20 73 69 6e 67  change to a sing
13820 6c 65 20 72 6f 77 20 6f 66 20 61 20 73 69 6e 67  le row of a sing
13830 6c 65 20 74 61 62 6c 65 0a 2a 2a 20 63 61 75 73  le table.** caus
13840 65 64 20 62 79 20 61 6e 20 49 4e 53 45 52 54 2c  ed by an INSERT,
13850 20 44 45 4c 45 54 45 2c 20 6f 72 20 55 50 44 41   DELETE, or UPDA
13860 54 45 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 52  TE statement.  R
13870 6f 77 73 20 74 68 61 74 0a 2a 2a 20 61 72 65 20  ows that.** are 
13880 63 68 61 6e 67 65 64 20 61 73 20 73 69 64 65 20  changed as side 
13890 65 66 66 65 63 74 73 20 6f 66 20 5b 52 45 50 4c  effects of [REPL
138a0 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74 20  ACE] constraint 
138b0 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a 2a 2a 20 72  resolution,.** r
138c0 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f 52 54 20 70  ollback, ABORT p
138d0 72 6f 63 65 73 73 69 6e 67 2c 20 5b 44 52 4f 50  rocessing, [DROP
138e0 20 54 41 42 4c 45 5d 2c 20 6f 72 20 62 79 20 61   TABLE], or by a
138f0 6e 79 20 6f 74 68 65 72 0a 2a 2a 20 6d 65 63 68  ny other.** mech
13900 61 6e 69 73 6d 73 20 64 6f 20 6e 6f 74 20 63 6f  anisms do not co
13910 75 6e 74 20 61 73 20 64 69 72 65 63 74 20 72 6f  unt as direct ro
13920 77 20 63 68 61 6e 67 65 73 2e 29 5e 0a 2a 2a 0a  w changes.)^.**.
13930 2a 2a 20 41 20 22 74 72 69 67 67 65 72 20 63 6f  ** A "trigger co
13940 6e 74 65 78 74 22 20 69 73 20 61 20 73 63 6f 70  ntext" is a scop
13950 65 20 6f 66 20 65 78 65 63 75 74 69 6f 6e 20 74  e of execution t
13960 68 61 74 20 62 65 67 69 6e 73 20 61 6e 64 0a 2a  hat begins and.*
13970 2a 20 65 6e 64 73 20 77 69 74 68 20 74 68 65 20  * ends with the 
13980 73 63 72 69 70 74 20 6f 66 20 61 20 5b 43 52 45  script of a [CRE
13990 41 54 45 20 54 52 49 47 47 45 52 20 7c 20 74 72  ATE TRIGGER | tr
139a0 69 67 67 65 72 5d 2e 20 0a 2a 2a 20 4d 6f 73 74  igger]. .** Most
139b0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
139c0 61 72 65 0a 2a 2a 20 65 76 61 6c 75 61 74 65 64  are.** evaluated
139d0 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e 79 20   outside of any 
139e0 74 72 69 67 67 65 72 2e 20 20 54 68 69 73 20 69  trigger.  This i
139f0 73 20 74 68 65 20 22 74 6f 70 20 6c 65 76 65 6c  s the "top level
13a00 22 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e  ".** trigger con
13a10 74 65 78 74 2e 20 20 49 66 20 61 20 74 72 69 67  text.  If a trig
13a20 67 65 72 20 66 69 72 65 73 20 66 72 6f 6d 20 74  ger fires from t
13a30 68 65 20 74 6f 70 20 6c 65 76 65 6c 2c 20 61 0a  he top level, a.
13a40 2a 2a 20 6e 65 77 20 74 72 69 67 67 65 72 20 63  ** new trigger c
13a50 6f 6e 74 65 78 74 20 69 73 20 65 6e 74 65 72 65  ontext is entere
13a60 64 20 66 6f 72 20 74 68 65 20 64 75 72 61 74 69  d for the durati
13a70 6f 6e 20 6f 66 20 74 68 61 74 20 6f 6e 65 0a 2a  on of that one.*
13a80 2a 20 74 72 69 67 67 65 72 2e 20 20 53 75 62 74  * trigger.  Subt
13a90 72 69 67 67 65 72 73 20 63 72 65 61 74 65 20 73  riggers create s
13aa0 75 62 63 6f 6e 74 65 78 74 73 20 66 6f 72 20 74  ubcontexts for t
13ab0 68 65 69 72 20 64 75 72 61 74 69 6f 6e 2e 0a 2a  heir duration..*
13ac0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 5b 73  *.** ^Calling [s
13ad0 71 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 20 6f  qlite3_exec()] o
13ae0 72 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  r [sqlite3_step(
13af0 29 5d 20 72 65 63 75 72 73 69 76 65 6c 79 20 64  )] recursively d
13b00 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63 72 65 61 74  oes.** not creat
13b10 65 20 61 20 6e 65 77 20 74 72 69 67 67 65 72 20  e a new trigger 
13b20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
13b30 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65  This function re
13b40 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
13b50 20 6f 66 20 64 69 72 65 63 74 20 72 6f 77 20 63   of direct row c
13b60 68 61 6e 67 65 73 20 69 6e 20 74 68 65 0a 2a 2a  hanges in the.**
13b70 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 49 4e 53   most recent INS
13b80 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20  ERT, UPDATE, or 
13b90 44 45 4c 45 54 45 20 73 74 61 74 65 6d 65 6e 74  DELETE statement
13ba0 20 77 69 74 68 69 6e 20 74 68 65 20 73 61 6d 65   within the same
13bb0 0a 2a 2a 20 74 72 69 67 67 65 72 20 63 6f 6e 74  .** trigger cont
13bc0 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 75 73  ext..**.** ^Thus
13bd0 2c 20 77 68 65 6e 20 63 61 6c 6c 65 64 20 66 72  , when called fr
13be0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
13bf0 2c 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 20  , this function 
13c00 72 65 74 75 72 6e 73 20 74 68 65 0a 2a 2a 20 6e  returns the.** n
13c10 75 6d 62 65 72 20 6f 66 20 63 68 61 6e 67 65 73  umber of changes
13c20 20 69 6e 20 74 68 65 20 6d 6f 73 74 20 72 65 63   in the most rec
13c30 65 6e 74 20 49 4e 53 45 52 54 2c 20 55 50 44 41  ent INSERT, UPDA
13c40 54 45 2c 20 6f 72 20 44 45 4c 45 54 45 0a 2a 2a  TE, or DELETE.**
13c50 20 74 68 61 74 20 61 6c 73 6f 20 6f 63 63 75 72   that also occur
13c60 72 65 64 20 61 74 20 74 68 65 20 74 6f 70 20 6c  red at the top l
13c70 65 76 65 6c 2e 20 20 5e 28 57 69 74 68 69 6e 20  evel.  ^(Within 
13c80 74 68 65 20 62 6f 64 79 20 6f 66 20 61 20 74 72  the body of a tr
13c90 69 67 67 65 72 2c 0a 2a 2a 20 74 68 65 20 73 71  igger,.** the sq
13ca0 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29 20  lite3_changes() 
13cb0 69 6e 74 65 72 66 61 63 65 20 63 61 6e 20 62 65  interface can be
13cc0 20 63 61 6c 6c 65 64 20 74 6f 20 66 69 6e 64 20   called to find 
13cd0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a  the number of.**
13ce0 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68 65 20   changes in the 
13cf0 6d 6f 73 74 20 72 65 63 65 6e 74 6c 79 20 63 6f  most recently co
13d00 6d 70 6c 65 74 65 64 20 49 4e 53 45 52 54 2c 20  mpleted INSERT, 
13d10 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
13d20 45 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 77  E.** statement w
13d30 69 74 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f  ithin the body o
13d40 66 20 74 68 65 20 73 61 6d 65 20 74 72 69 67 67  f the same trigg
13d50 65 72 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20  er..** However, 
13d60 74 68 65 20 6e 75 6d 62 65 72 20 72 65 74 75 72  the number retur
13d70 6e 65 64 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  ned does not inc
13d80 6c 75 64 65 20 63 68 61 6e 67 65 73 0a 2a 2a 20  lude changes.** 
13d90 63 61 75 73 65 64 20 62 79 20 73 75 62 74 72 69  caused by subtri
13da0 67 67 65 72 73 20 73 69 6e 63 65 20 74 68 6f 73  ggers since thos
13db0 65 20 68 61 76 65 20 74 68 65 69 72 20 6f 77 6e  e have their own
13dc0 20 63 6f 6e 74 65 78 74 2e 29 5e 0a 2a 2a 0a 2a   context.)^.**.*
13dd0 2a 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b  * See also the [
13de0 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
13df0 61 6e 67 65 73 28 29 5d 20 69 6e 74 65 72 66 61  anges()] interfa
13e00 63 65 2c 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e  ce, the.** [coun
13e10 74 5f 63 68 61 6e 67 65 73 20 70 72 61 67 6d 61  t_changes pragma
13e20 5d 2c 20 61 6e 64 20 74 68 65 20 5b 63 68 61 6e  ], and the [chan
13e30 67 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69  ges() SQL functi
13e40 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20  on]..**.** If a 
13e50 73 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20  separate thread 
13e60 6d 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e  makes changes on
13e70 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
13e80 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a  se connection.**
13e90 20 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f   while [sqlite3_
13ea0 63 68 61 6e 67 65 73 28 29 5d 20 69 73 20 72 75  changes()] is ru
13eb0 6e 6e 69 6e 67 20 74 68 65 6e 20 74 68 65 20 76  nning then the v
13ec0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a  alue returned.**
13ed0 20 69 73 20 75 6e 70 72 65 64 69 63 74 61 62 6c   is unpredictabl
13ee0 65 20 61 6e 64 20 6e 6f 74 20 6d 65 61 6e 69 6e  e and not meanin
13ef0 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  gful..*/.int sql
13f00 69 74 65 33 5f 63 68 61 6e 67 65 73 28 73 71 6c  ite3_changes(sql
13f10 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  ite3*);../*.** C
13f20 41 50 49 33 52 45 46 3a 20 54 6f 74 61 6c 20 4e  API3REF: Total N
13f30 75 6d 62 65 72 20 4f 66 20 52 6f 77 73 20 4d 6f  umber Of Rows Mo
13f40 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a 20 5e 54 68  dified.**.** ^Th
13f50 69 73 20 66 75 6e 63 74 69 6f 6e 20 72 65 74 75  is function retu
13f60 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  rns the number o
13f70 66 20 72 6f 77 20 63 68 61 6e 67 65 73 20 63 61  f row changes ca
13f80 75 73 65 64 20 62 79 20 5b 49 4e 53 45 52 54 5d  used by [INSERT]
13f90 2c 0a 2a 2a 20 5b 55 50 44 41 54 45 5d 20 6f 72  ,.** [UPDATE] or
13fa0 20 5b 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d   [DELETE] statem
13fb0 65 6e 74 73 20 73 69 6e 63 65 20 74 68 65 20 5b  ents since the [
13fc0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
13fd0 69 6f 6e 5d 20 77 61 73 20 6f 70 65 6e 65 64 2e  ion] was opened.
13fe0 0a 2a 2a 20 5e 28 54 68 65 20 63 6f 75 6e 74 20  .** ^(The count 
13ff0 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
14000 74 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65  te3_total_change
14010 73 28 29 20 69 6e 63 6c 75 64 65 73 20 61 6c 6c  s() includes all
14020 20 63 68 61 6e 67 65 73 0a 2a 2a 20 66 72 6f 6d   changes.** from
14030 20 61 6c 6c 20 5b 43 52 45 41 54 45 20 54 52 49   all [CREATE TRI
14040 47 47 45 52 20 7c 20 74 72 69 67 67 65 72 5d 20  GGER | trigger] 
14050 63 6f 6e 74 65 78 74 73 20 61 6e 64 20 63 68 61  contexts and cha
14060 6e 67 65 73 20 6d 61 64 65 20 62 79 0a 2a 2a 20  nges made by.** 
14070 5b 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63 74  [foreign key act
14080 69 6f 6e 73 5d 2e 20 48 6f 77 65 76 65 72 2c 0a  ions]. However,.
14090 2a 2a 20 74 68 65 20 63 6f 75 6e 74 20 64 6f 65  ** the count doe
140a0 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 63 68  s not include ch
140b0 61 6e 67 65 73 20 75 73 65 64 20 74 6f 20 69 6d  anges used to im
140c0 70 6c 65 6d 65 6e 74 20 5b 52 45 50 4c 41 43 45  plement [REPLACE
140d0 5d 20 63 6f 6e 73 74 72 61 69 6e 74 73 2c 0a 2a  ] constraints,.*
140e0 2a 20 64 6f 20 72 6f 6c 6c 62 61 63 6b 73 20 6f  * do rollbacks o
140f0 72 20 41 42 4f 52 54 20 70 72 6f 63 65 73 73 69  r ABORT processi
14100 6e 67 2c 20 6f 72 20 5b 44 52 4f 50 20 54 41 42  ng, or [DROP TAB
14110 4c 45 5d 20 70 72 6f 63 65 73 73 69 6e 67 2e 20  LE] processing. 
14120 20 54 68 65 0a 2a 2a 20 63 6f 75 6e 74 20 64 6f   The.** count do
14130 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 72  es not include r
14140 6f 77 73 20 6f 66 20 76 69 65 77 73 20 74 68 61  ows of views tha
14150 74 20 66 69 72 65 20 61 6e 20 5b 49 4e 53 54 45  t fire an [INSTE
14160 41 44 20 4f 46 20 74 72 69 67 67 65 72 5d 2c 0a  AD OF trigger],.
14170 2a 2a 20 74 68 6f 75 67 68 20 69 66 20 74 68 65  ** though if the
14180 20 49 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67   INSTEAD OF trig
14190 67 65 72 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ger makes change
141a0 73 20 6f 66 20 69 74 73 20 6f 77 6e 2c 20 74 68  s of its own, th
141b0 6f 73 65 20 63 68 61 6e 67 65 73 20 0a 2a 2a 20  ose changes .** 
141c0 61 72 65 20 63 6f 75 6e 74 65 64 2e 29 5e 0a 2a  are counted.)^.*
141d0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 74  * ^The sqlite3_t
141e0 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 20 66  otal_changes() f
141f0 75 6e 63 74 69 6f 6e 20 63 6f 75 6e 74 73 20 74  unction counts t
14200 68 65 20 63 68 61 6e 67 65 73 20 61 73 20 73 6f  he changes as so
14210 6f 6e 20 61 73 0a 2a 2a 20 74 68 65 20 73 74 61  on as.** the sta
14220 74 65 6d 65 6e 74 20 74 68 61 74 20 6d 61 6b 65  tement that make
14230 73 20 74 68 65 6d 20 69 73 20 63 6f 6d 70 6c 65  s them is comple
14240 74 65 64 20 28 77 68 65 6e 20 74 68 65 20 73 74  ted (when the st
14250 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 0a 2a  atement handle.*
14260 2a 20 69 73 20 70 61 73 73 65 64 20 74 6f 20 5b  * is passed to [
14270 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
14280 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e   or [sqlite3_fin
14290 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a 2a 0a 2a 2a  alize()])..**.**
142a0 20 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73   See also the [s
142b0 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73 28 29  qlite3_changes()
142c0 5d 20 69 6e 74 65 72 66 61 63 65 2c 20 74 68 65  ] interface, the
142d0 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63 68 61 6e 67  .** [count_chang
142e0 65 73 20 70 72 61 67 6d 61 5d 2c 20 61 6e 64 20  es pragma], and 
142f0 74 68 65 20 5b 74 6f 74 61 6c 5f 63 68 61 6e 67  the [total_chang
14300 65 73 28 29 20 53 51 4c 20 66 75 6e 63 74 69 6f  es() SQL functio
14310 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 20 73  n]..**.** If a s
14320 65 70 61 72 61 74 65 20 74 68 72 65 61 64 20 6d  eparate thread m
14330 61 6b 65 73 20 63 68 61 6e 67 65 73 20 6f 6e 20  akes changes on 
14340 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
14350 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20  e connection.** 
14360 77 68 69 6c 65 20 5b 73 71 6c 69 74 65 33 5f 74  while [sqlite3_t
14370 6f 74 61 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20  otal_changes()] 
14380 69 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20  is running then 
14390 74 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  the value.** ret
143a0 75 72 6e 65 64 20 69 73 20 75 6e 70 72 65 64 69  urned is unpredi
143b0 63 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d  ctable and not m
143c0 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e  eaningful..*/.in
143d0 74 20 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f  t sqlite3_total_
143e0 63 68 61 6e 67 65 73 28 73 71 6c 69 74 65 33 2a  changes(sqlite3*
143f0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
14400 45 46 3a 20 49 6e 74 65 72 72 75 70 74 20 41 20  EF: Interrupt A 
14410 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67 20 51 75 65  Long-Running Que
14420 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 66  ry.**.** ^This f
14430 75 6e 63 74 69 6f 6e 20 63 61 75 73 65 73 20 61  unction causes a
14440 6e 79 20 70 65 6e 64 69 6e 67 20 64 61 74 61 62  ny pending datab
14450 61 73 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 6f  ase operation to
14460 20 61 62 6f 72 74 20 61 6e 64 0a 2a 2a 20 72 65   abort and.** re
14470 74 75 72 6e 20 61 74 20 69 74 73 20 65 61 72 6c  turn at its earl
14480 69 65 73 74 20 6f 70 70 6f 72 74 75 6e 69 74 79  iest opportunity
14490 2e 20 54 68 69 73 20 72 6f 75 74 69 6e 65 20 69  . This routine i
144a0 73 20 74 79 70 69 63 61 6c 6c 79 0a 2a 2a 20 63  s typically.** c
144b0 61 6c 6c 65 64 20 69 6e 20 72 65 73 70 6f 6e 73  alled in respons
144c0 65 20 74 6f 20 61 20 75 73 65 72 20 61 63 74 69  e to a user acti
144d0 6f 6e 20 73 75 63 68 20 61 73 20 70 72 65 73 73  on such as press
144e0 69 6e 67 20 22 43 61 6e 63 65 6c 22 0a 2a 2a 20  ing "Cancel".** 
144f0 6f 72 20 43 74 72 6c 2d 43 20 77 68 65 72 65 20  or Ctrl-C where 
14500 74 68 65 20 75 73 65 72 20 77 61 6e 74 73 20 61  the user wants a
14510 20 6c 6f 6e 67 20 71 75 65 72 79 20 6f 70 65 72   long query oper
14520 61 74 69 6f 6e 20 74 6f 20 68 61 6c 74 0a 2a 2a  ation to halt.**
14530 20 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a   immediately..**
14540 0a 2a 2a 20 5e 49 74 20 69 73 20 73 61 66 65 20  .** ^It is safe 
14550 74 6f 20 63 61 6c 6c 20 74 68 69 73 20 72 6f 75  to call this rou
14560 74 69 6e 65 20 66 72 6f 6d 20 61 20 74 68 72 65  tine from a thre
14570 61 64 20 64 69 66 66 65 72 65 6e 74 20 66 72 6f  ad different fro
14580 6d 20 74 68 65 0a 2a 2a 20 74 68 72 65 61 64 20  m the.** thread 
14590 74 68 61 74 20 69 73 20 63 75 72 72 65 6e 74 6c  that is currentl
145a0 79 20 72 75 6e 6e 69 6e 67 20 74 68 65 20 64 61  y running the da
145b0 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f 6e  tabase operation
145c0 2e 20 20 42 75 74 20 69 74 0a 2a 2a 20 69 73 20  .  But it.** is 
145d0 6e 6f 74 20 73 61 66 65 20 74 6f 20 63 61 6c 6c  not safe to call
145e0 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69   this routine wi
145f0 74 68 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  th a [database c
14600 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 68 61 74 0a  onnection] that.
14610 2a 2a 20 69 73 20 63 6c 6f 73 65 64 20 6f 72 20  ** is closed or 
14620 6d 69 67 68 74 20 63 6c 6f 73 65 20 62 65 66 6f  might close befo
14630 72 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  re sqlite3_inter
14640 72 75 70 74 28 29 20 72 65 74 75 72 6e 73 2e 0a  rupt() returns..
14650 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 20 53 51 4c  **.** ^If an SQL
14660 20 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 76 65   operation is ve
14670 72 79 20 6e 65 61 72 6c 79 20 66 69 6e 69 73 68  ry nearly finish
14680 65 64 20 61 74 20 74 68 65 20 74 69 6d 65 20 77  ed at the time w
14690 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 69  hen.** sqlite3_i
146a0 6e 74 65 72 72 75 70 74 28 29 20 69 73 20 63 61  nterrupt() is ca
146b0 6c 6c 65 64 2c 20 74 68 65 6e 20 69 74 20 6d 69  lled, then it mi
146c0 67 68 74 20 6e 6f 74 20 68 61 76 65 20 61 6e 20  ght not have an 
146d0 6f 70 70 6f 72 74 75 6e 69 74 79 0a 2a 2a 20 74  opportunity.** t
146e0 6f 20 62 65 20 69 6e 74 65 72 72 75 70 74 65 64  o be interrupted
146f0 20 61 6e 64 20 6d 69 67 68 74 20 63 6f 6e 74 69   and might conti
14700 6e 75 65 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f  nue to completio
14710 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e 20 53 51 4c  n..**.** ^An SQL
14720 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61 74 20   operation that 
14730 69 73 20 69 6e 74 65 72 72 75 70 74 65 64 20 77  is interrupted w
14740 69 6c 6c 20 72 65 74 75 72 6e 20 5b 53 51 4c 49  ill return [SQLI
14750 54 45 5f 49 4e 54 45 52 52 55 50 54 5d 2e 0a 2a  TE_INTERRUPT]..*
14760 2a 20 5e 49 66 20 74 68 65 20 69 6e 74 65 72 72  * ^If the interr
14770 75 70 74 65 64 20 53 51 4c 20 6f 70 65 72 61 74  upted SQL operat
14780 69 6f 6e 20 69 73 20 61 6e 20 49 4e 53 45 52 54  ion is an INSERT
14790 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c  , UPDATE, or DEL
147a0 45 54 45 0a 2a 2a 20 74 68 61 74 20 69 73 20 69  ETE.** that is i
147b0 6e 73 69 64 65 20 61 6e 20 65 78 70 6c 69 63 69  nside an explici
147c0 74 20 74 72 61 6e 73 61 63 74 69 6f 6e 2c 20 74  t transaction, t
147d0 68 65 6e 20 74 68 65 20 65 6e 74 69 72 65 20 74  hen the entire t
147e0 72 61 6e 73 61 63 74 69 6f 6e 0a 2a 2a 20 77 69  ransaction.** wi
147f0 6c 6c 20 62 65 20 72 6f 6c 6c 65 64 20 62 61 63  ll be rolled bac
14800 6b 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 2e  k automatically.
14810 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
14820 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 44 29  te3_interrupt(D)
14830 20 63 61 6c 6c 20 69 73 20 69 6e 20 65 66 66 65   call is in effe
14840 63 74 20 75 6e 74 69 6c 20 61 6c 6c 20 63 75 72  ct until all cur
14850 72 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 0a 2a  rently running.*
14860 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  * SQL statements
14870 20 6f 6e 20 5b 64 61 74 61 62 61 73 65 20 63 6f   on [database co
14880 6e 6e 65 63 74 69 6f 6e 5d 20 44 20 63 6f 6d 70  nnection] D comp
14890 6c 65 74 65 2e 20 20 5e 41 6e 79 20 6e 65 77 20  lete.  ^Any new 
148a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a  SQL statements.*
148b0 2a 20 74 68 61 74 20 61 72 65 20 73 74 61 72 74  * that are start
148c0 65 64 20 61 66 74 65 72 20 74 68 65 20 73 71 6c  ed after the sql
148d0 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29  ite3_interrupt()
148e0 20 63 61 6c 6c 20 61 6e 64 20 62 65 66 6f 72 65   call and before
148f0 20 74 68 65 20 0a 2a 2a 20 72 75 6e 6e 69 6e 67   the .** running
14900 20 73 74 61 74 65 6d 65 6e 74 73 20 72 65 61 63   statements reac
14910 68 65 73 20 7a 65 72 6f 20 61 72 65 20 69 6e 74  hes zero are int
14920 65 72 72 75 70 74 65 64 20 61 73 20 69 66 20 74  errupted as if t
14930 68 65 79 20 68 61 64 20 62 65 65 6e 0a 2a 2a 20  hey had been.** 
14940 72 75 6e 6e 69 6e 67 20 70 72 69 6f 72 20 74 6f  running prior to
14950 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74   the sqlite3_int
14960 65 72 72 75 70 74 28 29 20 63 61 6c 6c 2e 20 20  errupt() call.  
14970 5e 4e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65  ^New SQL stateme
14980 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  nts.** that are 
14990 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68  started after th
149a0 65 20 72 75 6e 6e 69 6e 67 20 73 74 61 74 65 6d  e running statem
149b0 65 6e 74 20 63 6f 75 6e 74 20 72 65 61 63 68 65  ent count reache
149c0 73 20 7a 65 72 6f 20 61 72 65 0a 2a 2a 20 6e 6f  s zero are.** no
149d0 74 20 65 66 66 65 63 74 65 64 20 62 79 20 74 68  t effected by th
149e0 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72  e sqlite3_interr
149f0 75 70 74 28 29 2e 0a 2a 2a 20 5e 41 20 63 61 6c  upt()..** ^A cal
14a00 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 74  l to sqlite3_int
14a10 65 72 72 75 70 74 28 44 29 20 74 68 61 74 20 6f  errupt(D) that o
14a20 63 63 75 72 73 20 77 68 65 6e 20 74 68 65 72 65  ccurs when there
14a30 20 61 72 65 20 6e 6f 20 72 75 6e 6e 69 6e 67 0a   are no running.
14a40 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
14a50 73 20 69 73 20 61 20 6e 6f 2d 6f 70 20 61 6e 64  s is a no-op and
14a60 20 68 61 73 20 6e 6f 20 65 66 66 65 63 74 20 6f   has no effect o
14a70 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  n SQL statements
14a80 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73 74 61  .** that are sta
14a90 72 74 65 64 20 61 66 74 65 72 20 74 68 65 20 73  rted after the s
14aa0 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
14ab0 28 29 20 63 61 6c 6c 20 72 65 74 75 72 6e 73 2e  () call returns.
14ac0 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 64 61  .**.** If the da
14ad0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
14ae0 6e 20 63 6c 6f 73 65 73 20 77 68 69 6c 65 20 5b  n closes while [
14af0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
14b00 74 28 29 5d 0a 2a 2a 20 69 73 20 72 75 6e 6e 69  t()].** is runni
14b10 6e 67 20 74 68 65 6e 20 62 61 64 20 74 68 69 6e  ng then bad thin
14b20 67 73 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 68  gs will likely h
14b30 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f 69 64 20 73  appen..*/.void s
14b40 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70 74  qlite3_interrupt
14b50 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
14b60 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
14b70 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
14b80 20 53 74 61 74 65 6d 65 6e 74 20 49 73 20 43 6f   Statement Is Co
14b90 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a 20 54 68 65  mplete.**.** The
14ba0 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
14bb0 75 73 65 66 75 6c 20 64 75 72 69 6e 67 20 63 6f  useful during co
14bc0 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69 6e 70 75 74  mmand-line input
14bd0 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 69 66   to determine if
14be0 20 74 68 65 0a 2a 2a 20 63 75 72 72 65 6e 74 6c   the.** currentl
14bf0 79 20 65 6e 74 65 72 65 64 20 74 65 78 74 20 73  y entered text s
14c00 65 65 6d 73 20 74 6f 20 66 6f 72 6d 20 61 20 63  eems to form a c
14c10 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
14c20 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20 69 66 20 61  ement or.** if a
14c30 64 64 69 74 69 6f 6e 61 6c 20 69 6e 70 75 74 20  dditional input 
14c40 69 73 20 6e 65 65 64 65 64 20 62 65 66 6f 72 65  is needed before
14c50 20 73 65 6e 64 69 6e 67 20 74 68 65 20 74 65 78   sending the tex
14c60 74 20 69 6e 74 6f 0a 2a 2a 20 53 51 4c 69 74 65  t into.** SQLite
14c70 20 66 6f 72 20 70 61 72 73 69 6e 67 2e 20 20 5e   for parsing.  ^
14c80 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
14c90 65 74 75 72 6e 20 31 20 69 66 20 74 68 65 20 69  eturn 1 if the i
14ca0 6e 70 75 74 20 73 74 72 69 6e 67 0a 2a 2a 20 61  nput string.** a
14cb0 70 70 65 61 72 73 20 74 6f 20 62 65 20 61 20 63  ppears to be a c
14cc0 6f 6d 70 6c 65 74 65 20 53 51 4c 20 73 74 61 74  omplete SQL stat
14cd0 65 6d 65 6e 74 2e 20 20 5e 41 20 73 74 61 74 65  ement.  ^A state
14ce0 6d 65 6e 74 20 69 73 20 6a 75 64 67 65 64 20 74  ment is judged t
14cf0 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 6c 65 74 65  o be.** complete
14d00 20 69 66 20 69 74 20 65 6e 64 73 20 77 69 74 68   if it ends with
14d10 20 61 20 73 65 6d 69 63 6f 6c 6f 6e 20 74 6f 6b   a semicolon tok
14d20 65 6e 20 61 6e 64 20 69 73 20 6e 6f 74 20 61 20  en and is not a 
14d30 70 72 65 66 69 78 20 6f 66 20 61 0a 2a 2a 20 77  prefix of a.** w
14d40 65 6c 6c 2d 66 6f 72 6d 65 64 20 43 52 45 41 54  ell-formed CREAT
14d50 45 20 54 52 49 47 47 45 52 20 73 74 61 74 65 6d  E TRIGGER statem
14d60 65 6e 74 2e 20 20 5e 53 65 6d 69 63 6f 6c 6f 6e  ent.  ^Semicolon
14d70 73 20 74 68 61 74 20 61 72 65 20 65 6d 62 65 64  s that are embed
14d80 64 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20 73 74  ded within.** st
14d90 72 69 6e 67 20 6c 69 74 65 72 61 6c 73 20 6f 72  ring literals or
14da0 20 71 75 6f 74 65 64 20 69 64 65 6e 74 69 66 69   quoted identifi
14db0 65 72 20 6e 61 6d 65 73 20 6f 72 20 63 6f 6d 6d  er names or comm
14dc0 65 6e 74 73 20 61 72 65 20 6e 6f 74 0a 2a 2a 20  ents are not.** 
14dd0 69 6e 64 65 70 65 6e 64 65 6e 74 20 74 6f 6b 65  independent toke
14de0 6e 73 20 28 74 68 65 79 20 61 72 65 20 70 61 72  ns (they are par
14df0 74 20 6f 66 20 74 68 65 20 74 6f 6b 65 6e 20 69  t of the token i
14e00 6e 20 77 68 69 63 68 20 74 68 65 79 20 61 72 65  n which they are
14e10 0a 2a 2a 20 65 6d 62 65 64 64 65 64 29 20 61 6e  .** embedded) an
14e20 64 20 74 68 75 73 20 64 6f 20 6e 6f 74 20 63 6f  d thus do not co
14e30 75 6e 74 20 61 73 20 61 20 73 74 61 74 65 6d 65  unt as a stateme
14e40 6e 74 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20  nt terminator.  
14e50 5e 57 68 69 74 65 73 70 61 63 65 0a 2a 2a 20 61  ^Whitespace.** a
14e60 6e 64 20 63 6f 6d 6d 65 6e 74 73 20 74 68 61 74  nd comments that
14e70 20 66 6f 6c 6c 6f 77 20 74 68 65 20 66 69 6e 61   follow the fina
14e80 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20 61 72 65 20  l semicolon are 
14e90 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  ignored..**.** ^
14ea0 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 72  These routines r
14eb0 65 74 75 72 6e 20 30 20 69 66 20 74 68 65 20 73  eturn 0 if the s
14ec0 74 61 74 65 6d 65 6e 74 20 69 73 20 69 6e 63 6f  tatement is inco
14ed0 6d 70 6c 65 74 65 2e 20 20 5e 49 66 20 61 0a 2a  mplete.  ^If a.*
14ee0 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  * memory allocat
14ef0 69 6f 6e 20 66 61 69 6c 73 2c 20 74 68 65 6e 20  ion fails, then 
14f00 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 20 69 73 20  SQLITE_NOMEM is 
14f10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
14f20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20  ^These routines 
14f30 64 6f 20 6e 6f 74 20 70 61 72 73 65 20 74 68 65  do not parse the
14f40 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20   SQL statements 
14f50 74 68 75 73 0a 2a 2a 20 77 69 6c 6c 20 6e 6f 74  thus.** will not
14f60 20 64 65 74 65 63 74 20 73 79 6e 74 61 63 74 69   detect syntacti
14f70 63 61 6c 6c 79 20 69 6e 63 6f 72 72 65 63 74 20  cally incorrect 
14f80 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  SQL..**.** ^(If 
14f90 53 51 4c 69 74 65 20 68 61 73 20 6e 6f 74 20 62  SQLite has not b
14fa0 65 65 6e 20 69 6e 69 74 69 61 6c 69 7a 65 64 20  een initialized 
14fb0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 69  using [sqlite3_i
14fc0 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 70 72 69  nitialize()] pri
14fd0 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e 76 6f 6b 69  or .** to invoki
14fe0 6e 67 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  ng sqlite3_compl
14ff0 65 74 65 31 36 28 29 20 74 68 65 6e 20 73 71 6c  ete16() then sql
15000 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
15010 29 20 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20  ) is invoked.** 
15020 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 62 79  automatically by
15030 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74   sqlite3_complet
15040 65 31 36 28 29 2e 20 20 49 66 20 74 68 61 74 20  e16().  If that 
15050 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20 66  initialization f
15060 61 69 6c 73 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  ails,.** then th
15070 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
15080 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70  rom sqlite3_comp
15090 6c 65 74 65 31 36 28 29 20 77 69 6c 6c 20 62 65  lete16() will be
150a0 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a 20 72 65 67   non-zero.** reg
150b0 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
150c0 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 69 6e  er or not the in
150d0 70 75 74 20 53 51 4c 20 69 73 20 63 6f 6d 70 6c  put SQL is compl
150e0 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65  ete.)^.**.** The
150f0 20 69 6e 70 75 74 20 74 6f 20 5b 73 71 6c 69 74   input to [sqlit
15100 65 33 5f 63 6f 6d 70 6c 65 74 65 28 29 5d 20 6d  e3_complete()] m
15110 75 73 74 20 62 65 20 61 20 7a 65 72 6f 2d 74 65  ust be a zero-te
15120 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 55 54 46 2d  rminated.** UTF-
15130 38 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20  8 string..**.** 
15140 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73 71  The input to [sq
15150 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 31 36  lite3_complete16
15160 28 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65  ()] must be a ze
15170 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a  ro-terminated.**
15180 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 20 69   UTF-16 string i
15190 6e 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72  n native byte or
151a0 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  der..*/.int sqli
151b0 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28 63 6f 6e  te3_complete(con
151c0 73 74 20 63 68 61 72 20 2a 73 71 6c 29 3b 0a 69  st char *sql);.i
151d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c  nt sqlite3_compl
151e0 65 74 65 31 36 28 63 6f 6e 73 74 20 76 6f 69 64  ete16(const void
151f0 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   *sql);../*.** C
15200 41 50 49 33 52 45 46 3a 20 52 65 67 69 73 74 65  API3REF: Registe
15210 72 20 41 20 43 61 6c 6c 62 61 63 6b 20 54 6f 20  r A Callback To 
15220 48 61 6e 64 6c 65 20 53 51 4c 49 54 45 5f 42 55  Handle SQLITE_BU
15230 53 59 20 45 72 72 6f 72 73 0a 2a 2a 0a 2a 2a 20  SY Errors.**.** 
15240 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73 65  ^This routine se
15250 74 73 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75  ts a callback fu
15260 6e 63 74 69 6f 6e 20 74 68 61 74 20 6d 69 67 68  nction that migh
15270 74 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  t be invoked whe
15280 6e 65 76 65 72 0a 2a 2a 20 61 6e 20 61 74 74 65  never.** an atte
15290 6d 70 74 20 69 73 20 6d 61 64 65 20 74 6f 20 6f  mpt is made to o
152a0 70 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 74  pen a database t
152b0 61 62 6c 65 20 74 68 61 74 20 61 6e 6f 74 68 65  able that anothe
152c0 72 20 74 68 72 65 61 64 0a 2a 2a 20 6f 72 20 70  r thread.** or p
152d0 72 6f 63 65 73 73 20 68 61 73 20 6c 6f 63 6b 65  rocess has locke
152e0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  d..**.** ^If the
152f0 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
15300 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 5b 53 51  s NULL, then [SQ
15310 4c 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53  LITE_BUSY] or [S
15320 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43  QLITE_IOERR_BLOC
15330 4b 45 44 5d 0a 2a 2a 20 69 73 20 72 65 74 75 72  KED].** is retur
15340 6e 65 64 20 69 6d 6d 65 64 69 61 74 65 6c 79 20  ned immediately 
15350 75 70 6f 6e 20 65 6e 63 6f 75 6e 74 65 72 69 6e  upon encounterin
15360 67 20 74 68 65 20 6c 6f 63 6b 2e 20 20 5e 49 66  g the lock.  ^If
15370 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
15380 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74 20 4e 55 4c  ck.** is not NUL
15390 4c 2c 20 74 68 65 6e 20 74 68 65 20 63 61 6c 6c  L, then the call
153a0 62 61 63 6b 20 6d 69 67 68 74 20 62 65 20 69 6e  back might be in
153b0 76 6f 6b 65 64 20 77 69 74 68 20 74 77 6f 20 61  voked with two a
153c0 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  rguments..**.** 
153d0 5e 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d  ^The first argum
153e0 65 6e 74 20 74 6f 20 74 68 65 20 62 75 73 79 20  ent to the busy 
153f0 68 61 6e 64 6c 65 72 20 69 73 20 61 20 63 6f 70  handler is a cop
15400 79 20 6f 66 20 74 68 65 20 76 6f 69 64 2a 20 70  y of the void* p
15410 6f 69 6e 74 65 72 20 77 68 69 63 68 0a 2a 2a 20  ointer which.** 
15420 69 73 20 74 68 65 20 74 68 69 72 64 20 61 72 67  is the third arg
15430 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
15440 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 2e  _busy_handler().
15450 20 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72    ^The second ar
15460 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a 20 74 68 65  gument to.** the
15470 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20 63 61   busy handler ca
15480 6c 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 75  llback is the nu
15490 6d 62 65 72 20 6f 66 20 74 69 6d 65 73 20 74 68  mber of times th
154a0 61 74 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  at the busy hand
154b0 6c 65 72 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20  ler has.** been 
154c0 69 6e 76 6f 6b 65 64 20 66 6f 72 20 74 68 69 73  invoked for this
154d0 20 6c 6f 63 6b 69 6e 67 20 65 76 65 6e 74 2e 20   locking event. 
154e0 20 5e 49 66 20 74 68 65 0a 2a 2a 20 62 75 73 79   ^If the.** busy
154f0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
15500 73 20 30 2c 20 74 68 65 6e 20 6e 6f 20 61 64 64  s 0, then no add
15510 69 74 69 6f 6e 61 6c 20 61 74 74 65 6d 70 74 73  itional attempts
15520 20 61 72 65 20 6d 61 64 65 20 74 6f 0a 2a 2a 20   are made to.** 
15530 61 63 63 65 73 73 20 74 68 65 20 64 61 74 61 62  access the datab
15540 61 73 65 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  ase and [SQLITE_
15550 42 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45  BUSY] or [SQLITE
15560 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 20  _IOERR_BLOCKED] 
15570 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20  is returned..** 
15580 5e 49 66 20 74 68 65 20 63 61 6c 6c 62 61 63 6b  ^If the callback
15590 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72   returns non-zer
155a0 6f 2c 20 74 68 65 6e 20 61 6e 6f 74 68 65 72 20  o, then another 
155b0 61 74 74 65 6d 70 74 0a 2a 2a 20 69 73 20 6d 61  attempt.** is ma
155c0 64 65 20 74 6f 20 6f 70 65 6e 20 74 68 65 20 64  de to open the d
155d0 61 74 61 62 61 73 65 20 66 6f 72 20 72 65 61 64  atabase for read
155e0 69 6e 67 20 61 6e 64 20 74 68 65 20 63 79 63 6c  ing and the cycl
155f0 65 20 72 65 70 65 61 74 73 2e 0a 2a 2a 0a 2a 2a  e repeats..**.**
15600 20 54 68 65 20 70 72 65 73 65 6e 63 65 20 6f 66   The presence of
15610 20 61 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20   a busy handler 
15620 64 6f 65 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  does not guarant
15630 65 65 20 74 68 61 74 20 69 74 20 77 69 6c 6c 20  ee that it will 
15640 62 65 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 77 68  be invoked.** wh
15650 65 6e 20 74 68 65 72 65 20 69 73 20 6c 6f 63 6b  en there is lock
15660 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e 20 5e 49 66   contention. ^If
15670 20 53 51 4c 69 74 65 20 64 65 74 65 72 6d 69 6e   SQLite determin
15680 65 73 20 74 68 61 74 20 69 6e 76 6f 6b 69 6e 67  es that invoking
15690 20 74 68 65 20 62 75 73 79 0a 2a 2a 20 68 61 6e   the busy.** han
156a0 64 6c 65 72 20 63 6f 75 6c 64 20 72 65 73 75 6c  dler could resul
156b0 74 20 69 6e 20 61 20 64 65 61 64 6c 6f 63 6b 2c  t in a deadlock,
156c0 20 69 74 20 77 69 6c 6c 20 67 6f 20 61 68 65 61   it will go ahea
156d0 64 20 61 6e 64 20 72 65 74 75 72 6e 20 5b 53 51  d and return [SQ
156e0 4c 49 54 45 5f 42 55 53 59 5d 0a 2a 2a 20 6f 72  LITE_BUSY].** or
156f0 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f 42   [SQLITE_IOERR_B
15700 4c 4f 43 4b 45 44 5d 20 69 6e 73 74 65 61 64 20  LOCKED] instead 
15710 6f 66 20 69 6e 76 6f 6b 69 6e 67 20 74 68 65 20  of invoking the 
15720 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a  busy handler..**
15730 20 43 6f 6e 73 69 64 65 72 20 61 20 73 63 65 6e   Consider a scen
15740 61 72 69 6f 20 77 68 65 72 65 20 6f 6e 65 20 70  ario where one p
15750 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64 69 6e  rocess is holdin
15760 67 20 61 20 72 65 61 64 20 6c 6f 63 6b 20 74 68  g a read lock th
15770 61 74 0a 2a 2a 20 69 74 20 69 73 20 74 72 79 69  at.** it is tryi
15780 6e 67 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74 6f  ng to promote to
15790 20 61 20 72 65 73 65 72 76 65 64 20 6c 6f 63 6b   a reserved lock
157a0 20 61 6e 64 0a 2a 2a 20 61 20 73 65 63 6f 6e 64   and.** a second
157b0 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f 6c 64   process is hold
157c0 69 6e 67 20 61 20 72 65 73 65 72 76 65 64 20 6c  ing a reserved l
157d0 6f 63 6b 20 74 68 61 74 20 69 74 20 69 73 20 74  ock that it is t
157e0 72 79 69 6e 67 0a 2a 2a 20 74 6f 20 70 72 6f 6d  rying.** to prom
157f0 6f 74 65 20 74 6f 20 61 6e 20 65 78 63 6c 75 73  ote to an exclus
15800 69 76 65 20 6c 6f 63 6b 2e 20 20 54 68 65 20 66  ive lock.  The f
15810 69 72 73 74 20 70 72 6f 63 65 73 73 20 63 61 6e  irst process can
15820 6e 6f 74 20 70 72 6f 63 65 65 64 0a 2a 2a 20 62  not proceed.** b
15830 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c 6f  ecause it is blo
15840 63 6b 65 64 20 62 79 20 74 68 65 20 73 65 63 6f  cked by the seco
15850 6e 64 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  nd and the secon
15860 64 20 70 72 6f 63 65 73 73 20 63 61 6e 6e 6f 74  d process cannot
15870 0a 2a 2a 20 70 72 6f 63 65 65 64 20 62 65 63 61  .** proceed beca
15880 75 73 65 20 69 74 20 69 73 20 62 6c 6f 63 6b 65  use it is blocke
15890 64 20 62 79 20 74 68 65 20 66 69 72 73 74 2e 20  d by the first. 
158a0 20 49 66 20 62 6f 74 68 20 70 72 6f 63 65 73 73   If both process
158b0 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65  es.** invoke the
158c0 20 62 75 73 79 20 68 61 6e 64 6c 65 72 73 2c 20   busy handlers, 
158d0 6e 65 69 74 68 65 72 20 77 69 6c 6c 20 6d 61 6b  neither will mak
158e0 65 20 61 6e 79 20 70 72 6f 67 72 65 73 73 2e 20  e any progress. 
158f0 20 54 68 65 72 65 66 6f 72 65 2c 0a 2a 2a 20 53   Therefore,.** S
15900 51 4c 69 74 65 20 72 65 74 75 72 6e 73 20 5b 53  QLite returns [S
15910 51 4c 49 54 45 5f 42 55 53 59 5d 20 66 6f 72 20  QLITE_BUSY] for 
15920 74 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73  the first proces
15930 73 2c 20 68 6f 70 69 6e 67 20 74 68 61 74 20 74  s, hoping that t
15940 68 69 73 0a 2a 2a 20 77 69 6c 6c 20 69 6e 64 75  his.** will indu
15950 63 65 20 74 68 65 20 66 69 72 73 74 20 70 72 6f  ce the first pro
15960 63 65 73 73 20 74 6f 20 72 65 6c 65 61 73 65 20  cess to release 
15970 69 74 73 20 72 65 61 64 20 6c 6f 63 6b 20 61 6e  its read lock an
15980 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74 68 65 20 73  d allow.** the s
15990 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 74 6f  econd process to
159a0 20 70 72 6f 63 65 65 64 2e 0a 2a 2a 0a 2a 2a 20   proceed..**.** 
159b0 5e 54 68 65 20 64 65 66 61 75 6c 74 20 62 75 73  ^The default bus
159c0 79 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 4e 55  y callback is NU
159d0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b  LL..**.** ^The [
159e0 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 65 72 72  SQLITE_BUSY] err
159f0 6f 72 20 69 73 20 63 6f 6e 76 65 72 74 65 64 20  or is converted 
15a00 74 6f 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  to [SQLITE_IOERR
15a10 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 77 68 65  _BLOCKED].** whe
15a20 6e 20 53 51 4c 69 74 65 20 69 73 20 69 6e 20 74  n SQLite is in t
15a30 68 65 20 6d 69 64 64 6c 65 20 6f 66 20 61 20 6c  he middle of a l
15a40 61 72 67 65 20 74 72 61 6e 73 61 63 74 69 6f 6e  arge transaction
15a50 20 77 68 65 72 65 20 61 6c 6c 20 74 68 65 0a 2a   where all the.*
15a60 2a 20 63 68 61 6e 67 65 73 20 77 69 6c 6c 20 6e  * changes will n
15a70 6f 74 20 66 69 74 20 69 6e 74 6f 20 74 68 65 20  ot fit into the 
15a80 69 6e 2d 6d 65 6d 6f 72 79 20 63 61 63 68 65 2e  in-memory cache.
15a90 20 20 53 51 4c 69 74 65 20 77 69 6c 6c 0a 2a 2a    SQLite will.**
15aa0 20 61 6c 72 65 61 64 79 20 68 6f 6c 64 20 61 20   already hold a 
15ab0 52 45 53 45 52 56 45 44 20 6c 6f 63 6b 20 6f 6e  RESERVED lock on
15ac0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66 69   the database fi
15ad0 6c 65 2c 20 62 75 74 20 69 74 20 6e 65 65 64 73  le, but it needs
15ae0 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f 74 65 20 74  .** to promote t
15af0 68 69 73 20 6c 6f 63 6b 20 74 6f 20 45 58 43 4c  his lock to EXCL
15b00 55 53 49 56 45 20 73 6f 20 74 68 61 74 20 69 74  USIVE so that it
15b10 20 63 61 6e 20 73 70 69 6c 6c 20 63 61 63 68 65   can spill cache
15b20 0a 2a 2a 20 70 61 67 65 73 20 69 6e 74 6f 20 74  .** pages into t
15b30 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
15b40 20 77 69 74 68 6f 75 74 20 68 61 72 6d 20 74 6f   without harm to
15b50 20 63 6f 6e 63 75 72 72 65 6e 74 0a 2a 2a 20 72   concurrent.** r
15b60 65 61 64 65 72 73 2e 20 20 5e 49 66 20 69 74 20  eaders.  ^If it 
15b70 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 70 72 6f  is unable to pro
15b80 6d 6f 74 65 20 74 68 65 20 6c 6f 63 6b 2c 20 74  mote the lock, t
15b90 68 65 6e 20 74 68 65 20 69 6e 2d 6d 65 6d 6f 72  hen the in-memor
15ba0 79 0a 2a 2a 20 63 61 63 68 65 20 77 69 6c 6c 20  y.** cache will 
15bb0 62 65 20 6c 65 66 74 20 69 6e 20 61 6e 20 69 6e  be left in an in
15bc0 63 6f 6e 73 69 73 74 65 6e 74 20 73 74 61 74 65  consistent state
15bd0 20 61 6e 64 20 73 6f 20 74 68 65 20 65 72 72 6f   and so the erro
15be0 72 0a 2a 2a 20 63 6f 64 65 20 69 73 20 70 72 6f  r.** code is pro
15bf0 6d 6f 74 65 64 20 66 72 6f 6d 20 74 68 65 20 72  moted from the r
15c00 65 6c 61 74 69 76 65 6c 79 20 62 65 6e 69 67 6e  elatively benign
15c10 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 74   [SQLITE_BUSY] t
15c20 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72 65 20 73 65  o.** the more se
15c30 76 65 72 65 20 5b 53 51 4c 49 54 45 5f 49 4f 45  vere [SQLITE_IOE
15c40 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 20 20 5e 54  RR_BLOCKED].  ^T
15c50 68 69 73 20 65 72 72 6f 72 20 63 6f 64 65 20 70  his error code p
15c60 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20 66 6f 72 63  romotion.** forc
15c70 65 73 20 61 6e 20 61 75 74 6f 6d 61 74 69 63 20  es an automatic 
15c80 72 6f 6c 6c 62 61 63 6b 20 6f 66 20 74 68 65 20  rollback of the 
15c90 63 68 61 6e 67 65 73 2e 20 20 53 65 65 20 74 68  changes.  See th
15ca0 65 0a 2a 2a 20 3c 61 20 68 72 65 66 3d 22 2f 63  e.** <a href="/c
15cb0 76 73 74 72 61 63 2f 77 69 6b 69 3f 70 3d 43 6f  vstrac/wiki?p=Co
15cc0 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77 69 6e  rruptionFollowin
15cd0 67 42 75 73 79 45 72 72 6f 72 22 3e 0a 2a 2a 20  gBusyError">.** 
15ce0 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c 6f 77  CorruptionFollow
15cf0 69 6e 67 42 75 73 79 45 72 72 6f 72 3c 2f 61 3e  ingBusyError</a>
15d00 20 77 69 6b 69 20 70 61 67 65 20 66 6f 72 20 61   wiki page for a
15d10 20 64 69 73 63 75 73 73 69 6f 6e 20 6f 66 20 77   discussion of w
15d20 68 79 0a 2a 2a 20 74 68 69 73 20 69 73 20 69 6d  hy.** this is im
15d30 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e  portant..**.** ^
15d40 28 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20  (There can only 
15d50 62 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79  be a single busy
15d60 20 68 61 6e 64 6c 65 72 20 64 65 66 69 6e 65 64   handler defined
15d70 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 5b 64 61   for each.** [da
15d80 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
15d90 6e 5d 2e 20 20 53 65 74 74 69 6e 67 20 61 20 6e  n].  Setting a n
15da0 65 77 20 62 75 73 79 20 68 61 6e 64 6c 65 72 20  ew busy handler 
15db0 63 6c 65 61 72 73 20 61 6e 79 0a 2a 2a 20 70 72  clears any.** pr
15dc0 65 76 69 6f 75 73 6c 79 20 73 65 74 20 68 61 6e  eviously set han
15dd0 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f 74 65 20 74  dler.)^  ^Note t
15de0 68 61 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  hat calling [sql
15df0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
15e00 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c 20 61 6c 73  t()].** will als
15e10 6f 20 73 65 74 20 6f 72 20 63 6c 65 61 72 20 74  o set or clear t
15e20 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e  he busy handler.
15e30 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62 75 73 79 20  .**.** The busy 
15e40 63 61 6c 6c 62 61 63 6b 20 73 68 6f 75 6c 64 20  callback should 
15e50 6e 6f 74 20 74 61 6b 65 20 61 6e 79 20 61 63 74  not take any act
15e60 69 6f 6e 73 20 77 68 69 63 68 20 6d 6f 64 69 66  ions which modif
15e70 79 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  y the.** databas
15e80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
15e90 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75  t invoked the bu
15ea0 73 79 20 68 61 6e 64 6c 65 72 2e 20 20 41 6e 79  sy handler.  Any
15eb0 20 73 75 63 68 20 61 63 74 69 6f 6e 73 0a 2a 2a   such actions.**
15ec0 20 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66   result in undef
15ed0 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a 2a  ined behavior..*
15ee0 2a 20 0a 2a 2a 20 41 20 62 75 73 79 20 68 61 6e  * .** A busy han
15ef0 64 6c 65 72 20 6d 75 73 74 20 6e 6f 74 20 63 6c  dler must not cl
15f00 6f 73 65 20 74 68 65 20 64 61 74 61 62 61 73 65  ose the database
15f10 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f   connection.** o
15f20 72 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  r [prepared stat
15f30 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 6e 76 6f  ement] that invo
15f40 6b 65 64 20 74 68 65 20 62 75 73 79 20 68 61 6e  ked the busy han
15f50 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  dler..*/.int sql
15f60 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
15f70 72 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 28  r(sqlite3*, int(
15f80 2a 29 28 76 6f 69 64 2a 2c 69 6e 74 29 2c 20 76  *)(void*,int), v
15f90 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  oid*);../*.** CA
15fa0 50 49 33 52 45 46 3a 20 53 65 74 20 41 20 42 75  PI3REF: Set A Bu
15fb0 73 79 20 54 69 6d 65 6f 75 74 0a 2a 2a 0a 2a 2a  sy Timeout.**.**
15fc0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 73   ^This routine s
15fd0 65 74 73 20 61 20 5b 73 71 6c 69 74 65 33 5f 62  ets a [sqlite3_b
15fe0 75 73 79 5f 68 61 6e 64 6c 65 72 20 7c 20 62 75  usy_handler | bu
15ff0 73 79 20 68 61 6e 64 6c 65 72 5d 20 74 68 61 74  sy handler] that
16000 20 73 6c 65 65 70 73 0a 2a 2a 20 66 6f 72 20 61   sleeps.** for a
16010 20 73 70 65 63 69 66 69 65 64 20 61 6d 6f 75 6e   specified amoun
16020 74 20 6f 66 20 74 69 6d 65 20 77 68 65 6e 20 61  t of time when a
16030 20 74 61 62 6c 65 20 69 73 20 6c 6f 63 6b 65 64   table is locked
16040 2e 20 20 5e 54 68 65 20 68 61 6e 64 6c 65 72 0a  .  ^The handler.
16050 2a 2a 20 77 69 6c 6c 20 73 6c 65 65 70 20 6d 75  ** will sleep mu
16060 6c 74 69 70 6c 65 20 74 69 6d 65 73 20 75 6e 74  ltiple times unt
16070 69 6c 20 61 74 20 6c 65 61 73 74 20 22 6d 73 22  il at least "ms"
16080 20 6d 69 6c 6c 69 73 65 63 6f 6e 64 73 20 6f 66   milliseconds of
16090 20 73 6c 65 65 70 69 6e 67 0a 2a 2a 20 68 61 76   sleeping.** hav
160a0 65 20 61 63 63 75 6d 75 6c 61 74 65 64 2e 20 20  e accumulated.  
160b0 5e 41 66 74 65 72 20 61 74 20 6c 65 61 73 74 20  ^After at least 
160c0 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
160d0 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 2c 0a 2a  s of sleeping,.*
160e0 2a 20 74 68 65 20 68 61 6e 64 6c 65 72 20 72 65  * the handler re
160f0 74 75 72 6e 73 20 30 20 77 68 69 63 68 20 63 61  turns 0 which ca
16100 75 73 65 73 20 5b 73 71 6c 69 74 65 33 5f 73 74  uses [sqlite3_st
16110 65 70 28 29 5d 20 74 6f 20 72 65 74 75 72 6e 0a  ep()] to return.
16120 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  ** [SQLITE_BUSY]
16130 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52   or [SQLITE_IOER
16140 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a 2a 2a 0a 2a  R_BLOCKED]..**.*
16150 2a 20 5e 43 61 6c 6c 69 6e 67 20 74 68 69 73 20  * ^Calling this 
16160 72 6f 75 74 69 6e 65 20 77 69 74 68 20 61 6e 20  routine with an 
16170 61 72 67 75 6d 65 6e 74 20 6c 65 73 73 20 74 68  argument less th
16180 61 6e 20 6f 72 20 65 71 75 61 6c 20 74 6f 20 7a  an or equal to z
16190 65 72 6f 0a 2a 2a 20 74 75 72 6e 73 20 6f 66 66  ero.** turns off
161a0 20 61 6c 6c 20 62 75 73 79 20 68 61 6e 64 6c 65   all busy handle
161b0 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 72  rs..**.** ^(Ther
161c0 65 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20 61 20  e can only be a 
161d0 73 69 6e 67 6c 65 20 62 75 73 79 20 68 61 6e 64  single busy hand
161e0 6c 65 72 20 66 6f 72 20 61 20 70 61 72 74 69 63  ler for a partic
161f0 75 6c 61 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73  ular.** [databas
16200 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 61 6e  e connection] an
16210 79 20 61 6e 79 20 67 69 76 65 6e 20 6d 6f 6d 65  y any given mome
16220 6e 74 2e 20 20 49 66 20 61 6e 6f 74 68 65 72 20  nt.  If another 
16230 62 75 73 79 20 68 61 6e 64 6c 65 72 0a 2a 2a 20  busy handler.** 
16240 77 61 73 20 64 65 66 69 6e 65 64 20 20 28 75 73  was defined  (us
16250 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 62 75 73  ing [sqlite3_bus
16260 79 5f 68 61 6e 64 6c 65 72 28 29 5d 29 20 70 72  y_handler()]) pr
16270 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a  ior to calling.*
16280 2a 20 74 68 69 73 20 72 6f 75 74 69 6e 65 2c 20  * this routine, 
16290 74 68 61 74 20 6f 74 68 65 72 20 62 75 73 79 20  that other busy 
162a0 68 61 6e 64 6c 65 72 20 69 73 20 63 6c 65 61 72  handler is clear
162b0 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ed.)^.*/.int sql
162c0 69 74 65 33 5f 62 75 73 79 5f 74 69 6d 65 6f 75  ite3_busy_timeou
162d0 74 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  t(sqlite3*, int 
162e0 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ms);../*.** CAPI
162f0 33 52 45 46 3a 20 43 6f 6e 76 65 6e 69 65 6e 63  3REF: Convenienc
16300 65 20 52 6f 75 74 69 6e 65 73 20 46 6f 72 20 52  e Routines For R
16310 75 6e 6e 69 6e 67 20 51 75 65 72 69 65 73 0a 2a  unning Queries.*
16320 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20 61 20 6c  *.** This is a l
16330 65 67 61 63 79 20 69 6e 74 65 72 66 61 63 65 20  egacy interface 
16340 74 68 61 74 20 69 73 20 70 72 65 73 65 72 76 65  that is preserve
16350 64 20 66 6f 72 20 62 61 63 6b 77 61 72 64 73 20  d for backwards 
16360 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a  compatibility..*
16370 2a 20 55 73 65 20 6f 66 20 74 68 69 73 20 69 6e  * Use of this in
16380 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20 72  terface is not r
16390 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a 2a 2a 0a 2a  ecommended..**.*
163a0 2a 20 44 65 66 69 6e 69 74 69 6f 6e 3a 20 41 20  * Definition: A 
163b0 3c 62 3e 72 65 73 75 6c 74 20 74 61 62 6c 65 3c  <b>result table<
163c0 2f 62 3e 20 69 73 20 6d 65 6d 6f 72 79 20 64 61  /b> is memory da
163d0 74 61 20 73 74 72 75 63 74 75 72 65 20 63 72 65  ta structure cre
163e0 61 74 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 5b  ated by the.** [
163f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
16400 65 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 20  e()] interface. 
16410 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20   A result table 
16420 72 65 63 6f 72 64 73 20 74 68 65 0a 2a 2a 20 63  records the.** c
16430 6f 6d 70 6c 65 74 65 20 71 75 65 72 79 20 72 65  omplete query re
16440 73 75 6c 74 73 20 66 72 6f 6d 20 6f 6e 65 20 6f  sults from one o
16450 72 20 6d 6f 72 65 20 71 75 65 72 69 65 73 2e 0a  r more queries..
16460 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c 65 20  **.** The table 
16470 63 6f 6e 63 65 70 74 75 61 6c 6c 79 20 68 61 73  conceptually has
16480 20 61 20 6e 75 6d 62 65 72 20 6f 66 20 72 6f 77   a number of row
16490 73 20 61 6e 64 20 63 6f 6c 75 6d 6e 73 2e 20 20  s and columns.  
164a0 42 75 74 0a 2a 2a 20 74 68 65 73 65 20 6e 75 6d  But.** these num
164b0 62 65 72 73 20 61 72 65 20 6e 6f 74 20 70 61 72  bers are not par
164c0 74 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  t of the result 
164d0 74 61 62 6c 65 20 69 74 73 65 6c 66 2e 20 20 54  table itself.  T
164e0 68 65 73 65 0a 2a 2a 20 6e 75 6d 62 65 72 73 20  hese.** numbers 
164f0 61 72 65 20 6f 62 74 61 69 6e 65 64 20 73 65 70  are obtained sep
16500 61 72 61 74 65 6c 79 2e 20 20 4c 65 74 20 4e 20  arately.  Let N 
16510 62 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  be the number of
16520 20 72 6f 77 73 0a 2a 2a 20 61 6e 64 20 4d 20 62   rows.** and M b
16530 65 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20  e the number of 
16540 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a 2a 2a 20 41  columns..**.** A
16550 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 69 73   result table is
16560 20 61 6e 20 61 72 72 61 79 20 6f 66 20 70 6f 69   an array of poi
16570 6e 74 65 72 73 20 74 6f 20 7a 65 72 6f 2d 74 65  nters to zero-te
16580 72 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 20 73  rminated UTF-8 s
16590 74 72 69 6e 67 73 2e 0a 2a 2a 20 54 68 65 72 65  trings..** There
165a0 20 61 72 65 20 28 4e 2b 31 29 2a 4d 20 65 6c 65   are (N+1)*M ele
165b0 6d 65 6e 74 73 20 69 6e 20 74 68 65 20 61 72 72  ments in the arr
165c0 61 79 2e 20 20 54 68 65 20 66 69 72 73 74 20 4d  ay.  The first M
165d0 20 70 6f 69 6e 74 65 72 73 20 70 6f 69 6e 74 0a   pointers point.
165e0 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74 65 72 6d 69  ** to zero-termi
165f0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
16600 61 74 20 20 63 6f 6e 74 61 69 6e 20 74 68 65 20  at  contain the 
16610 6e 61 6d 65 73 20 6f 66 20 74 68 65 20 63 6f 6c  names of the col
16620 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65 20 72 65 6d  umns..** The rem
16630 61 69 6e 69 6e 67 20 65 6e 74 72 69 65 73 20 61  aining entries a
16640 6c 6c 20 70 6f 69 6e 74 20 74 6f 20 71 75 65 72  ll point to quer
16650 79 20 72 65 73 75 6c 74 73 2e 20 20 4e 55 4c 4c  y results.  NULL
16660 20 76 61 6c 75 65 73 20 72 65 73 75 6c 74 0a 2a   values result.*
16670 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  * in NULL pointe
16680 72 73 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 76  rs.  All other v
16690 61 6c 75 65 73 20 61 72 65 20 69 6e 20 74 68 65  alues are in the
166a0 69 72 20 55 54 46 2d 38 20 7a 65 72 6f 2d 74 65  ir UTF-8 zero-te
166b0 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69  rminated.** stri
166c0 6e 67 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f  ng representatio
166d0 6e 20 61 73 20 72 65 74 75 72 6e 65 64 20 62 79  n as returned by
166e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
166f0 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  _text()]..**.** 
16700 41 20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 6d  A result table m
16710 69 67 68 74 20 63 6f 6e 73 69 73 74 20 6f 66 20  ight consist of 
16720 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 6d 65 6d 6f  one or more memo
16730 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 0a  ry allocations..
16740 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
16750 65 20 74 6f 20 70 61 73 73 20 61 20 72 65 73 75  e to pass a resu
16760 6c 74 20 74 61 62 6c 65 20 64 69 72 65 63 74 6c  lt table directl
16770 79 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 66 72  y to [sqlite3_fr
16780 65 65 28 29 5d 2e 0a 2a 2a 20 41 20 72 65 73 75  ee()]..** A resu
16790 6c 74 20 74 61 62 6c 65 20 73 68 6f 75 6c 64 20  lt table should 
167a0 62 65 20 64 65 61 6c 6c 6f 63 61 74 65 64 20 75  be deallocated u
167b0 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 72  sing [sqlite3_fr
167c0 65 65 5f 74 61 62 6c 65 28 29 5d 2e 0a 2a 2a 0a  ee_table()]..**.
167d0 2a 2a 20 5e 28 41 73 20 61 6e 20 65 78 61 6d 70  ** ^(As an examp
167e0 6c 65 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74  le of the result
167f0 20 74 61 62 6c 65 20 66 6f 72 6d 61 74 2c 20 73   table format, s
16800 75 70 70 6f 73 65 20 61 20 71 75 65 72 79 20 72  uppose a query r
16810 65 73 75 6c 74 0a 2a 2a 20 69 73 20 61 73 20 66  esult.** is as f
16820 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62  ollows:.**.** <b
16830 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a  lockquote><pre>.
16840 2a 2a 20 20 20 20 20 20 20 20 4e 61 6d 65 20 20  **        Name  
16850 20 20 20 20 20 20 7c 20 41 67 65 0a 2a 2a 20 20        | Age.**  
16860 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d        ----------
16870 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 0a 2a 2a  -------------.**
16880 20 20 20 20 20 20 20 20 41 6c 69 63 65 20 20 20          Alice   
16890 20 20 20 20 7c 20 34 33 0a 2a 2a 20 20 20 20 20      | 43.**     
168a0 20 20 20 42 6f 62 20 20 20 20 20 20 20 20 20 7c     Bob         |
168b0 20 32 38 0a 2a 2a 20 20 20 20 20 20 20 20 43 69   28.**        Ci
168c0 6e 64 79 20 20 20 20 20 20 20 7c 20 32 31 0a 2a  ndy       | 21.*
168d0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
168e0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 72  uote>.**.** Ther
168f0 65 20 61 72 65 20 74 77 6f 20 63 6f 6c 75 6d 6e  e are two column
16900 20 28 4d 3d 3d 32 29 20 61 6e 64 20 74 68 72 65   (M==2) and thre
16910 65 20 72 6f 77 73 20 28 4e 3d 3d 33 29 2e 20 20  e rows (N==3).  
16920 54 68 75 73 20 74 68 65 0a 2a 2a 20 72 65 73 75  Thus the.** resu
16930 6c 74 20 74 61 62 6c 65 20 68 61 73 20 38 20 65  lt table has 8 e
16940 6e 74 72 69 65 73 2e 20 20 53 75 70 70 6f 73 65  ntries.  Suppose
16950 20 74 68 65 20 72 65 73 75 6c 74 20 74 61 62 6c   the result tabl
16960 65 20 69 73 20 73 74 6f 72 65 64 0a 2a 2a 20 69  e is stored.** i
16970 6e 20 61 6e 20 61 72 72 61 79 20 6e 61 6d 65 73  n an array names
16980 20 61 7a 52 65 73 75 6c 74 2e 20 20 54 68 65 6e   azResult.  Then
16990 20 61 7a 52 65 73 75 6c 74 20 68 6f 6c 64 73 20   azResult holds 
169a0 74 68 69 73 20 63 6f 6e 74 65 6e 74 3a 0a 2a 2a  this content:.**
169b0 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e  .** <blockquote>
169c0 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20  <pre>.**        
169d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 30 5d 20  azResult&#91;0] 
169e0 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a 20 20 20 20  = "Name";.**    
169f0 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16a00 3b 31 5d 20 3d 20 22 41 67 65 22 3b 0a 2a 2a 20  ;1] = "Age";.** 
16a10 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16a20 23 39 31 3b 32 5d 20 3d 20 22 41 6c 69 63 65 22  #91;2] = "Alice"
16a30 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
16a40 73 75 6c 74 26 23 39 31 3b 33 5d 20 3d 20 22 34  sult&#91;3] = "4
16a50 33 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a  3";.**        az
16a60 52 65 73 75 6c 74 26 23 39 31 3b 34 5d 20 3d 20  Result&#91;4] = 
16a70 22 42 6f 62 22 3b 0a 2a 2a 20 20 20 20 20 20 20  "Bob";.**       
16a80 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 35 5d   azResult&#91;5]
16a90 20 3d 20 22 32 38 22 3b 0a 2a 2a 20 20 20 20 20   = "28";.**     
16aa0 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b     azResult&#91;
16ab0 36 5d 20 3d 20 22 43 69 6e 64 79 22 3b 0a 2a 2a  6] = "Cindy";.**
16ac0 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
16ad0 26 23 39 31 3b 37 5d 20 3d 20 22 32 31 22 3b 0a  &#91;7] = "21";.
16ae0 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b  ** </pre></block
16af0 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  quote>)^.**.** ^
16b00 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  The sqlite3_get_
16b10 74 61 62 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  table() function
16b20 20 65 76 61 6c 75 61 74 65 73 20 6f 6e 65 20 6f   evaluates one o
16b30 72 20 6d 6f 72 65 0a 2a 2a 20 73 65 6d 69 63 6f  r more.** semico
16b40 6c 6f 6e 2d 73 65 70 61 72 61 74 65 64 20 53 51  lon-separated SQ
16b50 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 69 6e 20  L statements in 
16b60 74 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61  the zero-termina
16b70 74 65 64 20 55 54 46 2d 38 0a 2a 2a 20 73 74 72  ted UTF-8.** str
16b80 69 6e 67 20 6f 66 20 69 74 73 20 32 6e 64 20 70  ing of its 2nd p
16b90 61 72 61 6d 65 74 65 72 20 61 6e 64 20 72 65 74  arameter and ret
16ba0 75 72 6e 73 20 61 20 72 65 73 75 6c 74 20 74 61  urns a result ta
16bb0 62 6c 65 20 74 6f 20 74 68 65 0a 2a 2a 20 70 6f  ble to the.** po
16bc0 69 6e 74 65 72 20 67 69 76 65 6e 20 69 6e 20 69  inter given in i
16bd0 74 73 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  ts 3rd parameter
16be0 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 74 68  ..**.** After th
16bf0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 68 61  e application ha
16c00 73 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20  s finished with 
16c10 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d 20  the result from 
16c20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
16c30 65 28 29 2c 0a 2a 2a 20 69 74 20 6d 75 73 74 20  e(),.** it must 
16c40 70 61 73 73 20 74 68 65 20 72 65 73 75 6c 74 20  pass the result 
16c50 74 61 62 6c 65 20 70 6f 69 6e 74 65 72 20 74 6f  table pointer to
16c60 20 73 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61   sqlite3_free_ta
16c70 62 6c 65 28 29 20 69 6e 20 6f 72 64 65 72 20 74  ble() in order t
16c80 6f 0a 2a 2a 20 72 65 6c 65 61 73 65 20 74 68 65  o.** release the
16c90 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 77 61 73   memory that was
16ca0 20 6d 61 6c 6c 6f 63 65 64 2e 20 20 42 65 63 61   malloced.  Beca
16cb0 75 73 65 20 6f 66 20 74 68 65 20 77 61 79 20 74  use of the way t
16cc0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  he.** [sqlite3_m
16cd0 61 6c 6c 6f 63 28 29 5d 20 68 61 70 70 65 6e 73  alloc()] happens
16ce0 20 77 69 74 68 69 6e 20 73 71 6c 69 74 65 33 5f   within sqlite3_
16cf0 67 65 74 5f 74 61 62 6c 65 28 29 2c 20 74 68 65  get_table(), the
16d00 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 66 75 6e 63   calling.** func
16d10 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 74 72  tion must not tr
16d20 79 20 74 6f 20 63 61 6c 6c 20 5b 73 71 6c 69 74  y to call [sqlit
16d30 65 33 5f 66 72 65 65 28 29 5d 20 64 69 72 65 63  e3_free()] direc
16d40 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a 2a 20 5b 73  tly.  Only.** [s
16d50 71 6c 69 74 65 33 5f 66 72 65 65 5f 74 61 62 6c  qlite3_free_tabl
16d60 65 28 29 5d 20 69 73 20 61 62 6c 65 20 74 6f 20  e()] is able to 
16d70 72 65 6c 65 61 73 65 20 74 68 65 20 6d 65 6d 6f  release the memo
16d80 72 79 20 70 72 6f 70 65 72 6c 79 20 61 6e 64 20  ry properly and 
16d90 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 54 68  safely..**.** Th
16da0 65 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61  e sqlite3_get_ta
16db0 62 6c 65 28 29 20 69 6e 74 65 72 66 61 63 65 20  ble() interface 
16dc0 69 73 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61  is implemented a
16dd0 73 20 61 20 77 72 61 70 70 65 72 20 61 72 6f 75  s a wrapper arou
16de0 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65  nd.** [sqlite3_e
16df0 78 65 63 28 29 5d 2e 20 20 54 68 65 20 73 71 6c  xec()].  The sql
16e00 69 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29  ite3_get_table()
16e10 20 72 6f 75 74 69 6e 65 20 64 6f 65 73 20 6e 6f   routine does no
16e20 74 20 68 61 76 65 20 61 63 63 65 73 73 0a 2a 2a  t have access.**
16e30 20 74 6f 20 61 6e 79 20 69 6e 74 65 72 6e 61 6c   to any internal
16e40 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65 73   data structures
16e50 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 49 74 20   of SQLite.  It 
16e60 75 73 65 73 20 6f 6e 6c 79 20 74 68 65 20 70 75  uses only the pu
16e70 62 6c 69 63 0a 2a 2a 20 69 6e 74 65 72 66 61 63  blic.** interfac
16e80 65 20 64 65 66 69 6e 65 64 20 68 65 72 65 2e 20  e defined here. 
16e90 20 41 73 20 61 20 63 6f 6e 73 65 71 75 65 6e 63   As a consequenc
16ea0 65 2c 20 65 72 72 6f 72 73 20 74 68 61 74 20 6f  e, errors that o
16eb0 63 63 75 72 20 69 6e 20 74 68 65 0a 2a 2a 20 77  ccur in the.** w
16ec0 72 61 70 70 65 72 20 6c 61 79 65 72 20 6f 75 74  rapper layer out
16ed0 73 69 64 65 20 6f 66 20 74 68 65 20 69 6e 74 65  side of the inte
16ee0 72 6e 61 6c 20 5b 73 71 6c 69 74 65 33 5f 65 78  rnal [sqlite3_ex
16ef0 65 63 28 29 5d 20 63 61 6c 6c 20 61 72 65 20 6e  ec()] call are n
16f00 6f 74 0a 2a 2a 20 72 65 66 6c 65 63 74 65 64 20  ot.** reflected 
16f10 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
16f20 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  lls to [sqlite3_
16f30 65 72 72 63 6f 64 65 28 29 5d 20 6f 72 0a 2a 2a  errcode()] or.**
16f40 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
16f50 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
16f60 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 0a 20  te3_get_table(. 
16f70 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
16f80 20 20 20 20 20 20 20 2f 2a 20 41 6e 20 6f 70 65         /* An ope
16f90 6e 20 64 61 74 61 62 61 73 65 20 2a 2f 0a 20 20  n database */.  
16fa0 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
16fb0 2c 20 20 20 20 20 2f 2a 20 53 51 4c 20 74 6f 20  ,     /* SQL to 
16fc0 62 65 20 65 76 61 6c 75 61 74 65 64 20 2a 2f 0a  be evaluated */.
16fd0 20 20 63 68 61 72 20 2a 2a 2a 70 61 7a 52 65 73    char ***pazRes
16fe0 75 6c 74 2c 20 20 20 20 2f 2a 20 52 65 73 75 6c  ult,    /* Resul
16ff0 74 73 20 6f 66 20 74 68 65 20 71 75 65 72 79 20  ts of the query 
17000 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 52 6f 77 2c  */.  int *pnRow,
17010 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
17020 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20 72  mber of result r
17030 6f 77 73 20 77 72 69 74 74 65 6e 20 68 65 72 65  ows written here
17040 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e 43 6f 6c   */.  int *pnCol
17050 75 6d 6e 2c 20 20 20 20 20 20 20 20 2f 2a 20 4e  umn,        /* N
17060 75 6d 62 65 72 20 6f 66 20 72 65 73 75 6c 74 20  umber of result 
17070 63 6f 6c 75 6d 6e 73 20 77 72 69 74 74 65 6e 20  columns written 
17080 68 65 72 65 20 2a 2f 0a 20 20 63 68 61 72 20 2a  here */.  char *
17090 2a 70 7a 45 72 72 6d 73 67 20 20 20 20 20 20 20  *pzErrmsg       
170a0 2f 2a 20 45 72 72 6f 72 20 6d 73 67 20 77 72 69  /* Error msg wri
170b0 74 74 65 6e 20 68 65 72 65 20 2a 2f 0a 29 3b 0a  tten here */.);.
170c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65  void sqlite3_fre
170d0 65 5f 74 61 62 6c 65 28 63 68 61 72 20 2a 2a 72  e_table(char **r
170e0 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  esult);../*.** C
170f0 41 50 49 33 52 45 46 3a 20 46 6f 72 6d 61 74 74  API3REF: Formatt
17100 65 64 20 53 74 72 69 6e 67 20 50 72 69 6e 74 69  ed String Printi
17110 6e 67 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a 0a  ng Functions.**.
17120 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65  ** These routine
17130 73 20 61 72 65 20 77 6f 72 6b 2d 61 6c 69 6b 65  s are work-alike
17140 73 20 6f 66 20 74 68 65 20 22 70 72 69 6e 74 66  s of the "printf
17150 28 29 22 20 66 61 6d 69 6c 79 20 6f 66 20 66 75  ()" family of fu
17160 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66 72 6f 6d 20  nctions.** from 
17170 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c  the standard C l
17180 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ibrary..**.** ^T
17190 68 65 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e  he sqlite3_mprin
171a0 74 66 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  tf() and sqlite3
171b0 5f 76 6d 70 72 69 6e 74 66 28 29 20 72 6f 75 74  _vmprintf() rout
171c0 69 6e 65 73 20 77 72 69 74 65 20 74 68 65 69 72  ines write their
171d0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
171e0 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65 64   memory obtained
171f0 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 6d   from [sqlite3_m
17200 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a 20 54 68 65  alloc()]..** The
17210 20 73 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65   strings returne
17220 64 20 62 79 20 74 68 65 73 65 20 74 77 6f 20 72  d by these two r
17230 6f 75 74 69 6e 65 73 20 73 68 6f 75 6c 64 20 62  outines should b
17240 65 0a 2a 2a 20 72 65 6c 65 61 73 65 64 20 62 79  e.** released by
17250 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
17260 5d 2e 20 20 5e 42 6f 74 68 20 72 6f 75 74 69 6e  ].  ^Both routin
17270 65 73 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 4e  es return a.** N
17280 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 66 20 5b  ULL pointer if [
17290 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
172a0 5d 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61  ] is unable to a
172b0 6c 6c 6f 63 61 74 65 20 65 6e 6f 75 67 68 0a 2a  llocate enough.*
172c0 2a 20 6d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  * memory to hold
172d0 20 74 68 65 20 72 65 73 75 6c 74 69 6e 67 20 73   the resulting s
172e0 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  tring..**.** ^(T
172f0 68 65 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69  he sqlite3_snpri
17300 6e 74 66 28 29 20 72 6f 75 74 69 6e 65 20 69 73  ntf() routine is
17310 20 73 69 6d 69 6c 61 72 20 74 6f 20 22 73 6e 70   similar to "snp
17320 72 69 6e 74 66 28 29 22 20 66 72 6f 6d 0a 2a 2a  rintf()" from.**
17330 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
17340 6c 69 62 72 61 72 79 2e 20 20 54 68 65 20 72 65  library.  The re
17350 73 75 6c 74 20 69 73 20 77 72 69 74 74 65 6e 20  sult is written 
17360 69 6e 74 6f 20 74 68 65 0a 2a 2a 20 62 75 66 66  into the.** buff
17370 65 72 20 73 75 70 70 6c 69 65 64 20 61 73 20 74  er supplied as t
17380 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
17390 74 65 72 20 77 68 6f 73 65 20 73 69 7a 65 20 69  ter whose size i
173a0 73 20 67 69 76 65 6e 20 62 79 0a 2a 2a 20 74 68  s given by.** th
173b0 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
173c0 72 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65  r. Note that the
173d0 20 6f 72 64 65 72 20 6f 66 20 74 68 65 0a 2a 2a   order of the.**
173e0 20 66 69 72 73 74 20 74 77 6f 20 70 61 72 61 6d   first two param
173f0 65 74 65 72 73 20 69 73 20 72 65 76 65 72 73 65  eters is reverse
17400 64 20 66 72 6f 6d 20 73 6e 70 72 69 6e 74 66 28  d from snprintf(
17410 29 2e 29 5e 20 20 54 68 69 73 20 69 73 20 61 6e  ).)^  This is an
17420 0a 2a 2a 20 68 69 73 74 6f 72 69 63 61 6c 20 61  .** historical a
17430 63 63 69 64 65 6e 74 20 74 68 61 74 20 63 61 6e  ccident that can
17440 6e 6f 74 20 62 65 20 66 69 78 65 64 20 77 69 74  not be fixed wit
17450 68 6f 75 74 20 62 72 65 61 6b 69 6e 67 0a 2a 2a  hout breaking.**
17460 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70 61   backwards compa
17470 74 69 62 69 6c 69 74 79 2e 20 20 5e 28 4e 6f 74  tibility.  ^(Not
17480 65 20 61 6c 73 6f 20 74 68 61 74 20 73 71 6c 69  e also that sqli
17490 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29 0a 2a  te3_snprintf().*
174a0 2a 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  * returns a poin
174b0 74 65 72 20 74 6f 20 69 74 73 20 62 75 66 66 65  ter to its buffe
174c0 72 20 69 6e 73 74 65 61 64 20 6f 66 20 74 68 65  r instead of the
174d0 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 63 68   number of.** ch
174e0 61 72 61 63 74 65 72 73 20 61 63 74 75 61 6c 6c  aracters actuall
174f0 79 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 74  y written into t
17500 68 65 20 62 75 66 66 65 72 2e 29 5e 20 20 57 65  he buffer.)^  We
17510 20 61 64 6d 69 74 20 74 68 61 74 0a 2a 2a 20 74   admit that.** t
17520 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  he number of cha
17530 72 61 63 74 65 72 73 20 77 72 69 74 74 65 6e 20  racters written 
17540 77 6f 75 6c 64 20 62 65 20 61 20 6d 6f 72 65 20  would be a more 
17550 75 73 65 66 75 6c 20 72 65 74 75 72 6e 0a 2a 2a  useful return.**
17560 20 76 61 6c 75 65 20 62 75 74 20 77 65 20 63 61   value but we ca
17570 6e 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20  nnot change the 
17580 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
17590 66 20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e  f sqlite3_snprin
175a0 74 66 28 29 0a 2a 2a 20 6e 6f 77 20 77 69 74 68  tf().** now with
175b0 6f 75 74 20 62 72 65 61 6b 69 6e 67 20 63 6f 6d  out breaking com
175c0 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2a 0a 2a  patibility..**.*
175d0 2a 20 5e 41 73 20 6c 6f 6e 67 20 61 73 20 74 68  * ^As long as th
175e0 65 20 62 75 66 66 65 72 20 73 69 7a 65 20 69 73  e buffer size is
175f0 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 7a 65   greater than ze
17600 72 6f 2c 20 73 71 6c 69 74 65 33 5f 73 6e 70 72  ro, sqlite3_snpr
17610 69 6e 74 66 28 29 0a 2a 2a 20 67 75 61 72 61 6e  intf().** guaran
17620 74 65 65 73 20 74 68 61 74 20 74 68 65 20 62 75  tees that the bu
17630 66 66 65 72 20 69 73 20 61 6c 77 61 79 73 20 7a  ffer is always z
17640 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 2e 20  ero-terminated. 
17650 20 5e 54 68 65 20 66 69 72 73 74 0a 2a 2a 20 70   ^The first.** p
17660 61 72 61 6d 65 74 65 72 20 22 6e 22 20 69 73 20  arameter "n" is 
17670 74 68 65 20 74 6f 74 61 6c 20 73 69 7a 65 20 6f  the total size o
17680 66 20 74 68 65 20 62 75 66 66 65 72 2c 20 69 6e  f the buffer, in
17690 63 6c 75 64 69 6e 67 20 73 70 61 63 65 20 66 6f  cluding space fo
176a0 72 0a 2a 2a 20 74 68 65 20 7a 65 72 6f 20 74 65  r.** the zero te
176b0 72 6d 69 6e 61 74 6f 72 2e 20 20 53 6f 20 74 68  rminator.  So th
176c0 65 20 6c 6f 6e 67 65 73 74 20 73 74 72 69 6e 67  e longest string
176d0 20 74 68 61 74 20 63 61 6e 20 62 65 20 63 6f 6d   that can be com
176e0 70 6c 65 74 65 6c 79 0a 2a 2a 20 77 72 69 74 74  pletely.** writt
176f0 65 6e 20 77 69 6c 6c 20 62 65 20 6e 2d 31 20 63  en will be n-1 c
17700 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
17710 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76 73   ^The sqlite3_vs
17720 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
17730 65 20 69 73 20 61 20 76 61 72 61 72 67 73 20 76  e is a varargs v
17740 65 72 73 69 6f 6e 20 6f 66 20 73 71 6c 69 74 65  ersion of sqlite
17750 33 5f 73 6e 70 72 69 6e 74 66 28 29 2e 0a 2a 2a  3_snprintf()..**
17760 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
17770 65 73 20 61 6c 6c 20 69 6d 70 6c 65 6d 65 6e 74  es all implement
17780 20 73 6f 6d 65 20 61 64 64 69 74 69 6f 6e 61 6c   some additional
17790 20 66 6f 72 6d 61 74 74 69 6e 67 0a 2a 2a 20 6f   formatting.** o
177a0 70 74 69 6f 6e 73 20 74 68 61 74 20 61 72 65 20  ptions that are 
177b0 75 73 65 66 75 6c 20 66 6f 72 20 63 6f 6e 73 74  useful for const
177c0 72 75 63 74 69 6e 67 20 53 51 4c 20 73 74 61 74  ructing SQL stat
177d0 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41 6c 6c 20 6f  ements..** All o
177e0 66 20 74 68 65 20 75 73 75 61 6c 20 70 72 69 6e  f the usual prin
177f0 74 66 28 29 20 66 6f 72 6d 61 74 74 69 6e 67 20  tf() formatting 
17800 6f 70 74 69 6f 6e 73 20 61 70 70 6c 79 2e 20 20  options apply.  
17810 49 6e 20 61 64 64 69 74 69 6f 6e 2c 20 74 68 65  In addition, the
17820 72 65 0a 2a 2a 20 69 73 20 61 72 65 20 22 25 71  re.** is are "%q
17830 22 2c 20 22 25 51 22 2c 20 61 6e 64 20 22 25 7a  ", "%Q", and "%z
17840 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a  " options..**.**
17850 20 5e 28 54 68 65 20 25 71 20 6f 70 74 69 6f 6e   ^(The %q option
17860 20 77 6f 72 6b 73 20 6c 69 6b 65 20 25 73 20 69   works like %s i
17870 6e 20 74 68 61 74 20 69 74 20 73 75 62 73 74 69  n that it substi
17880 74 75 74 65 73 20 61 20 6e 75 6c 6c 2d 74 65 72  tutes a null-ter
17890 6d 69 6e 61 74 65 64 0a 2a 2a 20 73 74 72 69 6e  minated.** strin
178a0 67 20 66 72 6f 6d 20 74 68 65 20 61 72 67 75 6d  g from the argum
178b0 65 6e 74 20 6c 69 73 74 2e 20 20 42 75 74 20 25  ent list.  But %
178c0 71 20 61 6c 73 6f 20 64 6f 75 62 6c 65 73 20 65  q also doubles e
178d0 76 65 72 79 20 27 5c 27 27 20 63 68 61 72 61 63  very '\'' charac
178e0 74 65 72 2e 0a 2a 2a 20 25 71 20 69 73 20 64 65  ter..** %q is de
178f0 73 69 67 6e 65 64 20 66 6f 72 20 75 73 65 20 69  signed for use i
17900 6e 73 69 64 65 20 61 20 73 74 72 69 6e 67 20 6c  nside a string l
17910 69 74 65 72 61 6c 2e 29 5e 20 20 42 79 20 64 6f  iteral.)^  By do
17920 75 62 6c 69 6e 67 20 65 61 63 68 20 27 5c 27 27  ubling each '\''
17930 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 20 69 74  .** character it
17940 20 65 73 63 61 70 65 73 20 74 68 61 74 20 63 68   escapes that ch
17950 61 72 61 63 74 65 72 20 61 6e 64 20 61 6c 6c 6f  aracter and allo
17960 77 73 20 69 74 20 74 6f 20 62 65 20 69 6e 73 65  ws it to be inse
17970 72 74 65 64 20 69 6e 74 6f 0a 2a 2a 20 74 68 65  rted into.** the
17980 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a 20 46   string..**.** F
17990 6f 72 20 65 78 61 6d 70 6c 65 2c 20 61 73 73 75  or example, assu
179a0 6d 65 20 74 68 65 20 73 74 72 69 6e 67 20 76 61  me the string va
179b0 72 69 61 62 6c 65 20 7a 54 65 78 74 20 63 6f 6e  riable zText con
179c0 74 61 69 6e 73 20 74 65 78 74 20 61 73 20 66 6f  tains text as fo
179d0 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  llows:.**.** <bl
179e0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
179f0 2a 20 20 63 68 61 72 20 2a 7a 54 65 78 74 20 3d  *  char *zText =
17a00 20 22 49 74 27 73 20 61 20 68 61 70 70 79 20 64   "It's a happy d
17a10 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  ay!";.** </pre><
17a20 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
17a30 2a 2a 20 4f 6e 65 20 63 61 6e 20 75 73 65 20 74  ** One can use t
17a40 68 69 73 20 74 65 78 74 20 69 6e 20 61 6e 20 53  his text in an S
17a50 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61 73 20  QL statement as 
17a60 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c  follows:.**.** <
17a70 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e  blockquote><pre>
17a80 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 53 51 4c 20  .**  char *zSQL 
17a90 3d 20 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74  = sqlite3_mprint
17aa0 66 28 22 49 4e 53 45 52 54 20 49 4e 54 4f 20 74  f("INSERT INTO t
17ab0 61 62 6c 65 20 56 41 4c 55 45 53 28 27 25 71 27  able VALUES('%q'
17ac0 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a 20 20  )", zText);.**  
17ad0 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64 62 2c  sqlite3_exec(db,
17ae0 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30 29 3b   zSQL, 0, 0, 0);
17af0 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66 72 65  .**  sqlite3_fre
17b00 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f 70 72  e(zSQL);.** </pr
17b10 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a  e></blockquote>.
17b20 2a 2a 0a 2a 2a 20 42 65 63 61 75 73 65 20 74 68  **.** Because th
17b30 65 20 25 71 20 66 6f 72 6d 61 74 20 73 74 72 69  e %q format stri
17b40 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65 20  ng is used, the 
17b50 27 5c 27 27 20 63 68 61 72 61 63 74 65 72 20 69  '\'' character i
17b60 6e 20 7a 54 65 78 74 0a 2a 2a 20 69 73 20 65 73  n zText.** is es
17b70 63 61 70 65 64 20 61 6e 64 20 74 68 65 20 53 51  caped and the SQ
17b80 4c 20 67 65 6e 65 72 61 74 65 64 20 69 73 20 61  L generated is a
17b90 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
17ba0 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
17bb0 65 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e  e>.**  INSERT IN
17bc0 54 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53  TO table1 VALUES
17bd0 28 27 49 74 27 27 73 20 61 20 68 61 70 70 79 20  ('It''s a happy 
17be0 64 61 79 21 27 29 0a 2a 2a 20 3c 2f 70 72 65 3e  day!').** </pre>
17bf0 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a  </blockquote>.**
17c00 0a 2a 2a 20 54 68 69 73 20 69 73 20 63 6f 72 72  .** This is corr
17c10 65 63 74 2e 20 20 48 61 64 20 77 65 20 75 73 65  ect.  Had we use
17c20 64 20 25 73 20 69 6e 73 74 65 61 64 20 6f 66 20  d %s instead of 
17c30 25 71 2c 20 74 68 65 20 67 65 6e 65 72 61 74 65  %q, the generate
17c40 64 20 53 51 4c 0a 2a 2a 20 77 6f 75 6c 64 20 68  d SQL.** would h
17c50 61 76 65 20 6c 6f 6f 6b 65 64 20 6c 69 6b 65 20  ave looked like 
17c60 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f  this:.**.** <blo
17c70 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a  ckquote><pre>.**
17c80 20 20 49 4e 53 45 52 54 20 49 4e 54 4f 20 74 61    INSERT INTO ta
17c90 62 6c 65 31 20 56 41 4c 55 45 53 28 27 49 74 27  ble1 VALUES('It'
17ca0 73 20 61 20 68 61 70 70 79 20 64 61 79 21 27 29  s a happy day!')
17cb0 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f  ;.** </pre></blo
17cc0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54  ckquote>.**.** T
17cd0 68 69 73 20 73 65 63 6f 6e 64 20 65 78 61 6d 70  his second examp
17ce0 6c 65 20 69 73 20 61 6e 20 53 51 4c 20 73 79 6e  le is an SQL syn
17cf0 74 61 78 20 65 72 72 6f 72 2e 20 20 41 73 20 61  tax error.  As a
17d00 20 67 65 6e 65 72 61 6c 20 72 75 6c 65 20 79 6f   general rule yo
17d10 75 20 73 68 6f 75 6c 64 0a 2a 2a 20 61 6c 77 61  u should.** alwa
17d20 79 73 20 75 73 65 20 25 71 20 69 6e 73 74 65 61  ys use %q instea
17d30 64 20 6f 66 20 25 73 20 77 68 65 6e 20 69 6e 73  d of %s when ins
17d40 65 72 74 69 6e 67 20 74 65 78 74 20 69 6e 74 6f  erting text into
17d50 20 61 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61   a string litera
17d60 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 25  l..**.** ^(The %
17d70 51 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c  Q option works l
17d80 69 6b 65 20 25 71 20 65 78 63 65 70 74 20 69 74  ike %q except it
17d90 20 61 6c 73 6f 20 61 64 64 73 20 73 69 6e 67 6c   also adds singl
17da0 65 20 71 75 6f 74 65 73 20 61 72 6f 75 6e 64 0a  e quotes around.
17db0 2a 2a 20 74 68 65 20 6f 75 74 73 69 64 65 20 6f  ** the outside o
17dc0 66 20 74 68 65 20 74 6f 74 61 6c 20 73 74 72 69  f the total stri
17dd0 6e 67 2e 20 20 41 64 64 69 74 69 6f 6e 61 6c 6c  ng.  Additionall
17de0 79 2c 20 69 66 20 74 68 65 20 70 61 72 61 6d 65  y, if the parame
17df0 74 65 72 20 69 6e 20 74 68 65 0a 2a 2a 20 61 72  ter in the.** ar
17e00 67 75 6d 65 6e 74 20 6c 69 73 74 20 69 73 20 61  gument list is a
17e10 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 25   NULL pointer, %
17e20 51 20 73 75 62 73 74 69 74 75 74 65 73 20 74 68  Q substitutes th
17e30 65 20 74 65 78 74 20 22 4e 55 4c 4c 22 20 28 77  e text "NULL" (w
17e40 69 74 68 6f 75 74 0a 2a 2a 20 73 69 6e 67 6c 65  ithout.** single
17e50 20 71 75 6f 74 65 73 29 2e 29 5e 20 20 53 6f 2c   quotes).)^  So,
17e60 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20 6f 6e   for example, on
17e70 65 20 63 6f 75 6c 64 20 73 61 79 3a 0a 2a 2a 0a  e could say:.**.
17e80 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
17e90 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
17ea0 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
17eb0 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
17ec0 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
17ed0 25 51 29 22 2c 20 7a 54 65 78 74 29 3b 0a 2a 2a  %Q)", zText);.**
17ee0 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63 28 64    sqlite3_exec(d
17ef0 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c 20 30  b, zSQL, 0, 0, 0
17f00 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 66  );.**  sqlite3_f
17f10 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20 3c 2f  ree(zSQL);.** </
17f20 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
17f30 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  >.**.** The code
17f40 20 61 62 6f 76 65 20 77 69 6c 6c 20 72 65 6e 64   above will rend
17f50 65 72 20 61 20 63 6f 72 72 65 63 74 20 53 51 4c  er a correct SQL
17f60 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
17f70 65 20 7a 53 51 4c 0a 2a 2a 20 76 61 72 69 61 62  e zSQL.** variab
17f80 6c 65 20 65 76 65 6e 20 69 66 20 74 68 65 20 7a  le even if the z
17f90 54 65 78 74 20 76 61 72 69 61 62 6c 65 20 69 73  Text variable is
17fa0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17fb0 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65 20 22 25 7a  .**.** ^(The "%z
17fc0 22 20 66 6f 72 6d 61 74 74 69 6e 67 20 6f 70 74  " formatting opt
17fd0 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20 22  ion works like "
17fe0 25 73 22 20 62 75 74 20 77 69 74 68 20 74 68 65  %s" but with the
17ff0 0a 2a 2a 20 61 64 64 69 74 69 6f 6e 20 74 68 61  .** addition tha
18000 74 20 61 66 74 65 72 20 74 68 65 20 73 74 72 69  t after the stri
18010 6e 67 20 68 61 73 20 62 65 65 6e 20 72 65 61 64  ng has been read
18020 20 61 6e 64 20 63 6f 70 69 65 64 20 69 6e 74 6f   and copied into
18030 0a 2a 2a 20 74 68 65 20 72 65 73 75 6c 74 2c 20  .** the result, 
18040 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
18050 20 69 73 20 63 61 6c 6c 65 64 20 6f 6e 20 74 68   is called on th
18060 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 2e 29  e input string.)
18070 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73 71 6c 69 74  ^.*/.char *sqlit
18080 65 33 5f 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74  e3_mprintf(const
18090 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b 0a 63 68 61   char*,...);.cha
180a0 72 20 2a 73 71 6c 69 74 65 33 5f 76 6d 70 72 69  r *sqlite3_vmpri
180b0 6e 74 66 28 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ntf(const char*,
180c0 20 76 61 5f 6c 69 73 74 29 3b 0a 63 68 61 72 20   va_list);.char 
180d0 2a 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  *sqlite3_snprint
180e0 66 28 69 6e 74 2c 63 68 61 72 2a 2c 63 6f 6e 73  f(int,char*,cons
180f0 74 20 63 68 61 72 2a 2c 20 2e 2e 2e 29 3b 0a 63  t char*, ...);.c
18100 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76 73 6e  har *sqlite3_vsn
18110 70 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a  printf(int,char*
18120 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 76 61  ,const char*, va
18130 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  _list);../*.** C
18140 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20  API3REF: Memory 
18150 41 6c 6c 6f 63 61 74 69 6f 6e 20 53 75 62 73 79  Allocation Subsy
18160 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54 68 65 20 53  stem.**.** The S
18170 51 4c 69 74 65 20 63 6f 72 65 20 75 73 65 73 20  QLite core uses 
18180 74 68 65 73 65 20 74 68 72 65 65 20 72 6f 75 74  these three rout
18190 69 6e 65 73 20 66 6f 72 20 61 6c 6c 20 6f 66 20  ines for all of 
181a0 69 74 73 20 6f 77 6e 0a 2a 2a 20 69 6e 74 65 72  its own.** inter
181b0 6e 61 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  nal memory alloc
181c0 61 74 69 6f 6e 20 6e 65 65 64 73 2e 20 22 43 6f  ation needs. "Co
181d0 72 65 22 20 69 6e 20 74 68 65 20 70 72 65 76 69  re" in the previ
181e0 6f 75 73 20 73 65 6e 74 65 6e 63 65 0a 2a 2a 20  ous sentence.** 
181f0 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64 65  does not include
18200 20 6f 70 65 72 61 74 69 6e 67 2d 73 79 73 74 65   operating-syste
18210 6d 20 73 70 65 63 69 66 69 63 20 56 46 53 20 69  m specific VFS i
18220 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e 20 20  mplementation.  
18230 54 68 65 0a 2a 2a 20 57 69 6e 64 6f 77 73 20 56  The.** Windows V
18240 46 53 20 75 73 65 73 20 6e 61 74 69 76 65 20 6d  FS uses native m
18250 61 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65  alloc() and free
18260 28 29 20 66 6f 72 20 73 6f 6d 65 20 6f 70 65 72  () for some oper
18270 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ations..**.** ^T
18280 68 65 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  he sqlite3_mallo
18290 63 28 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  c() routine retu
182a0 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
182b0 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20 6f 66 20 6d   a block.** of m
182c0 65 6d 6f 72 79 20 61 74 20 6c 65 61 73 74 20 4e  emory at least N
182d0 20 62 79 74 65 73 20 69 6e 20 6c 65 6e 67 74 68   bytes in length
182e0 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65  , where N is the
182f0 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 5e   parameter..** ^
18300 49 66 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  If sqlite3_mallo
18310 63 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  c() is unable to
18320 20 6f 62 74 61 69 6e 20 73 75 66 66 69 63 69 65   obtain sufficie
18330 6e 74 20 66 72 65 65 0a 2a 2a 20 6d 65 6d 6f 72  nt free.** memor
18340 79 2c 20 69 74 20 72 65 74 75 72 6e 73 20 61 20  y, it returns a 
18350 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 5e  NULL pointer.  ^
18360 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  If the parameter
18370 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33   N to.** sqlite3
18380 5f 6d 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72  _malloc() is zer
18390 6f 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 68  o or negative th
183a0 65 6e 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  en sqlite3_mallo
183b0 63 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61  c() returns.** a
183c0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a   NULL pointer..*
183d0 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 73 71  *.** ^Calling sq
183e0 6c 69 74 65 33 5f 66 72 65 65 28 29 20 77 69 74  lite3_free() wit
183f0 68 20 61 20 70 6f 69 6e 74 65 72 20 70 72 65 76  h a pointer prev
18400 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 0a  iously returned.
18410 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 6d 61  ** by sqlite3_ma
18420 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
18430 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65 6c 65  3_realloc() rele
18440 61 73 65 73 20 74 68 61 74 20 6d 65 6d 6f 72 79  ases that memory
18450 20 73 6f 0a 2a 2a 20 74 68 61 74 20 69 74 20 6d   so.** that it m
18460 69 67 68 74 20 62 65 20 72 65 75 73 65 64 2e 20  ight be reused. 
18470 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66 72   ^The sqlite3_fr
18480 65 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 0a  ee() routine is.
18490 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69 66 20 69 73  ** a no-op if is
184a0 20 63 61 6c 6c 65 64 20 77 69 74 68 20 61 20 4e   called with a N
184b0 55 4c 4c 20 70 6f 69 6e 74 65 72 2e 20 20 50 61  ULL pointer.  Pa
184c0 73 73 69 6e 67 20 61 20 4e 55 4c 4c 20 70 6f 69  ssing a NULL poi
184d0 6e 74 65 72 0a 2a 2a 20 74 6f 20 73 71 6c 69 74  nter.** to sqlit
184e0 65 33 5f 66 72 65 65 28 29 20 69 73 20 68 61 72  e3_free() is har
184f0 6d 6c 65 73 73 2e 20 20 41 66 74 65 72 20 62 65  mless.  After be
18500 69 6e 67 20 66 72 65 65 64 2c 20 6d 65 6d 6f 72  ing freed, memor
18510 79 0a 2a 2a 20 73 68 6f 75 6c 64 20 6e 65 69 74  y.** should neit
18520 68 65 72 20 62 65 20 72 65 61 64 20 6e 6f 72 20  her be read nor 
18530 77 72 69 74 74 65 6e 2e 20 20 45 76 65 6e 20 72  written.  Even r
18540 65 61 64 69 6e 67 20 70 72 65 76 69 6f 75 73 6c  eading previousl
18550 79 20 66 72 65 65 64 0a 2a 2a 20 6d 65 6d 6f 72  y freed.** memor
18560 79 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20 69  y might result i
18570 6e 20 61 20 73 65 67 6d 65 6e 74 61 74 69 6f 6e  n a segmentation
18580 20 66 61 75 6c 74 20 6f 72 20 6f 74 68 65 72 20   fault or other 
18590 73 65 76 65 72 65 20 65 72 72 6f 72 2e 0a 2a 2a  severe error..**
185a0 20 4d 65 6d 6f 72 79 20 63 6f 72 72 75 70 74 69   Memory corrupti
185b0 6f 6e 2c 20 61 20 73 65 67 6d 65 6e 74 61 74 69  on, a segmentati
185c0 6f 6e 20 66 61 75 6c 74 2c 20 6f 72 20 6f 74 68  on fault, or oth
185d0 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72 0a  er severe error.
185e0 2a 2a 20 6d 69 67 68 74 20 72 65 73 75 6c 74 20  ** might result 
185f0 69 66 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  if sqlite3_free(
18600 29 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  ) is called with
18610 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70 6f 69 6e   a non-NULL poin
18620 74 65 72 20 74 68 61 74 0a 2a 2a 20 77 61 73 20  ter that.** was 
18630 6e 6f 74 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  not obtained fro
18640 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
18650 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65  () or sqlite3_re
18660 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e  alloc()..**.** ^
18670 28 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 61  (The sqlite3_rea
18680 6c 6c 6f 63 28 29 20 69 6e 74 65 72 66 61 63 65  lloc() interface
18690 20 61 74 74 65 6d 70 74 73 20 74 6f 20 72 65 73   attempts to res
186a0 69 7a 65 20 61 0a 2a 2a 20 70 72 69 6f 72 20 6d  ize a.** prior m
186b0 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
186c0 20 74 6f 20 62 65 20 61 74 20 6c 65 61 73 74 20   to be at least 
186d0 4e 20 62 79 74 65 73 2c 20 77 68 65 72 65 20 4e  N bytes, where N
186e0 20 69 73 20 74 68 65 0a 2a 2a 20 73 65 63 6f 6e   is the.** secon
186f0 64 20 70 61 72 61 6d 65 74 65 72 2e 20 20 54 68  d parameter.  Th
18700 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  e memory allocat
18710 69 6f 6e 20 74 6f 20 62 65 20 72 65 73 69 7a 65  ion to be resize
18720 64 20 69 73 20 74 68 65 20 66 69 72 73 74 0a 2a  d is the first.*
18730 2a 20 70 61 72 61 6d 65 74 65 72 2e 29 5e 20 5e  * parameter.)^ ^
18740 20 49 66 20 74 68 65 20 66 69 72 73 74 20 70 61   If the first pa
18750 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
18760 65 33 5f 72 65 61 6c 6c 6f 63 28 29 0a 2a 2a 20  e3_realloc().** 
18770 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
18780 72 20 74 68 65 6e 20 69 74 73 20 62 65 68 61 76  r then its behav
18790 69 6f 72 20 69 73 20 69 64 65 6e 74 69 63 61 6c  ior is identical
187a0 20 74 6f 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20 73   to calling.** s
187b0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 4e 29  qlite3_malloc(N)
187c0 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
187d0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
187e0 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61 6c   to sqlite3_real
187f0 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49 66 20 74 68  loc()..** ^If th
18800 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
18810 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
18820 61 6c 6c 6f 63 28 29 20 69 73 20 7a 65 72 6f 20  alloc() is zero 
18830 6f 72 0a 2a 2a 20 6e 65 67 61 74 69 76 65 20 74  or.** negative t
18840 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
18850 20 69 73 20 65 78 61 63 74 6c 79 20 74 68 65 20   is exactly the 
18860 73 61 6d 65 20 61 73 20 63 61 6c 6c 69 6e 67 0a  same as calling.
18870 2a 2a 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28  ** sqlite3_free(
18880 50 29 20 77 68 65 72 65 20 50 20 69 73 20 74 68  P) where P is th
18890 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  e first paramete
188a0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 61  r to sqlite3_rea
188b0 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 73 71 6c 69  lloc()..** ^sqli
188c0 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 72 65  te3_realloc() re
188d0 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20  turns a pointer 
188e0 74 6f 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  to a memory allo
188f0 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 61 74 20  cation.** of at 
18900 6c 65 61 73 74 20 4e 20 62 79 74 65 73 20 69 6e  least N bytes in
18910 20 73 69 7a 65 20 6f 72 20 4e 55 4c 4c 20 69 66   size or NULL if
18920 20 73 75 66 66 69 63 69 65 6e 74 20 6d 65 6d 6f   sufficient memo
18930 72 79 20 69 73 20 75 6e 61 76 61 69 6c 61 62 6c  ry is unavailabl
18940 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20 69 73 20 74  e..** ^If M is t
18950 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 70  he size of the p
18960 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 2c  rior allocation,
18970 20 74 68 65 6e 20 6d 69 6e 28 4e 2c 4d 29 20 62   then min(N,M) b
18980 79 74 65 73 0a 2a 2a 20 6f 66 20 74 68 65 20 70  ytes.** of the p
18990 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  rior allocation 
189a0 61 72 65 20 63 6f 70 69 65 64 20 69 6e 74 6f 20  are copied into 
189b0 74 68 65 20 62 65 67 69 6e 6e 69 6e 67 20 6f 66  the beginning of
189c0 20 62 75 66 66 65 72 20 72 65 74 75 72 6e 65 64   buffer returned
189d0 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65 33 5f 72  .** by sqlite3_r
189e0 65 61 6c 6c 6f 63 28 29 20 61 6e 64 20 74 68 65  ealloc() and the
189f0 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f   prior allocatio
18a00 6e 20 69 73 20 66 72 65 65 64 2e 0a 2a 2a 20 5e  n is freed..** ^
18a10 49 66 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  If sqlite3_reall
18a20 6f 63 28 29 20 72 65 74 75 72 6e 73 20 4e 55 4c  oc() returns NUL
18a30 4c 2c 20 74 68 65 6e 20 74 68 65 20 70 72 69 6f  L, then the prio
18a40 72 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20  r allocation.** 
18a50 69 73 20 6e 6f 74 20 66 72 65 65 64 2e 0a 2a 2a  is not freed..**
18a60 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
18a70 72 65 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69  returned by sqli
18a80 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 61 6e 64  te3_malloc() and
18a90 20 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63   sqlite3_realloc
18aa0 28 29 0a 2a 2a 20 69 73 20 61 6c 77 61 79 73 20  ().** is always 
18ab0 61 6c 69 67 6e 65 64 20 74 6f 20 61 74 20 6c 65  aligned to at le
18ac0 61 73 74 20 61 6e 20 38 20 62 79 74 65 20 62 6f  ast an 8 byte bo
18ad0 75 6e 64 61 72 79 2c 20 6f 72 20 74 6f 20 61 0a  undary, or to a.
18ae0 2a 2a 20 34 20 62 79 74 65 20 62 6f 75 6e 64 61  ** 4 byte bounda
18af0 72 79 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54  ry if the [SQLIT
18b00 45 5f 34 5f 42 59 54 45 5f 41 4c 49 47 4e 45 44  E_4_BYTE_ALIGNED
18b10 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d 70 69 6c 65  _MALLOC] compile
18b20 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74 69 6f 6e 20  -time.** option 
18b30 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 49  is used..**.** I
18b40 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  n SQLite version
18b50 20 33 2e 35 2e 30 20 61 6e 64 20 33 2e 35 2e 31   3.5.0 and 3.5.1
18b60 2c 20 69 74 20 77 61 73 20 70 6f 73 73 69 62 6c  , it was possibl
18b70 65 20 74 6f 20 64 65 66 69 6e 65 0a 2a 2a 20 74  e to define.** t
18b80 68 65 20 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 4d  he SQLITE_OMIT_M
18b90 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41 54 49 4f 4e  EMORY_ALLOCATION
18ba0 20 77 68 69 63 68 20 77 6f 75 6c 64 20 63 61 75   which would cau
18bb0 73 65 20 74 68 65 20 62 75 69 6c 74 2d 69 6e 0a  se the built-in.
18bc0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
18bd0 6e 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  n of these routi
18be0 6e 65 73 20 74 6f 20 62 65 20 6f 6d 69 74 74 65  nes to be omitte
18bf0 64 2e 20 20 54 68 61 74 20 63 61 70 61 62 69 6c  d.  That capabil
18c00 69 74 79 0a 2a 2a 20 69 73 20 6e 6f 20 6c 6f 6e  ity.** is no lon
18c10 67 65 72 20 70 72 6f 76 69 64 65 64 2e 20 20 4f  ger provided.  O
18c20 6e 6c 79 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d  nly built-in mem
18c30 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 73 20 63  ory allocators c
18c40 61 6e 20 62 65 20 75 73 65 64 2e 0a 2a 2a 0a 2a  an be used..**.*
18c50 2a 20 54 68 65 20 57 69 6e 64 6f 77 73 20 4f 53  * The Windows OS
18c60 20 69 6e 74 65 72 66 61 63 65 20 6c 61 79 65 72   interface layer
18c70 20 63 61 6c 6c 73 0a 2a 2a 20 74 68 65 20 73 79   calls.** the sy
18c80 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20 61 6e  stem malloc() an
18c90 64 20 66 72 65 65 28 29 20 64 69 72 65 63 74 6c  d free() directl
18ca0 79 20 77 68 65 6e 20 63 6f 6e 76 65 72 74 69 6e  y when convertin
18cb0 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d 65 73 20 62  g.** filenames b
18cc0 65 74 77 65 65 6e 20 74 68 65 20 55 54 46 2d 38  etween the UTF-8
18cd0 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20 62   encoding used b
18ce0 79 20 53 51 4c 69 74 65 0a 2a 2a 20 61 6e 64 20  y SQLite.** and 
18cf0 77 68 61 74 65 76 65 72 20 66 69 6c 65 6e 61 6d  whatever filenam
18d00 65 20 65 6e 63 6f 64 69 6e 67 20 69 73 20 75 73  e encoding is us
18d10 65 64 20 62 79 20 74 68 65 20 70 61 72 74 69 63  ed by the partic
18d20 75 6c 61 72 20 57 69 6e 64 6f 77 73 0a 2a 2a 20  ular Windows.** 
18d30 69 6e 73 74 61 6c 6c 61 74 69 6f 6e 2e 20 20 4d  installation.  M
18d40 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
18d50 20 65 72 72 6f 72 73 20 61 72 65 20 64 65 74 65   errors are dete
18d60 63 74 65 64 2c 20 62 75 74 0a 2a 2a 20 74 68 65  cted, but.** the
18d70 79 20 61 72 65 20 72 65 70 6f 72 74 65 64 20 62  y are reported b
18d80 61 63 6b 20 61 73 20 5b 53 51 4c 49 54 45 5f 43  ack as [SQLITE_C
18d90 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a 2a 2a 20 5b  ANTOPEN] or.** [
18da0 53 51 4c 49 54 45 5f 49 4f 45 52 52 5d 20 72 61  SQLITE_IOERR] ra
18db0 74 68 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54  ther than [SQLIT
18dc0 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a 0a 2a 2a 20  E_NOMEM]..**.** 
18dd0 54 68 65 20 70 6f 69 6e 74 65 72 20 61 72 67 75  The pointer argu
18de0 6d 65 6e 74 73 20 74 6f 20 5b 73 71 6c 69 74 65  ments to [sqlite
18df0 33 5f 66 72 65 65 28 29 5d 20 61 6e 64 20 5b 73  3_free()] and [s
18e00 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
18e10 5d 0a 2a 2a 20 6d 75 73 74 20 62 65 20 65 69 74  ].** must be eit
18e20 68 65 72 20 4e 55 4c 4c 20 6f 72 20 65 6c 73 65  her NULL or else
18e30 20 70 6f 69 6e 74 65 72 73 20 6f 62 74 61 69 6e   pointers obtain
18e40 65 64 20 66 72 6f 6d 20 61 20 70 72 69 6f 72 0a  ed from a prior.
18e50 2a 2a 20 69 6e 76 6f 63 61 74 69 6f 6e 20 6f 66  ** invocation of
18e60 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
18e70 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
18e80 72 65 61 6c 6c 6f 63 28 29 5d 20 74 68 61 74 20  realloc()] that 
18e90 68 61 76 65 0a 2a 2a 20 6e 6f 74 20 79 65 74 20  have.** not yet 
18ea0 62 65 65 6e 20 72 65 6c 65 61 73 65 64 2e 0a 2a  been released..*
18eb0 2a 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61  *.** The applica
18ec0 74 69 6f 6e 20 6d 75 73 74 20 6e 6f 74 20 72 65  tion must not re
18ed0 61 64 20 6f 72 20 77 72 69 74 65 20 61 6e 79 20  ad or write any 
18ee0 70 61 72 74 20 6f 66 0a 2a 2a 20 61 20 62 6c 6f  part of.** a blo
18ef0 63 6b 20 6f 66 20 6d 65 6d 6f 72 79 20 61 66 74  ck of memory aft
18f00 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20 72  er it has been r
18f10 65 6c 65 61 73 65 64 20 75 73 69 6e 67 0a 2a 2a  eleased using.**
18f20 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29   [sqlite3_free()
18f30 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  ] or [sqlite3_re
18f40 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f 0a 76 6f 69  alloc()]..*/.voi
18f50 64 20 2a 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  d *sqlite3_mallo
18f60 63 28 69 6e 74 29 3b 0a 76 6f 69 64 20 2a 73 71  c(int);.void *sq
18f70 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 76 6f  lite3_realloc(vo
18f80 69 64 2a 2c 20 69 6e 74 29 3b 0a 76 6f 69 64 20  id*, int);.void 
18f90 73 71 6c 69 74 65 33 5f 66 72 65 65 28 76 6f 69  sqlite3_free(voi
18fa0 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  d*);../*.** CAPI
18fb0 33 52 45 46 3a 20 4d 65 6d 6f 72 79 20 41 6c 6c  3REF: Memory All
18fc0 6f 63 61 74 6f 72 20 53 74 61 74 69 73 74 69 63  ocator Statistic
18fd0 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 70  s.**.** SQLite p
18fe0 72 6f 76 69 64 65 73 20 74 68 65 73 65 20 74 77  rovides these tw
18ff0 6f 20 69 6e 74 65 72 66 61 63 65 73 20 66 6f 72  o interfaces for
19000 20 72 65 70 6f 72 74 69 6e 67 20 6f 6e 20 74 68   reporting on th
19010 65 20 73 74 61 74 75 73 0a 2a 2a 20 6f 66 20 74  e status.** of t
19020 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  he [sqlite3_mall
19030 6f 63 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  oc()], [sqlite3_
19040 66 72 65 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71  free()], and [sq
19050 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d  lite3_realloc()]
19060 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 2c 20 77 68  .** routines, wh
19070 69 63 68 20 66 6f 72 6d 20 74 68 65 20 62 75 69  ich form the bui
19080 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79 20 61 6c 6c  lt-in memory all
19090 6f 63 61 74 69 6f 6e 20 73 75 62 73 79 73 74 65  ocation subsyste
190a0 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73  m..**.** ^The [s
190b0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
190c0 65 64 28 29 5d 20 72 6f 75 74 69 6e 65 20 72 65  ed()] routine re
190d0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
190e0 20 6f 66 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20   of bytes.** of 
190f0 6d 65 6d 6f 72 79 20 63 75 72 72 65 6e 74 6c 79  memory currently
19100 20 6f 75 74 73 74 61 6e 64 69 6e 67 20 28 6d 61   outstanding (ma
19110 6c 6c 6f 63 65 64 20 62 75 74 20 6e 6f 74 20 66  lloced but not f
19120 72 65 65 64 29 2e 0a 2a 2a 20 5e 54 68 65 20 5b  reed)..** ^The [
19130 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68  sqlite3_memory_h
19140 69 67 68 77 61 74 65 72 28 29 5d 20 72 6f 75 74  ighwater()] rout
19150 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ine returns the 
19160 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76 61 6c 75 65  maximum.** value
19170 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d   of [sqlite3_mem
19180 6f 72 79 5f 75 73 65 64 28 29 5d 20 73 69 6e 63  ory_used()] sinc
19190 65 20 74 68 65 20 68 69 67 68 2d 77 61 74 65 72  e the high-water
191a0 20 6d 61 72 6b 0a 2a 2a 20 77 61 73 20 6c 61 73   mark.** was las
191b0 74 20 72 65 73 65 74 2e 20 20 5e 54 68 65 20 76  t reset.  ^The v
191c0 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64 20 62  alues returned b
191d0 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
191e0 79 5f 75 73 65 64 28 29 5d 20 61 6e 64 0a 2a 2a  y_used()] and.**
191f0 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19200 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 6e  _highwater()] in
19210 63 6c 75 64 65 20 61 6e 79 20 6f 76 65 72 68 65  clude any overhe
19220 61 64 0a 2a 2a 20 61 64 64 65 64 20 62 79 20 53  ad.** added by S
19230 51 4c 69 74 65 20 69 6e 20 69 74 73 20 69 6d 70  QLite in its imp
19240 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b  lementation of [
19250 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
19260 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f 74 20 6f 76  ],.** but not ov
19270 65 72 68 65 61 64 20 61 64 64 65 64 20 62 79 20  erhead added by 
19280 74 68 65 20 61 6e 79 20 75 6e 64 65 72 6c 79 69  the any underlyi
19290 6e 67 20 73 79 73 74 65 6d 20 6c 69 62 72 61 72  ng system librar
192a0 79 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 74 68  y.** routines th
192b0 61 74 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  at [sqlite3_mall
192c0 6f 63 28 29 5d 20 6d 61 79 20 63 61 6c 6c 2e 0a  oc()] may call..
192d0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72  **.** ^The memor
192e0 79 20 68 69 67 68 2d 77 61 74 65 72 20 6d 61 72  y high-water mar
192f0 6b 20 69 73 20 72 65 73 65 74 20 74 6f 20 74 68  k is reset to th
19300 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
19310 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d  of.** [sqlite3_m
19320 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 69 66  emory_used()] if
19330 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68 65   and only if the
19340 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a 2a 2a   parameter to.**
19350 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79   [sqlite3_memory
19360 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20 69 73  _highwater()] is
19370 20 74 72 75 65 2e 20 20 5e 54 68 65 20 76 61 6c   true.  ^The val
19380 75 65 20 72 65 74 75 72 6e 65 64 0a 2a 2a 20 62  ue returned.** b
19390 79 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  y [sqlite3_memor
193a0 79 5f 68 69 67 68 77 61 74 65 72 28 31 29 5d 20  y_highwater(1)] 
193b0 69 73 20 74 68 65 20 68 69 67 68 2d 77 61 74 65  is the high-wate
193c0 72 20 6d 61 72 6b 0a 2a 2a 20 70 72 69 6f 72 20  r mark.** prior 
193d0 74 6f 20 74 68 65 20 72 65 73 65 74 2e 0a 2a 2f  to the reset..*/
193e0 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
193f0 71 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73  qlite3_memory_us
19400 65 64 28 76 6f 69 64 29 3b 0a 73 71 6c 69 74 65  ed(void);.sqlite
19410 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f  3_int64 sqlite3_
19420 6d 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72  memory_highwater
19430 28 69 6e 74 20 72 65 73 65 74 46 6c 61 67 29 3b  (int resetFlag);
19440 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
19450 3a 20 50 73 65 75 64 6f 2d 52 61 6e 64 6f 6d 20  : Pseudo-Random 
19460 4e 75 6d 62 65 72 20 47 65 6e 65 72 61 74 6f 72  Number Generator
19470 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 63 6f  .**.** SQLite co
19480 6e 74 61 69 6e 73 20 61 20 68 69 67 68 2d 71 75  ntains a high-qu
19490 61 6c 69 74 79 20 70 73 65 75 64 6f 2d 72 61 6e  ality pseudo-ran
194a0 64 6f 6d 20 6e 75 6d 62 65 72 20 67 65 6e 65 72  dom number gener
194b0 61 74 6f 72 20 28 50 52 4e 47 29 20 75 73 65 64  ator (PRNG) used
194c0 20 74 6f 0a 2a 2a 20 73 65 6c 65 63 74 20 72 61   to.** select ra
194d0 6e 64 6f 6d 20 5b 52 4f 57 49 44 20 7c 20 52 4f  ndom [ROWID | RO
194e0 57 49 44 73 5d 20 77 68 65 6e 20 69 6e 73 65 72  WIDs] when inser
194f0 74 69 6e 67 20 6e 65 77 20 72 65 63 6f 72 64 73  ting new records
19500 20 69 6e 74 6f 20 61 20 74 61 62 6c 65 20 74 68   into a table th
19510 61 74 0a 2a 2a 20 61 6c 72 65 61 64 79 20 75 73  at.** already us
19520 65 73 20 74 68 65 20 6c 61 72 67 65 73 74 20 70  es the largest p
19530 6f 73 73 69 62 6c 65 20 5b 52 4f 57 49 44 5d 2e  ossible [ROWID].
19540 20 20 54 68 65 20 50 52 4e 47 20 69 73 20 61 6c    The PRNG is al
19550 73 6f 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74  so used for.** t
19560 68 65 20 62 75 69 6c 64 2d 69 6e 20 72 61 6e 64  he build-in rand
19570 6f 6d 28 29 20 61 6e 64 20 72 61 6e 64 6f 6d 62  om() and randomb
19580 6c 6f 62 28 29 20 53 51 4c 20 66 75 6e 63 74 69  lob() SQL functi
19590 6f 6e 73 2e 20 20 54 68 69 73 20 69 6e 74 65 72  ons.  This inter
195a0 66 61 63 65 20 61 6c 6c 6f 77 73 0a 2a 2a 20 61  face allows.** a
195b0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 6f 20 61  pplications to a
195c0 63 63 65 73 73 20 74 68 65 20 73 61 6d 65 20 50  ccess the same P
195d0 52 4e 47 20 66 6f 72 20 6f 74 68 65 72 20 70 75  RNG for other pu
195e0 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  rposes..**.** ^A
195f0 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 72 6f   call to this ro
19600 75 74 69 6e 65 20 73 74 6f 72 65 73 20 4e 20 62  utine stores N b
19610 79 74 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65  ytes of randomne
19620 73 73 20 69 6e 74 6f 20 62 75 66 66 65 72 20 50  ss into buffer P
19630 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
19640 73 74 20 74 69 6d 65 20 74 68 69 73 20 72 6f 75  st time this rou
19650 74 69 6e 65 20 69 73 20 69 6e 76 6f 6b 65 64 20  tine is invoked 
19660 28 65 69 74 68 65 72 20 69 6e 74 65 72 6e 61 6c  (either internal
19670 6c 79 20 6f 72 20 62 79 0a 2a 2a 20 74 68 65 20  ly or by.** the 
19680 61 70 70 6c 69 63 61 74 69 6f 6e 29 20 74 68 65  application) the
19690 20 50 52 4e 47 20 69 73 20 73 65 65 64 65 64 20   PRNG is seeded 
196a0 75 73 69 6e 67 20 72 61 6e 64 6f 6d 6e 65 73 73  using randomness
196b0 20 6f 62 74 61 69 6e 65 64 0a 2a 2a 20 66 72 6f   obtained.** fro
196c0 6d 20 74 68 65 20 78 52 61 6e 64 6f 6d 6e 65 73  m the xRandomnes
196d0 73 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  s method of the 
196e0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
196f0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a  _vfs] object..**
19700 20 5e 4f 6e 20 61 6c 6c 20 73 75 62 73 65 71 75   ^On all subsequ
19710 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e 73 2c  ent invocations,
19720 20 74 68 65 20 70 73 65 75 64 6f 2d 72 61 6e 64   the pseudo-rand
19730 6f 6d 6e 65 73 73 20 69 73 20 67 65 6e 65 72 61  omness is genera
19740 74 65 64 0a 2a 2a 20 69 6e 74 65 72 6e 61 6c 6c  ted.** internall
19750 79 20 61 6e 64 20 77 69 74 68 6f 75 74 20 72 65  y and without re
19760 63 6f 75 72 73 65 20 74 6f 20 74 68 65 20 5b 73  course to the [s
19770 71 6c 69 74 65 33 5f 76 66 73 5d 20 78 52 61 6e  qlite3_vfs] xRan
19780 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d 65 74 68 6f  domness.** metho
19790 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  d..*/.void sqlit
197a0 65 33 5f 72 61 6e 64 6f 6d 6e 65 73 73 28 69 6e  e3_randomness(in
197b0 74 20 4e 2c 20 76 6f 69 64 20 2a 50 29 3b 0a 0a  t N, void *P);..
197c0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
197d0 43 6f 6d 70 69 6c 65 2d 54 69 6d 65 20 41 75 74  Compile-Time Aut
197e0 68 6f 72 69 7a 61 74 69 6f 6e 20 43 61 6c 6c 62  horization Callb
197f0 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  acks.**.** ^This
19800 20 72 6f 75 74 69 6e 65 20 72 65 67 69 73 74 65   routine registe
19810 72 73 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72  rs an authorizer
19820 20 63 61 6c 6c 62 61 63 6b 20 77 69 74 68 20 61   callback with a
19830 20 70 61 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b   particular.** [
19840 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
19850 69 6f 6e 5d 2c 20 73 75 70 70 6c 69 65 64 20 69  ion], supplied i
19860 6e 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75  n the first argu
19870 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65 20 61 75  ment..** ^The au
19880 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
19890 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 73 20  k is invoked as 
198a0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 61  SQL statements a
198b0 72 65 20 62 65 69 6e 67 20 63 6f 6d 70 69 6c 65  re being compile
198c0 64 0a 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33  d.** by [sqlite3
198d0 5f 70 72 65 70 61 72 65 28 29 5d 20 6f 72 20 69  _prepare()] or i
198e0 74 73 20 76 61 72 69 61 6e 74 73 20 5b 73 71 6c  ts variants [sql
198f0 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19900 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
19910 70 72 65 70 61 72 65 31 36 28 29 5d 20 61 6e 64  prepare16()] and
19920 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
19930 65 31 36 5f 76 32 28 29 5d 2e 20 20 5e 41 74 20  e16_v2()].  ^At 
19940 76 61 72 69 6f 75 73 0a 2a 2a 20 70 6f 69 6e 74  various.** point
19950 73 20 64 75 72 69 6e 67 20 74 68 65 20 63 6f 6d  s during the com
19960 70 69 6c 61 74 69 6f 6e 20 70 72 6f 63 65 73 73  pilation process
19970 2c 20 61 73 20 6c 6f 67 69 63 20 69 73 20 62 65  , as logic is be
19980 69 6e 67 20 63 72 65 61 74 65 64 0a 2a 2a 20 74  ing created.** t
19990 6f 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75  o perform variou
199a0 73 20 61 63 74 69 6f 6e 73 2c 20 74 68 65 20 61  s actions, the a
199b0 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61  uthorizer callba
199c0 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f  ck is invoked to
199d0 0a 2a 2a 20 73 65 65 20 69 66 20 74 68 6f 73 65  .** see if those
199e0 20 61 63 74 69 6f 6e 73 20 61 72 65 20 61 6c 6c   actions are all
199f0 6f 77 65 64 2e 20 20 5e 54 68 65 20 61 75 74 68  owed.  ^The auth
19a00 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19a10 73 68 6f 75 6c 64 0a 2a 2a 20 72 65 74 75 72 6e  should.** return
19a20 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 74 6f 20   [SQLITE_OK] to 
19a30 61 6c 6c 6f 77 20 74 68 65 20 61 63 74 69 6f 6e  allow the action
19a40 2c 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  , [SQLITE_IGNORE
19a50 5d 20 74 6f 20 64 69 73 61 6c 6c 6f 77 20 74 68  ] to disallow th
19a60 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 61 63  e.** specific ac
19a70 74 69 6f 6e 20 62 75 74 20 61 6c 6c 6f 77 20 74  tion but allow t
19a80 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
19a90 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20 74 6f 20   to continue to 
19aa0 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64 2c 20  be.** compiled, 
19ab0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d  or [SQLITE_DENY]
19ac0 20 74 6f 20 63 61 75 73 65 20 74 68 65 20 65 6e   to cause the en
19ad0 74 69 72 65 20 53 51 4c 20 73 74 61 74 65 6d 65  tire SQL stateme
19ae0 6e 74 20 74 6f 20 62 65 0a 2a 2a 20 72 65 6a 65  nt to be.** reje
19af0 63 74 65 64 20 77 69 74 68 20 61 6e 20 65 72 72  cted with an err
19b00 6f 72 2e 20 20 5e 49 66 20 74 68 65 20 61 75 74  or.  ^If the aut
19b10 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b  horizer callback
19b20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 61 6e 79 20   returns.** any 
19b30 76 61 6c 75 65 20 6f 74 68 65 72 20 74 68 61 6e  value other than
19b40 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d   [SQLITE_IGNORE]
19b50 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 2c 20 6f  , [SQLITE_OK], o
19b60 72 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 0a  r [SQLITE_DENY].
19b70 2a 2a 20 74 68 65 6e 20 74 68 65 20 5b 73 71 6c  ** then the [sql
19b80 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
19b90 29 5d 20 6f 72 20 65 71 75 69 76 61 6c 65 6e 74  )] or equivalent
19ba0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
19bb0 65 72 65 64 0a 2a 2a 20 74 68 65 20 61 75 74 68  ered.** the auth
19bc0 6f 72 69 7a 65 72 20 77 69 6c 6c 20 66 61 69 6c  orizer will fail
19bd0 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20 6d   with an error m
19be0 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a 2a 20 57 68  essage..**.** Wh
19bf0 65 6e 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20  en the callback 
19c00 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
19c10 4f 4b 5d 2c 20 74 68 61 74 20 6d 65 61 6e 73 20  OK], that means 
19c20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 0a 2a 2a  the operation.**
19c30 20 72 65 71 75 65 73 74 65 64 20 69 73 20 6f 6b   requested is ok
19c40 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 63 61 6c  .  ^When the cal
19c50 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53  lback returns [S
19c60 51 4c 49 54 45 5f 44 45 4e 59 5d 2c 20 74 68 65  QLITE_DENY], the
19c70 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  .** [sqlite3_pre
19c80 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 65 71  pare_v2()] or eq
19c90 75 69 76 61 6c 65 6e 74 20 63 61 6c 6c 20 74 68  uivalent call th
19ca0 61 74 20 74 72 69 67 67 65 72 65 64 20 74 68 65  at triggered the
19cb0 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 77  .** authorizer w
19cc0 69 6c 6c 20 66 61 69 6c 20 77 69 74 68 20 61 6e  ill fail with an
19cd0 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 20 65   error message e
19ce0 78 70 6c 61 69 6e 69 6e 67 20 74 68 61 74 0a 2a  xplaining that.*
19cf0 2a 20 61 63 63 65 73 73 20 69 73 20 64 65 6e 69  * access is deni
19d00 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ed. .**.** ^The 
19d10 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
19d20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  to the authorize
19d30 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 61 20  r callback is a 
19d40 63 6f 70 79 20 6f 66 20 74 68 65 20 74 68 69 72  copy of the thir
19d50 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 74  d.** parameter t
19d60 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73 65  o the sqlite3_se
19d70 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 20 69  t_authorizer() i
19d80 6e 74 65 72 66 61 63 65 2e 20 5e 54 68 65 20 73  nterface. ^The s
19d90 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 0a  econd parameter.
19da0 2a 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61  ** to the callba
19db0 63 6b 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ck is an integer
19dc0 20 5b 53 51 4c 49 54 45 5f 43 4f 50 59 20 7c 20   [SQLITE_COPY | 
19dd0 61 63 74 69 6f 6e 20 63 6f 64 65 5d 20 74 68 61  action code] tha
19de0 74 20 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 74  t specifies.** t
19df0 68 65 20 70 61 72 74 69 63 75 6c 61 72 20 61 63  he particular ac
19e00 74 69 6f 6e 20 74 6f 20 62 65 20 61 75 74 68 6f  tion to be autho
19e10 72 69 7a 65 64 2e 20 5e 54 68 65 20 74 68 69 72  rized. ^The thir
19e20 64 20 74 68 72 6f 75 67 68 20 73 69 78 74 68 20  d through sixth 
19e30 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f  parameters.** to
19e40 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 61 72   the callback ar
19e50 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  e zero-terminate
19e60 64 20 73 74 72 69 6e 67 73 20 74 68 61 74 20 63  d strings that c
19e70 6f 6e 74 61 69 6e 20 61 64 64 69 74 69 6f 6e 61  ontain additiona
19e80 6c 0a 2a 2a 20 64 65 74 61 69 6c 73 20 61 62 6f  l.** details abo
19e90 75 74 20 74 68 65 20 61 63 74 69 6f 6e 20 74 6f  ut the action to
19ea0 20 62 65 20 61 75 74 68 6f 72 69 7a 65 64 2e 0a   be authorized..
19eb0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 61 63  **.** ^If the ac
19ec0 74 69 6f 6e 20 63 6f 64 65 20 69 73 20 5b 53 51  tion code is [SQ
19ed0 4c 49 54 45 5f 52 45 41 44 5d 0a 2a 2a 20 61 6e  LITE_READ].** an
19ee0 64 20 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 72  d the callback r
19ef0 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f 49  eturns [SQLITE_I
19f00 47 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 0a  GNORE] then the.
19f10 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ** [prepared sta
19f20 74 65 6d 65 6e 74 5d 20 73 74 61 74 65 6d 65 6e  tement] statemen
19f30 74 20 69 73 20 63 6f 6e 73 74 72 75 63 74 65 64  t is constructed
19f40 20 74 6f 20 73 75 62 73 74 69 74 75 74 65 0a 2a   to substitute.*
19f50 2a 20 61 20 4e 55 4c 4c 20 76 61 6c 75 65 20 69  * a NULL value i
19f60 6e 20 70 6c 61 63 65 20 6f 66 20 74 68 65 20 74  n place of the t
19f70 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68 61 74  able column that
19f80 20 77 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 62   would have.** b
19f90 65 65 6e 20 72 65 61 64 20 69 66 20 5b 53 51 4c  een read if [SQL
19fa0 49 54 45 5f 4f 4b 5d 20 68 61 64 20 62 65 65 6e  ITE_OK] had been
19fb0 20 72 65 74 75 72 6e 65 64 2e 20 20 54 68 65 20   returned.  The 
19fc0 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 5d 0a  [SQLITE_IGNORE].
19fd0 2a 2a 20 72 65 74 75 72 6e 20 63 61 6e 20 62 65  ** return can be
19fe0 20 75 73 65 64 20 74 6f 20 64 65 6e 79 20 61 6e   used to deny an
19ff0 20 75 6e 74 72 75 73 74 65 64 20 75 73 65 72 20   untrusted user 
1a000 61 63 63 65 73 73 20 74 6f 20 69 6e 64 69 76 69  access to indivi
1a010 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75 6d 6e 73 20  dual.** columns 
1a020 6f 66 20 61 20 74 61 62 6c 65 2e 0a 2a 2a 20 5e  of a table..** ^
1a030 49 66 20 74 68 65 20 61 63 74 69 6f 6e 20 63 6f  If the action co
1a040 64 65 20 69 73 20 5b 53 51 4c 49 54 45 5f 44 45  de is [SQLITE_DE
1a050 4c 45 54 45 5d 20 61 6e 64 20 74 68 65 20 63 61  LETE] and the ca
1a060 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a  llback returns.*
1a070 2a 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45  * [SQLITE_IGNORE
1a080 5d 20 74 68 65 6e 20 74 68 65 20 5b 44 45 4c 45  ] then the [DELE
1a090 54 45 5d 20 6f 70 65 72 61 74 69 6f 6e 20 70 72  TE] operation pr
1a0a0 6f 63 65 65 64 73 20 62 75 74 20 74 68 65 0a 2a  oceeds but the.*
1a0b0 2a 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  * [truncate opti
1a0c0 6d 69 7a 61 74 69 6f 6e 5d 20 69 73 20 64 69 73  mization] is dis
1a0d0 61 62 6c 65 64 20 61 6e 64 20 61 6c 6c 20 72 6f  abled and all ro
1a0e0 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20 69  ws are deleted i
1a0f0 6e 64 69 76 69 64 75 61 6c 6c 79 2e 0a 2a 2a 0a  ndividually..**.
1a100 2a 2a 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  ** An authorizer
1a110 20 69 73 20 75 73 65 64 20 77 68 65 6e 20 5b 73   is used when [s
1a120 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 20 7c  qlite3_prepare |
1a130 20 70 72 65 70 61 72 69 6e 67 5d 0a 2a 2a 20 53   preparing].** S
1a140 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 66 72  QL statements fr
1a150 6f 6d 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  om an untrusted 
1a160 73 6f 75 72 63 65 2c 20 74 6f 20 65 6e 73 75 72  source, to ensur
1a170 65 20 74 68 61 74 20 74 68 65 20 53 51 4c 20 73  e that the SQL s
1a180 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 64 6f 20  tatements.** do 
1a190 6e 6f 74 20 74 72 79 20 74 6f 20 61 63 63 65 73  not try to acces
1a1a0 73 20 64 61 74 61 20 74 68 65 79 20 61 72 65 20  s data they are 
1a1b0 6e 6f 74 20 61 6c 6c 6f 77 65 64 20 74 6f 20 73  not allowed to s
1a1c0 65 65 2c 20 6f 72 20 74 68 61 74 20 74 68 65 79  ee, or that they
1a1d0 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74 72 79 20 74   do not.** try t
1a1e0 6f 20 65 78 65 63 75 74 65 20 6d 61 6c 69 63 69  o execute malici
1a1f0 6f 75 73 20 73 74 61 74 65 6d 65 6e 74 73 20 74  ous statements t
1a200 68 61 74 20 64 61 6d 61 67 65 20 74 68 65 20 64  hat damage the d
1a210 61 74 61 62 61 73 65 2e 20 20 46 6f 72 0a 2a 2a  atabase.  For.**
1a220 20 65 78 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70   example, an app
1a230 6c 69 63 61 74 69 6f 6e 20 6d 61 79 20 61 6c 6c  lication may all
1a240 6f 77 20 61 20 75 73 65 72 20 74 6f 20 65 6e 74  ow a user to ent
1a250 65 72 20 61 72 62 69 74 72 61 72 79 0a 2a 2a 20  er arbitrary.** 
1a260 53 51 4c 20 71 75 65 72 69 65 73 20 66 6f 72 20  SQL queries for 
1a270 65 76 61 6c 75 61 74 69 6f 6e 20 62 79 20 61 20  evaluation by a 
1a280 64 61 74 61 62 61 73 65 2e 20 20 42 75 74 20 74  database.  But t
1a290 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
1a2a0 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77 61 6e 74 20  oes.** not want 
1a2b0 74 68 65 20 75 73 65 72 20 74 6f 20 62 65 20 61  the user to be a
1a2c0 62 6c 65 20 74 6f 20 6d 61 6b 65 20 61 72 62 69  ble to make arbi
1a2d0 74 72 61 72 79 20 63 68 61 6e 67 65 73 20 74 6f  trary changes to
1a2e0 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65   the.** database
1a2f0 2e 20 20 41 6e 20 61 75 74 68 6f 72 69 7a 65 72  .  An authorizer
1a300 20 63 6f 75 6c 64 20 74 68 65 6e 20 62 65 20 70   could then be p
1a310 75 74 20 69 6e 20 70 6c 61 63 65 20 77 68 69 6c  ut in place whil
1a320 65 20 74 68 65 0a 2a 2a 20 75 73 65 72 2d 65 6e  e the.** user-en
1a330 74 65 72 65 64 20 53 51 4c 20 69 73 20 62 65 69  tered SQL is bei
1a340 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
1a350 61 72 65 20 7c 20 70 72 65 70 61 72 65 64 5d 20  are | prepared] 
1a360 74 68 61 74 0a 2a 2a 20 64 69 73 61 6c 6c 6f 77  that.** disallow
1a370 73 20 65 76 65 72 79 74 68 69 6e 67 20 65 78 63  s everything exc
1a380 65 70 74 20 5b 53 45 4c 45 43 54 5d 20 73 74 61  ept [SELECT] sta
1a390 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 41  tements..**.** A
1a3a0 70 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74  pplications that
1a3b0 20 6e 65 65 64 20 74 6f 20 70 72 6f 63 65 73 73   need to process
1a3c0 20 53 51 4c 20 66 72 6f 6d 20 75 6e 74 72 75 73   SQL from untrus
1a3d0 74 65 64 20 73 6f 75 72 63 65 73 0a 2a 2a 20 6d  ted sources.** m
1a3e0 69 67 68 74 20 61 6c 73 6f 20 63 6f 6e 73 69 64  ight also consid
1a3f0 65 72 20 6c 6f 77 65 72 69 6e 67 20 72 65 73 6f  er lowering reso
1a400 75 72 63 65 20 6c 69 6d 69 74 73 20 75 73 69 6e  urce limits usin
1a410 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69 74  g [sqlite3_limit
1a420 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c 69 6d 69 74  ()].** and limit
1a430 69 6e 67 20 64 61 74 61 62 61 73 65 20 73 69 7a  ing database siz
1a440 65 20 75 73 69 6e 67 20 74 68 65 20 5b 6d 61 78  e using the [max
1a450 5f 70 61 67 65 5f 63 6f 75 6e 74 5d 20 5b 50 52  _page_count] [PR
1a460 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20 61 64 64 69  AGMA].** in addi
1a470 74 69 6f 6e 20 74 6f 20 75 73 69 6e 67 20 61 6e  tion to using an
1a480 20 61 75 74 68 6f 72 69 7a 65 72 2e 0a 2a 2a 0a   authorizer..**.
1a490 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20 73 69 6e 67  ** ^(Only a sing
1a4a0 6c 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  le authorizer ca
1a4b0 6e 20 62 65 20 69 6e 20 70 6c 61 63 65 20 6f 6e  n be in place on
1a4c0 20 61 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e   a database conn
1a4d0 65 63 74 69 6f 6e 0a 2a 2a 20 61 74 20 61 20 74  ection.** at a t
1a4e0 69 6d 65 2e 20 20 45 61 63 68 20 63 61 6c 6c 20  ime.  Each call 
1a4f0 74 6f 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  to sqlite3_set_a
1a500 75 74 68 6f 72 69 7a 65 72 20 6f 76 65 72 72 69  uthorizer overri
1a510 64 65 73 20 74 68 65 0a 2a 2a 20 70 72 65 76 69  des the.** previ
1a520 6f 75 73 20 63 61 6c 6c 2e 29 5e 20 20 5e 44 69  ous call.)^  ^Di
1a530 73 61 62 6c 65 20 74 68 65 20 61 75 74 68 6f 72  sable the author
1a540 69 7a 65 72 20 62 79 20 69 6e 73 74 61 6c 6c 69  izer by installi
1a550 6e 67 20 61 20 4e 55 4c 4c 20 63 61 6c 6c 62 61  ng a NULL callba
1a560 63 6b 2e 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f  ck..** The autho
1a570 72 69 7a 65 72 20 69 73 20 64 69 73 61 62 6c 65  rizer is disable
1a580 64 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  d by default..**
1a590 0a 2a 2a 20 54 68 65 20 61 75 74 68 6f 72 69 7a  .** The authoriz
1a5a0 65 72 20 63 61 6c 6c 62 61 63 6b 20 6d 75 73 74  er callback must
1a5b0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
1a5c0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
1a5d0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
1a5e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
1a5f0 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 61 75  t invoked the au
1a600 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63  thorizer callbac
1a610 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74 20  k..** Note that 
1a620 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
1a630 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  _v2()] and [sqli
1a640 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74 68  te3_step()] both
1a650 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a 2a   modify their.**
1a660 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1a670 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d 65  tions for the me
1a680 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66 79  aning of "modify
1a690 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67 72  " in this paragr
1a6a0 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  aph..**.** ^When
1a6b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a6c0 65 5f 76 32 28 29 5d 20 69 73 20 75 73 65 64 20  e_v2()] is used 
1a6d0 74 6f 20 70 72 65 70 61 72 65 20 61 20 73 74 61  to prepare a sta
1a6e0 74 65 6d 65 6e 74 2c 20 74 68 65 0a 2a 2a 20 73  tement, the.** s
1a6f0 74 61 74 65 6d 65 6e 74 20 6d 69 67 68 74 20 62  tatement might b
1a700 65 20 72 65 2d 70 72 65 70 61 72 65 64 20 64 75  e re-prepared du
1a710 72 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74  ring [sqlite3_st
1a720 65 70 28 29 5d 20 64 75 65 20 74 6f 20 61 20 0a  ep()] due to a .
1a730 2a 2a 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  ** schema change
1a740 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 61 70  .  Hence, the ap
1a750 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c 64  plication should
1a760 20 65 6e 73 75 72 65 20 74 68 61 74 20 74 68 65   ensure that the
1a770 0a 2a 2a 20 63 6f 72 72 65 63 74 20 61 75 74 68  .** correct auth
1a780 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
1a790 72 65 6d 61 69 6e 73 20 69 6e 20 70 6c 61 63 65  remains in place
1a7a0 20 64 75 72 69 6e 67 20 74 68 65 20 5b 73 71 6c   during the [sql
1a7b0 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 0a 2a 2a  ite3_step()]..**
1a7c0 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  .** ^Note that t
1a7d0 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1a7e0 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
1a7f0 64 20 6f 6e 6c 79 20 64 75 72 69 6e 67 0a 2a 2a  d only during.**
1a800 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1a810 65 28 29 5d 20 6f 72 20 69 74 73 20 76 61 72 69  e()] or its vari
1a820 61 6e 74 73 2e 20 20 41 75 74 68 6f 72 69 7a 61  ants.  Authoriza
1a830 74 69 6f 6e 20 69 73 20 6e 6f 74 0a 2a 2a 20 70  tion is not.** p
1a840 65 72 66 6f 72 6d 65 64 20 64 75 72 69 6e 67 20  erformed during 
1a850 73 74 61 74 65 6d 65 6e 74 20 65 76 61 6c 75 61  statement evalua
1a860 74 69 6f 6e 20 69 6e 20 5b 73 71 6c 69 74 65 33  tion in [sqlite3
1a870 5f 73 74 65 70 28 29 5d 2c 20 75 6e 6c 65 73 73  _step()], unless
1a880 0a 2a 2a 20 61 73 20 73 74 61 74 65 64 20 69 6e  .** as stated in
1a890 20 74 68 65 20 70 72 65 76 69 6f 75 73 20 70 61   the previous pa
1a8a0 72 61 67 72 61 70 68 2c 20 73 71 6c 69 74 65 33  ragraph, sqlite3
1a8b0 5f 73 74 65 70 28 29 20 69 6e 76 6f 6b 65 73 0a  _step() invokes.
1a8c0 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  ** sqlite3_prepa
1a8d0 72 65 5f 76 32 28 29 20 74 6f 20 72 65 70 72 65  re_v2() to repre
1a8e0 70 61 72 65 20 61 20 73 74 61 74 65 6d 65 6e 74  pare a statement
1a8f0 20 61 66 74 65 72 20 61 20 73 63 68 65 6d 61 20   after a schema 
1a900 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69 6e 74 20 73  change..*/.int s
1a910 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f  qlite3_set_autho
1a920 72 69 7a 65 72 28 0a 20 20 73 71 6c 69 74 65 33  rizer(.  sqlite3
1a930 2a 2c 0a 20 20 69 6e 74 20 28 2a 78 41 75 74 68  *,.  int (*xAuth
1a940 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
1a950 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1a960 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 2c  ar*,const char*,
1a970 63 6f 6e 73 74 20 63 68 61 72 2a 29 2c 0a 20 20  const char*),.  
1a980 76 6f 69 64 20 2a 70 55 73 65 72 44 61 74 61 0a  void *pUserData.
1a990 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1a9a0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 52  EF: Authorizer R
1a9b0 65 74 75 72 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  eturn Codes.**.*
1a9c0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1a9d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 7c 20  et_authorizer | 
1a9e0 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
1a9f0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 5d 20 6d 75  ack function] mu
1aa00 73 74 0a 2a 2a 20 72 65 74 75 72 6e 20 65 69 74  st.** return eit
1aa10 68 65 72 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  her [SQLITE_OK] 
1aa20 6f 72 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  or one of these 
1aa30 74 77 6f 20 63 6f 6e 73 74 61 6e 74 73 20 69 6e  two constants in
1aa40 20 6f 72 64 65 72 0a 2a 2a 20 74 6f 20 73 69 67   order.** to sig
1aa50 6e 61 6c 20 53 51 4c 69 74 65 20 77 68 65 74 68  nal SQLite wheth
1aa60 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 61 63  er or not the ac
1aa70 74 69 6f 6e 20 69 73 20 70 65 72 6d 69 74 74 65  tion is permitte
1aa80 64 2e 20 20 53 65 65 20 74 68 65 0a 2a 2a 20 5b  d.  See the.** [
1aa90 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68  sqlite3_set_auth
1aaa0 6f 72 69 7a 65 72 20 7c 20 61 75 74 68 6f 72 69  orizer | authori
1aab0 7a 65 72 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f  zer documentatio
1aac0 6e 5d 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61  n] for additiona
1aad0 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  l.** information
1aae0 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
1aaf0 74 20 53 51 4c 49 54 45 5f 49 47 4e 4f 52 45 20  t SQLITE_IGNORE 
1ab00 69 73 20 61 6c 73 6f 20 75 73 65 64 20 61 73 20  is also used as 
1ab10 61 20 5b 53 51 4c 49 54 45 5f 52 4f 4c 4c 42 41  a [SQLITE_ROLLBA
1ab20 43 4b 20 7c 20 72 65 74 75 72 6e 20 63 6f 64 65  CK | return code
1ab30 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68 65 20 5b 73  ].** from the [s
1ab40 71 6c 69 74 65 33 5f 76 74 61 62 5f 6f 6e 5f 63  qlite3_vtab_on_c
1ab50 6f 6e 66 6c 69 63 74 28 29 5d 20 69 6e 74 65 72  onflict()] inter
1ab60 66 61 63 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  face..*/.#define
1ab70 20 53 51 4c 49 54 45 5f 44 45 4e 59 20 20 20 31   SQLITE_DENY   1
1ab80 20 20 20 2f 2a 20 41 62 6f 72 74 20 74 68 65 20     /* Abort the 
1ab90 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77 69  SQL statement wi
1aba0 74 68 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 23  th an error */.#
1abb0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 47  define SQLITE_IG
1abc0 4e 4f 52 45 20 32 20 20 20 2f 2a 20 44 6f 6e 27  NORE 2   /* Don'
1abd0 74 20 61 6c 6c 6f 77 20 61 63 63 65 73 73 2c 20  t allow access, 
1abe0 62 75 74 20 64 6f 6e 27 74 20 67 65 6e 65 72 61  but don't genera
1abf0 74 65 20 61 6e 20 65 72 72 6f 72 20 2a 2f 0a 0a  te an error */..
1ac00 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1ac10 41 75 74 68 6f 72 69 7a 65 72 20 41 63 74 69 6f  Authorizer Actio
1ac20 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68  n Codes.**.** Th
1ac30 65 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  e [sqlite3_set_a
1ac40 75 74 68 6f 72 69 7a 65 72 28 29 5d 20 69 6e 74  uthorizer()] int
1ac50 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
1ac60 20 61 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63   a callback func
1ac70 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 69 73 20  tion.** that is 
1ac80 69 6e 76 6f 6b 65 64 20 74 6f 20 61 75 74 68 6f  invoked to autho
1ac90 72 69 7a 65 20 63 65 72 74 61 69 6e 20 53 51 4c  rize certain SQL
1aca0 20 73 74 61 74 65 6d 65 6e 74 20 61 63 74 69 6f   statement actio
1acb0 6e 73 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ns.  The.** seco
1acc0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  nd parameter to 
1acd0 74 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  the callback is 
1ace0 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64 65 20  an integer code 
1acf0 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a 2a  that specifies.*
1ad00 2a 20 77 68 61 74 20 61 63 74 69 6f 6e 20 69 73  * what action is
1ad10 20 62 65 69 6e 67 20 61 75 74 68 6f 72 69 7a 65   being authorize
1ad20 64 2e 20 20 54 68 65 73 65 20 61 72 65 20 74 68  d.  These are th
1ad30 65 20 69 6e 74 65 67 65 72 20 61 63 74 69 6f 6e  e integer action
1ad40 20 63 6f 64 65 73 20 74 68 61 74 0a 2a 2a 20 74   codes that.** t
1ad50 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
1ad60 6c 6c 62 61 63 6b 20 6d 61 79 20 62 65 20 70 61  llback may be pa
1ad70 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ssed..**.** Thes
1ad80 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 76 61  e action code va
1ad90 6c 75 65 73 20 73 69 67 6e 69 66 79 20 77 68 61  lues signify wha
1ada0 74 20 6b 69 6e 64 20 6f 66 20 6f 70 65 72 61 74  t kind of operat
1adb0 69 6f 6e 20 69 73 20 74 6f 20 62 65 0a 2a 2a 20  ion is to be.** 
1adc0 61 75 74 68 6f 72 69 7a 65 64 2e 20 20 54 68 65  authorized.  The
1add0 20 33 72 64 20 61 6e 64 20 34 74 68 20 70 61 72   3rd and 4th par
1ade0 61 6d 65 74 65 72 73 20 74 6f 20 74 68 65 20 61  ameters to the a
1adf0 75 74 68 6f 72 69 7a 61 74 69 6f 6e 0a 2a 2a 20  uthorization.** 
1ae00 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f  callback functio
1ae10 6e 20 77 69 6c 6c 20 62 65 20 70 61 72 61 6d 65  n will be parame
1ae20 74 65 72 73 20 6f 72 20 4e 55 4c 4c 20 64 65 70  ters or NULL dep
1ae30 65 6e 64 69 6e 67 20 6f 6e 20 77 68 69 63 68 20  ending on which 
1ae40 6f 66 20 74 68 65 73 65 0a 2a 2a 20 63 6f 64 65  of these.** code
1ae50 73 20 69 73 20 75 73 65 64 20 61 73 20 74 68 65  s is used as the
1ae60 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
1ae70 72 2e 20 20 5e 28 54 68 65 20 35 74 68 20 70 61  r.  ^(The 5th pa
1ae80 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 0a 2a  rameter to the.*
1ae90 2a 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  * authorizer cal
1aea0 6c 62 61 63 6b 20 69 73 20 74 68 65 20 6e 61 6d  lback is the nam
1aeb0 65 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  e of the databas
1aec0 65 20 28 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e ("main", "temp
1aed0 22 2c 0a 2a 2a 20 65 74 63 2e 29 20 69 66 20 61  ",.** etc.) if a
1aee0 70 70 6c 69 63 61 62 6c 65 2e 29 5e 20 20 5e 54  pplicable.)^  ^T
1aef0 68 65 20 36 74 68 20 70 61 72 61 6d 65 74 65 72  he 6th parameter
1af00 20 74 6f 20 74 68 65 20 61 75 74 68 6f 72 69 7a   to the authoriz
1af10 65 72 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 69  er callback.** i
1af20 73 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  s the name of th
1af30 65 20 69 6e 6e 65 72 2d 6d 6f 73 74 20 74 72 69  e inner-most tri
1af40 67 67 65 72 20 6f 72 20 76 69 65 77 20 74 68 61  gger or view tha
1af50 74 20 69 73 20 72 65 73 70 6f 6e 73 69 62 6c 65  t is responsible
1af60 20 66 6f 72 0a 2a 2a 20 74 68 65 20 61 63 63 65   for.** the acce
1af70 73 73 20 61 74 74 65 6d 70 74 20 6f 72 20 4e 55  ss attempt or NU
1af80 4c 4c 20 69 66 20 74 68 69 73 20 61 63 63 65 73  LL if this acces
1af90 73 20 61 74 74 65 6d 70 74 20 69 73 20 64 69 72  s attempt is dir
1afa0 65 63 74 6c 79 20 66 72 6f 6d 0a 2a 2a 20 74 6f  ectly from.** to
1afb0 70 2d 6c 65 76 65 6c 20 53 51 4c 20 63 6f 64 65  p-level SQL code
1afc0 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ..*/./**********
1afd0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1afe0 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1aff0 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  * 3rd **********
1b000 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a 2a 2a 2a 2a  ** 4th *********
1b010 2a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  **/.#define SQLI
1b020 54 45 5f 43 52 45 41 54 45 5f 49 4e 44 45 58 20  TE_CREATE_INDEX 
1b030 20 20 20 20 20 20 20 20 20 31 20 20 20 2f 2a 20           1   /* 
1b040 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20  Index Name      
1b050 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1b060 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b070 45 5f 43 52 45 41 54 45 5f 54 41 42 4c 45 20 20  E_CREATE_TABLE  
1b080 20 20 20 20 20 20 20 20 32 20 20 20 2f 2a 20 54          2   /* T
1b090 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b0a0 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b0b0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b0c0 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 49 4e 44  _CREATE_TEMP_IND
1b0d0 45 58 20 20 20 20 20 33 20 20 20 2f 2a 20 49 6e  EX     3   /* In
1b0e0 64 65 78 20 4e 61 6d 65 20 20 20 20 20 20 54 61  dex Name      Ta
1b0f0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1b100 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b110 43 52 45 41 54 45 5f 54 45 4d 50 5f 54 41 42 4c  CREATE_TEMP_TABL
1b120 45 20 20 20 20 20 34 20 20 20 2f 2a 20 54 61 62  E     4   /* Tab
1b130 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c  le Name      NUL
1b140 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1b150 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43  #define SQLITE_C
1b160 52 45 41 54 45 5f 54 45 4d 50 5f 54 52 49 47 47  REATE_TEMP_TRIGG
1b170 45 52 20 20 20 35 20 20 20 2f 2a 20 54 72 69 67  ER   5   /* Trig
1b180 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c  ger Name    Tabl
1b190 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23  e Name      */.#
1b1a0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52  define SQLITE_CR
1b1b0 45 41 54 45 5f 54 45 4d 50 5f 56 49 45 57 20 20  EATE_TEMP_VIEW  
1b1c0 20 20 20 20 36 20 20 20 2f 2a 20 56 69 65 77 20      6   /* View 
1b1d0 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20  Name       NULL 
1b1e0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b1f0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45  efine SQLITE_CRE
1b200 41 54 45 5f 54 52 49 47 47 45 52 20 20 20 20 20  ATE_TRIGGER     
1b210 20 20 20 37 20 20 20 2f 2a 20 54 72 69 67 67 65     7   /* Trigge
1b220 72 20 4e 61 6d 65 20 20 20 20 54 61 62 6c 65 20  r Name    Table 
1b230 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65  Name      */.#de
1b240 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41  fine SQLITE_CREA
1b250 54 45 5f 56 49 45 57 20 20 20 20 20 20 20 20 20  TE_VIEW         
1b260 20 20 38 20 20 20 2f 2a 20 56 69 65 77 20 4e 61    8   /* View Na
1b270 6d 65 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  me       NULL   
1b280 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b290 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4c 45 54  ine SQLITE_DELET
1b2a0 45 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  E               
1b2b0 20 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61   9   /* Table Na
1b2c0 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1b2d0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b2e0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 49  ne SQLITE_DROP_I
1b2f0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 31  NDEX           1
1b300 30 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d  0   /* Index Nam
1b310 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  e      Table Nam
1b320 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b330 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 41  e SQLITE_DROP_TA
1b340 42 4c 45 20 20 20 20 20 20 20 20 20 20 20 31 31  BLE           11
1b350 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65     /* Table Name
1b360 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b370 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b380 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d   SQLITE_DROP_TEM
1b390 50 5f 49 4e 44 45 58 20 20 20 20 20 20 31 32 20  P_INDEX      12 
1b3a0 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20    /* Index Name 
1b3b0 20 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20       Table Name 
1b3c0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b3d0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50  SQLITE_DROP_TEMP
1b3e0 5f 54 41 42 4c 45 20 20 20 20 20 20 31 33 20 20  _TABLE      13  
1b3f0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b400 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1b410 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b420 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f  QLITE_DROP_TEMP_
1b430 54 52 49 47 47 45 52 20 20 20 20 31 34 20 20 20  TRIGGER    14   
1b440 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20  /* Trigger Name 
1b450 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20     Table Name   
1b460 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b470 4c 49 54 45 5f 44 52 4f 50 5f 54 45 4d 50 5f 56  LITE_DROP_TEMP_V
1b480 49 45 57 20 20 20 20 20 20 20 31 35 20 20 20 2f  IEW       15   /
1b490 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20  * View Name     
1b4a0 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20    NULL          
1b4b0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b4c0 49 54 45 5f 44 52 4f 50 5f 54 52 49 47 47 45 52  ITE_DROP_TRIGGER
1b4d0 20 20 20 20 20 20 20 20 20 31 36 20 20 20 2f 2a           16   /*
1b4e0 20 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20   Trigger Name   
1b4f0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1b500 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1b510 54 45 5f 44 52 4f 50 5f 56 49 45 57 20 20 20 20  TE_DROP_VIEW    
1b520 20 20 20 20 20 20 20 20 31 37 20 20 20 2f 2a 20          17   /* 
1b530 56 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20  View Name       
1b540 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1b550 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1b560 45 5f 49 4e 53 45 52 54 20 20 20 20 20 20 20 20  E_INSERT        
1b570 20 20 20 20 20 20 20 31 38 20 20 20 2f 2a 20 54         18   /* T
1b580 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 4e  able Name      N
1b590 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1b5a0 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1b5b0 5f 50 52 41 47 4d 41 20 20 20 20 20 20 20 20 20  _PRAGMA         
1b5c0 20 20 20 20 20 20 31 39 20 20 20 2f 2a 20 50 72        19   /* Pr
1b5d0 61 67 6d 61 20 4e 61 6d 65 20 20 20 20 20 31 73  agma Name     1s
1b5e0 74 20 61 72 67 20 6f 72 20 4e 55 4c 4c 20 2a 2f  t arg or NULL */
1b5f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1b600 52 45 41 44 20 20 20 20 20 20 20 20 20 20 20 20  READ            
1b610 20 20 20 20 20 32 30 20 20 20 2f 2a 20 54 61 62       20   /* Tab
1b620 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c  le Name      Col
1b630 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a  umn Name     */.
1b640 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53  #define SQLITE_S
1b650 45 4c 45 43 54 20 20 20 20 20 20 20 20 20 20 20  ELECT           
1b660 20 20 20 20 32 31 20 20 20 2f 2a 20 4e 55 4c 4c      21   /* NULL
1b670 20 20 20 20 20 20 20 20 20 20 20 20 4e 55 4c 4c              NULL
1b680 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1b690 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 52  define SQLITE_TR
1b6a0 41 4e 53 41 43 54 49 4f 4e 20 20 20 20 20 20 20  ANSACTION       
1b6b0 20 20 20 32 32 20 20 20 2f 2a 20 4f 70 65 72 61     22   /* Opera
1b6c0 74 69 6f 6e 20 20 20 20 20 20 20 4e 55 4c 4c 20  tion       NULL 
1b6d0 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64             */.#d
1b6e0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 55 50 44  efine SQLITE_UPD
1b6f0 41 54 45 20 20 20 20 20 20 20 20 20 20 20 20 20  ATE             
1b700 20 20 32 33 20 20 20 2f 2a 20 54 61 62 6c 65 20    23   /* Table 
1b710 4e 61 6d 65 20 20 20 20 20 20 43 6f 6c 75 6d 6e  Name      Column
1b720 20 4e 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65   Name     */.#de
1b730 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 54 54 41  fine SQLITE_ATTA
1b740 43 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20  CH              
1b750 20 32 34 20 20 20 2f 2a 20 46 69 6c 65 6e 61 6d   24   /* Filenam
1b760 65 20 20 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  e        NULL   
1b770 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b780 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 54 41 43  ine SQLITE_DETAC
1b790 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
1b7a0 32 35 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  25   /* Database
1b7b0 20 4e 61 6d 65 20 20 20 4e 55 4c 4c 20 20 20 20   Name   NULL    
1b7c0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1b7d0 6e 65 20 53 51 4c 49 54 45 5f 41 4c 54 45 52 5f  ne SQLITE_ALTER_
1b7e0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 32  TABLE          2
1b7f0 36 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20  6   /* Database 
1b800 4e 61 6d 65 20 20 20 54 61 62 6c 65 20 4e 61 6d  Name   Table Nam
1b810 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1b820 65 20 53 51 4c 49 54 45 5f 52 45 49 4e 44 45 58  e SQLITE_REINDEX
1b830 20 20 20 20 20 20 20 20 20 20 20 20 20 20 32 37                27
1b840 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65     /* Index Name
1b850 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1b860 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1b870 20 53 51 4c 49 54 45 5f 41 4e 41 4c 59 5a 45 20   SQLITE_ANALYZE 
1b880 20 20 20 20 20 20 20 20 20 20 20 20 20 32 38 20               28 
1b890 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20    /* Table Name 
1b8a0 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20       NULL       
1b8b0 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1b8c0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 56 54  SQLITE_CREATE_VT
1b8d0 41 42 4c 45 20 20 20 20 20 20 20 20 32 39 20 20  ABLE        29  
1b8e0 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20   /* Table Name  
1b8f0 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20      Module Name 
1b900 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1b910 51 4c 49 54 45 5f 44 52 4f 50 5f 56 54 41 42 4c  QLITE_DROP_VTABL
1b920 45 20 20 20 20 20 20 20 20 20 20 33 30 20 20 20  E          30   
1b930 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1b940 20 20 20 4d 6f 64 75 6c 65 20 4e 61 6d 65 20 20     Module Name  
1b950 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1b960 4c 49 54 45 5f 46 55 4e 43 54 49 4f 4e 20 20 20  LITE_FUNCTION   
1b970 20 20 20 20 20 20 20 20 20 20 33 31 20 20 20 2f            31   /
1b980 2a 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20  * NULL          
1b990 20 20 46 75 6e 63 74 69 6f 6e 20 4e 61 6d 65 20    Function Name 
1b9a0 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1b9b0 49 54 45 5f 53 41 56 45 50 4f 49 4e 54 20 20 20  ITE_SAVEPOINT   
1b9c0 20 20 20 20 20 20 20 20 20 33 32 20 20 20 2f 2a           32   /*
1b9d0 20 4f 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20   Operation      
1b9e0 20 53 61 76 65 70 6f 69 6e 74 20 4e 61 6d 65 20   Savepoint Name 
1b9f0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ba00 54 45 5f 43 4f 50 59 20 20 20 20 20 20 20 20 20  TE_COPY         
1ba10 20 20 20 20 20 20 20 20 20 30 20 20 20 2f 2a 20           0   /* 
1ba20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73 65 64 20 2a  No longer used *
1ba30 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
1ba40 46 3a 20 54 72 61 63 69 6e 67 20 41 6e 64 20 50  F: Tracing And P
1ba50 72 6f 66 69 6c 69 6e 67 20 46 75 6e 63 74 69 6f  rofiling Functio
1ba60 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  ns.**.** These r
1ba70 6f 75 74 69 6e 65 73 20 72 65 67 69 73 74 65 72  outines register
1ba80 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69   callback functi
1ba90 6f 6e 73 20 74 68 61 74 20 63 61 6e 20 62 65 20  ons that can be 
1baa0 75 73 65 64 20 66 6f 72 0a 2a 2a 20 74 72 61 63  used for.** trac
1bab0 69 6e 67 20 61 6e 64 20 70 72 6f 66 69 6c 69 6e  ing and profilin
1bac0 67 20 74 68 65 20 65 78 65 63 75 74 69 6f 6e 20  g the execution 
1bad0 6f 66 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  of SQL statement
1bae0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 61  s..**.** ^The ca
1baf0 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20  llback function 
1bb00 72 65 67 69 73 74 65 72 65 64 20 62 79 20 73 71  registered by sq
1bb10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 69 73  lite3_trace() is
1bb20 20 69 6e 76 6f 6b 65 64 20 61 74 0a 2a 2a 20 76   invoked at.** v
1bb30 61 72 69 6f 75 73 20 74 69 6d 65 73 20 77 68 65  arious times whe
1bb40 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  n an SQL stateme
1bb50 6e 74 20 69 73 20 62 65 69 6e 67 20 72 75 6e 20  nt is being run 
1bb60 62 79 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  by [sqlite3_step
1bb70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ()]..** ^The sql
1bb80 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61 6c  ite3_trace() cal
1bb90 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
1bba0 20 77 69 74 68 20 61 20 55 54 46 2d 38 20 72 65   with a UTF-8 re
1bbb0 6e 64 65 72 69 6e 67 20 6f 66 20 74 68 65 0a 2a  ndering of the.*
1bbc0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  * SQL statement 
1bbd0 74 65 78 74 20 61 73 20 74 68 65 20 73 74 61 74  text as the stat
1bbe0 65 6d 65 6e 74 20 66 69 72 73 74 20 62 65 67 69  ement first begi
1bbf0 6e 73 20 65 78 65 63 75 74 69 6e 67 2e 0a 2a 2a  ns executing..**
1bc00 20 5e 28 41 64 64 69 74 69 6f 6e 61 6c 20 73 71   ^(Additional sq
1bc10 6c 69 74 65 33 5f 74 72 61 63 65 28 29 20 63 61  lite3_trace() ca
1bc20 6c 6c 62 61 63 6b 73 20 6d 69 67 68 74 20 6f 63  llbacks might oc
1bc30 63 75 72 0a 2a 2a 20 61 73 20 65 61 63 68 20 74  cur.** as each t
1bc40 72 69 67 67 65 72 65 64 20 73 75 62 70 72 6f 67  riggered subprog
1bc50 72 61 6d 20 69 73 20 65 6e 74 65 72 65 64 2e 20  ram is entered. 
1bc60 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 73 20 66   The callbacks f
1bc70 6f 72 20 74 72 69 67 67 65 72 73 0a 2a 2a 20 63  or triggers.** c
1bc80 6f 6e 74 61 69 6e 20 61 20 55 54 46 2d 38 20 53  ontain a UTF-8 S
1bc90 51 4c 20 63 6f 6d 6d 65 6e 74 20 74 68 61 74 20  QL comment that 
1bca0 69 64 65 6e 74 69 66 69 65 73 20 74 68 65 20 74  identifies the t
1bcb0 72 69 67 67 65 72 2e 29 5e 0a 2a 2a 0a 2a 2a 20  rigger.)^.**.** 
1bcc0 5e 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 66 75  ^The callback fu
1bcd0 6e 63 74 69 6f 6e 20 72 65 67 69 73 74 65 72 65  nction registere
1bce0 64 20 62 79 20 73 71 6c 69 74 65 33 5f 70 72 6f  d by sqlite3_pro
1bcf0 66 69 6c 65 28 29 20 69 73 20 69 6e 76 6f 6b 65  file() is invoke
1bd00 64 0a 2a 2a 20 61 73 20 65 61 63 68 20 53 51 4c  d.** as each SQL
1bd10 20 73 74 61 74 65 6d 65 6e 74 20 66 69 6e 69 73   statement finis
1bd20 68 65 73 2e 20 20 5e 54 68 65 20 70 72 6f 66 69  hes.  ^The profi
1bd30 6c 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  le callback cont
1bd40 61 69 6e 73 0a 2a 2a 20 74 68 65 20 6f 72 69 67  ains.** the orig
1bd50 69 6e 61 6c 20 73 74 61 74 65 6d 65 6e 74 20 74  inal statement t
1bd60 65 78 74 20 61 6e 64 20 61 6e 20 65 73 74 69 6d  ext and an estim
1bd70 61 74 65 20 6f 66 20 77 61 6c 6c 2d 63 6c 6f 63  ate of wall-cloc
1bd80 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66 20 68 6f 77  k time.** of how
1bd90 20 6c 6f 6e 67 20 74 68 61 74 20 73 74 61 74 65   long that state
1bda0 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f 20 72 75 6e  ment took to run
1bdb0 2e 20 20 5e 54 68 65 20 70 72 6f 66 69 6c 65 20  .  ^The profile 
1bdc0 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 74 69 6d 65  callback.** time
1bdd0 20 69 73 20 69 6e 20 75 6e 69 74 73 20 6f 66 20   is in units of 
1bde0 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c 20 68 6f 77  nanoseconds, how
1bdf0 65 76 65 72 20 74 68 65 20 63 75 72 72 65 6e 74  ever the current
1be00 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 0a   implementation.
1be10 2a 2a 20 69 73 20 6f 6e 6c 79 20 63 61 70 61 62  ** is only capab
1be20 6c 65 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f 6e  le of millisecon
1be30 64 20 72 65 73 6f 6c 75 74 69 6f 6e 20 73 6f 20  d resolution so 
1be40 74 68 65 20 73 69 78 20 6c 65 61 73 74 20 73 69  the six least si
1be50 67 6e 69 66 69 63 61 6e 74 0a 2a 2a 20 64 69 67  gnificant.** dig
1be60 69 74 73 20 69 6e 20 74 68 65 20 74 69 6d 65 20  its in the time 
1be70 61 72 65 20 6d 65 61 6e 69 6e 67 6c 65 73 73 2e  are meaningless.
1be80 20 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e    Future version
1be90 73 20 6f 66 20 53 51 4c 69 74 65 0a 2a 2a 20 6d  s of SQLite.** m
1bea0 69 67 68 74 20 70 72 6f 76 69 64 65 20 67 72 65  ight provide gre
1beb0 61 74 65 72 20 72 65 73 6f 6c 75 74 69 6f 6e 20  ater resolution 
1bec0 6f 6e 20 74 68 65 20 70 72 6f 66 69 6c 65 72 20  on the profiler 
1bed0 63 61 6c 6c 62 61 63 6b 2e 20 20 54 68 65 0a 2a  callback.  The.*
1bee0 2a 20 73 71 6c 69 74 65 33 5f 70 72 6f 66 69 6c  * sqlite3_profil
1bef0 65 28 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  e() function is 
1bf00 63 6f 6e 73 69 64 65 72 65 64 20 65 78 70 65 72  considered exper
1bf10 69 6d 65 6e 74 61 6c 20 61 6e 64 20 69 73 0a 2a  imental and is.*
1bf20 2a 20 73 75 62 6a 65 63 74 20 74 6f 20 63 68 61  * subject to cha
1bf30 6e 67 65 20 69 6e 20 66 75 74 75 72 65 20 76 65  nge in future ve
1bf40 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65  rsions of SQLite
1bf50 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
1bf60 65 33 5f 74 72 61 63 65 28 73 71 6c 69 74 65 33  e3_trace(sqlite3
1bf70 2a 2c 20 76 6f 69 64 28 2a 78 54 72 61 63 65 29  *, void(*xTrace)
1bf80 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20 63 68 61  (void*,const cha
1bf90 72 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 53 51 4c  r*), void*);.SQL
1bfa0 49 54 45 5f 45 58 50 45 52 49 4d 45 4e 54 41 4c  ITE_EXPERIMENTAL
1bfb0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 70   void *sqlite3_p
1bfc0 72 6f 66 69 6c 65 28 73 71 6c 69 74 65 33 2a 2c  rofile(sqlite3*,
1bfd0 0a 20 20 20 76 6f 69 64 28 2a 78 50 72 6f 66 69  .   void(*xProfi
1bfe0 6c 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74 20  le)(void*,const 
1bff0 63 68 61 72 2a 2c 73 71 6c 69 74 65 33 5f 75 69  char*,sqlite3_ui
1c000 6e 74 36 34 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a  nt64), void*);..
1c010 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
1c020 51 75 65 72 79 20 50 72 6f 67 72 65 73 73 20 43  Query Progress C
1c030 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
1c040 54 68 65 20 73 71 6c 69 74 65 33 5f 70 72 6f 67  The sqlite3_prog
1c050 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 44 2c 4e  ress_handler(D,N
1c060 2c 58 2c 50 29 20 69 6e 74 65 72 66 61 63 65 20  ,X,P) interface 
1c070 63 61 75 73 65 73 20 74 68 65 20 63 61 6c 6c 62  causes the callb
1c080 61 63 6b 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ack.** function 
1c090 58 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  X to be invoked 
1c0a0 70 65 72 69 6f 64 69 63 61 6c 6c 79 20 64 75 72  periodically dur
1c0b0 69 6e 67 20 6c 6f 6e 67 20 72 75 6e 6e 69 6e 67  ing long running
1c0c0 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20 5b 73 71   calls to.** [sq
1c0d0 6c 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 5b  lite3_exec()], [
1c0e0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
1c0f0 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 67 65 74  and [sqlite3_get
1c100 5f 74 61 62 6c 65 28 29 5d 20 66 6f 72 0a 2a 2a  _table()] for.**
1c110 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1c120 74 69 6f 6e 20 44 2e 20 20 41 6e 20 65 78 61 6d  tion D.  An exam
1c130 70 6c 65 20 75 73 65 20 66 6f 72 20 74 68 69 73  ple use for this
1c140 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1c150 20 74 6f 20 6b 65 65 70 20 61 20 47 55 49 20 75   to keep a GUI u
1c160 70 64 61 74 65 64 20 64 75 72 69 6e 67 20 61 20  pdated during a 
1c170 6c 61 72 67 65 20 71 75 65 72 79 2e 0a 2a 2a 0a  large query..**.
1c180 2a 2a 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65  ** ^The paramete
1c190 72 20 50 20 69 73 20 70 61 73 73 65 64 20 74 68  r P is passed th
1c1a0 72 6f 75 67 68 20 61 73 20 74 68 65 20 6f 6e 6c  rough as the onl
1c1b0 79 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  y parameter to t
1c1c0 68 65 20 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20  he .** callback 
1c1d0 66 75 6e 63 74 69 6f 6e 20 58 2e 20 20 5e 54 68  function X.  ^Th
1c1e0 65 20 70 61 72 61 6d 65 74 65 72 20 4e 20 69 73  e parameter N is
1c1f0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 0a   the number of .
1c200 2a 2a 20 5b 76 69 72 74 75 61 6c 20 6d 61 63 68  ** [virtual mach
1c210 69 6e 65 20 69 6e 73 74 72 75 63 74 69 6f 6e 73  ine instructions
1c220 5d 20 74 68 61 74 20 61 72 65 20 65 76 61 6c 75  ] that are evalu
1c230 61 74 65 64 20 62 65 74 77 65 65 6e 20 73 75 63  ated between suc
1c240 63 65 73 73 69 76 65 0a 2a 2a 20 69 6e 76 6f 63  cessive.** invoc
1c250 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 63 61  ations of the ca
1c260 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a 0a 2a 2a 20  llback X..**.** 
1c270 5e 4f 6e 6c 79 20 61 20 73 69 6e 67 6c 65 20 70  ^Only a single p
1c280 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 20  rogress handler 
1c290 6d 61 79 20 62 65 20 64 65 66 69 6e 65 64 20 61  may be defined a
1c2a0 74 20 6f 6e 65 20 74 69 6d 65 20 70 65 72 0a 2a  t one time per.*
1c2b0 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  * [database conn
1c2c0 65 63 74 69 6f 6e 5d 3b 20 73 65 74 74 69 6e 67  ection]; setting
1c2d0 20 61 20 6e 65 77 20 70 72 6f 67 72 65 73 73 20   a new progress 
1c2e0 68 61 6e 64 6c 65 72 20 63 61 6e 63 65 6c 73 20  handler cancels 
1c2f0 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f 6e 65 2e 20  the.** old one. 
1c300 20 5e 53 65 74 74 69 6e 67 20 70 61 72 61 6d 65   ^Setting parame
1c310 74 65 72 20 58 20 74 6f 20 4e 55 4c 4c 20 64 69  ter X to NULL di
1c320 73 61 62 6c 65 73 20 74 68 65 20 70 72 6f 67 72  sables the progr
1c330 65 73 73 20 68 61 6e 64 6c 65 72 2e 0a 2a 2a 20  ess handler..** 
1c340 5e 54 68 65 20 70 72 6f 67 72 65 73 73 20 68 61  ^The progress ha
1c350 6e 64 6c 65 72 20 69 73 20 61 6c 73 6f 20 64 69  ndler is also di
1c360 73 61 62 6c 65 64 20 62 79 20 73 65 74 74 69 6e  sabled by settin
1c370 67 20 4e 20 74 6f 20 61 20 76 61 6c 75 65 20 6c  g N to a value l
1c380 65 73 73 0a 2a 2a 20 74 68 61 6e 20 31 2e 0a 2a  ess.** than 1..*
1c390 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 70 72 6f  *.** ^If the pro
1c3a0 67 72 65 73 73 20 63 61 6c 6c 62 61 63 6b 20 72  gress callback r
1c3b0 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 2c  eturns non-zero,
1c3c0 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 69   the operation i
1c3d0 73 0a 2a 2a 20 69 6e 74 65 72 72 75 70 74 65 64  s.** interrupted
1c3e0 2e 20 20 54 68 69 73 20 66 65 61 74 75 72 65 20  .  This feature 
1c3f0 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 69  can be used to i
1c400 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a 2a 20 22 43  mplement a.** "C
1c410 61 6e 63 65 6c 22 20 62 75 74 74 6f 6e 20 6f 6e  ancel" button on
1c420 20 61 20 47 55 49 20 70 72 6f 67 72 65 73 73 20   a GUI progress 
1c430 64 69 61 6c 6f 67 20 62 6f 78 2e 0a 2a 2a 0a 2a  dialog box..**.*
1c440 2a 20 54 68 65 20 70 72 6f 67 72 65 73 73 20 68  * The progress h
1c450 61 6e 64 6c 65 72 20 63 61 6c 6c 62 61 63 6b 20  andler callback 
1c460 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
1c470 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
1c480 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
1c490 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
1c4a0 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
1c4b0 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64 6c  e progress handl
1c4c0 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20 74 68 61 74  er..** Note that
1c4d0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
1c4e0 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b 73 71 6c  e_v2()] and [sql
1c4f0 69 74 65 33 5f 73 74 65 70 28 29 5d 20 62 6f 74  ite3_step()] bot
1c500 68 20 6d 6f 64 69 66 79 20 74 68 65 69 72 0a 2a  h modify their.*
1c510 2a 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  * database conne
1c520 63 74 69 6f 6e 73 20 66 6f 72 20 74 68 65 20 6d  ctions for the m
1c530 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f 64 69 66  eaning of "modif
1c540 79 22 20 69 6e 20 74 68 69 73 20 70 61 72 61 67  y" in this parag
1c550 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a 76 6f 69 64  raph..**.*/.void
1c560 20 73 71 6c 69 74 65 33 5f 70 72 6f 67 72 65 73   sqlite3_progres
1c570 73 5f 68 61 6e 64 6c 65 72 28 73 71 6c 69 74 65  s_handler(sqlite
1c580 33 2a 2c 20 69 6e 74 2c 20 69 6e 74 28 2a 29 28  3*, int, int(*)(
1c590 76 6f 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a  void*), void*);.
1c5a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
1c5b0 20 4f 70 65 6e 69 6e 67 20 41 20 4e 65 77 20 44   Opening A New D
1c5c0 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74 69  atabase Connecti
1c5d0 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
1c5e0 72 6f 75 74 69 6e 65 73 20 6f 70 65 6e 20 61 6e  routines open an
1c5f0 20 53 51 4c 69 74 65 20 64 61 74 61 62 61 73 65   SQLite database
1c600 20 66 69 6c 65 20 61 73 20 73 70 65 63 69 66 69   file as specifi
1c610 65 64 20 62 79 20 74 68 65 20 0a 2a 2a 20 66 69  ed by the .** fi
1c620 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 2e  lename argument.
1c630 20 5e 54 68 65 20 66 69 6c 65 6e 61 6d 65 20 61   ^The filename a
1c640 72 67 75 6d 65 6e 74 20 69 73 20 69 6e 74 65 72  rgument is inter
1c650 70 72 65 74 65 64 20 61 73 20 55 54 46 2d 38 20  preted as UTF-8 
1c660 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f  for.** sqlite3_o
1c670 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74 65  pen() and sqlite
1c680 33 5f 6f 70 65 6e 5f 76 32 28 29 20 61 6e 64 20  3_open_v2() and 
1c690 61 73 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  as UTF-16 in the
1c6a0 20 6e 61 74 69 76 65 20 62 79 74 65 0a 2a 2a 20   native byte.** 
1c6b0 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74 65  order for sqlite
1c6c0 33 5f 6f 70 65 6e 31 36 28 29 2e 20 5e 28 41 20  3_open16(). ^(A 
1c6d0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
1c6e0 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 20 69 73 20  tion] handle is 
1c6f0 75 73 75 61 6c 6c 79 0a 2a 2a 20 72 65 74 75 72  usually.** retur
1c700 6e 65 64 20 69 6e 20 2a 70 70 44 62 2c 20 65 76  ned in *ppDb, ev
1c710 65 6e 20 69 66 20 61 6e 20 65 72 72 6f 72 20 6f  en if an error o
1c720 63 63 75 72 73 2e 20 20 54 68 65 20 6f 6e 6c 79  ccurs.  The only
1c730 20 65 78 63 65 70 74 69 6f 6e 20 69 73 20 74 68   exception is th
1c740 61 74 0a 2a 2a 20 69 66 20 53 51 4c 69 74 65 20  at.** if SQLite 
1c750 69 73 20 75 6e 61 62 6c 65 20 74 6f 20 61 6c 6c  is unable to all
1c760 6f 63 61 74 65 20 6d 65 6d 6f 72 79 20 74 6f 20  ocate memory to 
1c770 68 6f 6c 64 20 74 68 65 20 5b 73 71 6c 69 74 65  hold the [sqlite
1c780 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a 2a 20 61 20  3] object,.** a 
1c790 4e 55 4c 4c 20 77 69 6c 6c 20 62 65 20 77 72 69  NULL will be wri
1c7a0 74 74 65 6e 20 69 6e 74 6f 20 2a 70 70 44 62 20  tten into *ppDb 
1c7b0 69 6e 73 74 65 61 64 20 6f 66 20 61 20 70 6f 69  instead of a poi
1c7c0 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c  nter to the [sql
1c7d0 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a 65 63 74 2e  ite3].** object.
1c7e0 29 5e 20 5e 28 49 66 20 74 68 65 20 64 61 74 61  )^ ^(If the data
1c7f0 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 28  base is opened (
1c800 61 6e 64 2f 6f 72 20 63 72 65 61 74 65 64 29 20  and/or created) 
1c810 73 75 63 63 65 73 73 66 75 6c 6c 79 2c 20 74 68  successfully, th
1c820 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 4b  en.** [SQLITE_OK
1c830 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20 20  ] is returned.  
1c840 4f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  Otherwise an [er
1c850 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
1c860 75 72 6e 65 64 2e 29 5e 20 5e 54 68 65 0a 2a 2a  urned.)^ ^The.**
1c870 20 5b 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   [sqlite3_errmsg
1c880 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
1c890 65 72 72 6d 73 67 31 36 28 29 5d 20 72 6f 75 74  errmsg16()] rout
1c8a0 69 6e 65 73 20 63 61 6e 20 62 65 20 75 73 65 64  ines can be used
1c8b0 20 74 6f 20 6f 62 74 61 69 6e 0a 2a 2a 20 61 6e   to obtain.** an
1c8c0 20 45 6e 67 6c 69 73 68 20 6c 61 6e 67 75 61 67   English languag
1c8d0 65 20 64 65 73 63 72 69 70 74 69 6f 6e 20 6f 66  e description of
1c8e0 20 74 68 65 20 65 72 72 6f 72 20 66 6f 6c 6c 6f   the error follo
1c8f0 77 69 6e 67 20 61 20 66 61 69 6c 75 72 65 20 6f  wing a failure o
1c900 66 20 61 6e 79 0a 2a 2a 20 6f 66 20 74 68 65 20  f any.** of the 
1c910 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 72  sqlite3_open() r
1c920 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 5e  outines..**.** ^
1c930 54 68 65 20 64 65 66 61 75 6c 74 20 65 6e 63 6f  The default enco
1c940 64 69 6e 67 20 66 6f 72 20 74 68 65 20 64 61 74  ding for the dat
1c950 61 62 61 73 65 20 77 69 6c 6c 20 62 65 20 55 54  abase will be UT
1c960 46 2d 38 20 69 66 0a 2a 2a 20 73 71 6c 69 74 65  F-8 if.** sqlite
1c970 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1c980 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1c990 20 63 61 6c 6c 65 64 20 61 6e 64 0a 2a 2a 20 55   called and.** U
1c9a0 54 46 2d 31 36 20 69 6e 20 74 68 65 20 6e 61 74  TF-16 in the nat
1c9b0 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 20 69  ive byte order i
1c9c0 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36  f sqlite3_open16
1c9d0 28 29 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a  () is used..**.*
1c9e0 2a 20 57 68 65 74 68 65 72 20 6f 72 20 6e 6f 74  * Whether or not
1c9f0 20 61 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73   an error occurs
1ca00 20 77 68 65 6e 20 69 74 20 69 73 20 6f 70 65 6e   when it is open
1ca10 65 64 2c 20 72 65 73 6f 75 72 63 65 73 0a 2a 2a  ed, resources.**
1ca20 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
1ca30 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1ca40 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c  onnection] handl
1ca50 65 20 73 68 6f 75 6c 64 20 62 65 20 72 65 6c 65  e should be rele
1ca60 61 73 65 64 20 62 79 0a 2a 2a 20 70 61 73 73 69  ased by.** passi
1ca70 6e 67 20 69 74 20 74 6f 20 5b 73 71 6c 69 74 65  ng it to [sqlite
1ca80 33 5f 63 6c 6f 73 65 28 29 5d 20 77 68 65 6e 20  3_close()] when 
1ca90 69 74 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20  it is no longer 
1caa0 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20  required..**.** 
1cab0 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  The sqlite3_open
1cac0 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63 65 20  _v2() interface 
1cad0 77 6f 72 6b 73 20 6c 69 6b 65 20 73 71 6c 69 74  works like sqlit
1cae0 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a 20 65 78 63  e3_open().** exc
1caf0 65 70 74 20 74 68 61 74 20 69 74 20 61 63 63 65  ept that it acce
1cb00 70 74 73 20 74 77 6f 20 61 64 64 69 74 69 6f 6e  pts two addition
1cb10 61 6c 20 70 61 72 61 6d 65 74 65 72 73 20 66 6f  al parameters fo
1cb20 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 63 6f 6e  r additional con
1cb30 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72 20 74 68 65  trol.** over the
1cb40 20 6e 65 77 20 64 61 74 61 62 61 73 65 20 63 6f   new database co
1cb50 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e 28 54 68 65  nnection.  ^(The
1cb60 20 66 6c 61 67 73 20 70 61 72 61 6d 65 74 65 72   flags parameter
1cb70 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 6f   to.** sqlite3_o
1cb80 70 65 6e 5f 76 32 28 29 20 63 61 6e 20 74 61 6b  pen_v2() can tak
1cb90 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20 74 68 65 20  e one of.** the 
1cba0 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72 65 65 20  following three 
1cbb0 76 61 6c 75 65 73 2c 20 6f 70 74 69 6f 6e 61 6c  values, optional
1cbc0 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77 69 74 68  ly combined with
1cbd0 20 74 68 65 20 0a 2a 2a 20 5b 53 51 4c 49 54 45   the .** [SQLITE
1cbe0 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20  _OPEN_NOMUTEX], 
1cbf0 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c  [SQLITE_OPEN_FUL
1cc00 4c 4d 55 54 45 58 5d 2c 20 5b 53 51 4c 49 54 45  LMUTEX], [SQLITE
1cc10 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48  _OPEN_SHAREDCACH
1cc20 45 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f  E],.** [SQLITE_O
1cc30 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1cc40 5d 2c 20 61 6e 64 2f 6f 72 20 5b 53 51 4c 49 54  ], and/or [SQLIT
1cc50 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67  E_OPEN_URI] flag
1cc60 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a  s:)^.**.** <dl>.
1cc70 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54 45  ** ^(<dt>[SQLITE
1cc80 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 3c  _OPEN_READONLY]<
1cc90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1cca0 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1ccb0 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79 20  ed in read-only 
1ccc0 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64 61  mode.  If the da
1ccd0 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74 0a  tabase does not.
1cce0 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73 74  ** already exist
1ccf0 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72 65  , an error is re
1cd00 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a 2a  turned.</dd>)^.*
1cd10 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49  *.** ^(<dt>[SQLI
1cd20 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49 54  TE_OPEN_READWRIT
1cd30 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54  E]</dt>.** <dd>T
1cd40 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1cd50 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69 6e  pened for readin
1cd60 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69 66  g and writing if
1cd70 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72 65   possible, or re
1cd80 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69 66  ading.** only if
1cd90 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72 69   the file is wri
1cda0 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79 20  te protected by 
1cdb0 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1cdc0 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65 72  stem.  In either
1cdd0 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61 74  .** case the dat
1cde0 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65 61  abase must alrea
1cdf0 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72 77  dy exist, otherw
1ce00 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73 20  ise an error is 
1ce10 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e  returned.</dd>)^
1ce20 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51  .**.** ^(<dt>[SQ
1ce30 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52  LITE_OPEN_READWR
1ce40 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f  ITE] | [SQLITE_O
1ce50 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74 3e  PEN_CREATE]</dt>
1ce60 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74 61  .** <dd>The data
1ce70 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20 66  base is opened f
1ce80 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20 77  or reading and w
1ce90 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20 63  riting, and is c
1cea0 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74 20  reated if.** it 
1ceb0 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64 79  does not already
1cec0 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73 20   exist. This is 
1ced0 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68 61  the behavior tha
1cee0 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  t is always used
1cef0 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   for.** sqlite3_
1cf00 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69 74  open() and sqlit
1cf10 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64 64  e3_open16().</dd
1cf20 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a 0a  >)^.** </dl>.**.
1cf30 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70 61  ** If the 3rd pa
1cf40 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74  rameter to sqlit
1cf50 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73 20  e3_open_v2() is 
1cf60 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a 2a  not one of the.*
1cf70 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20 73  * combinations s
1cf80 68 6f 77 6e 20 61 62 6f 76 65 20 6f 70 74 69 6f  hown above optio
1cf90 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20 77  nally combined w
1cfa0 69 74 68 20 6f 74 68 65 72 0a 2a 2a 20 5b 53 51  ith other.** [SQ
1cfb0 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e  LITE_OPEN_READON
1cfc0 4c 59 20 7c 20 53 51 4c 49 54 45 5f 4f 50 45 4e  LY | SQLITE_OPEN
1cfd0 5f 2a 20 62 69 74 73 5d 0a 2a 2a 20 74 68 65 6e  _* bits].** then
1cfe0 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 69 73   the behavior is
1cff0 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a   undefined..**.*
1d000 2a 20 5e 49 66 20 74 68 65 20 5b 53 51 4c 49 54  * ^If the [SQLIT
1d010 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 20  E_OPEN_NOMUTEX] 
1d020 66 6c 61 67 20 69 73 20 73 65 74 2c 20 74 68 65  flag is set, the
1d030 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1d040 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 6f 70 65  onnection.** ope
1d050 6e 73 20 69 6e 20 74 68 65 20 6d 75 6c 74 69 2d  ns in the multi-
1d060 74 68 72 65 61 64 20 5b 74 68 72 65 61 64 69 6e  thread [threadin
1d070 67 20 6d 6f 64 65 5d 20 61 73 20 6c 6f 6e 67 20  g mode] as long 
1d080 61 73 20 74 68 65 20 73 69 6e 67 6c 65 2d 74 68  as the single-th
1d090 72 65 61 64 0a 2a 2a 20 6d 6f 64 65 20 68 61 73  read.** mode has
1d0a0 20 6e 6f 74 20 62 65 65 6e 20 73 65 74 20 61 74   not been set at
1d0b0 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72   compile-time or
1d0c0 20 73 74 61 72 74 2d 74 69 6d 65 2e 20 20 5e 49   start-time.  ^I
1d0d0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
1d0e0 5f 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 5d  _OPEN_FULLMUTEX]
1d0f0 20 66 6c 61 67 20 69 73 20 73 65 74 20 74 68 65   flag is set the
1d100 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  n the database c
1d110 6f 6e 6e 65 63 74 69 6f 6e 20 6f 70 65 6e 73 0a  onnection opens.
1d120 2a 2a 20 69 6e 20 74 68 65 20 73 65 72 69 61 6c  ** in the serial
1d130 69 7a 65 64 20 5b 74 68 72 65 61 64 69 6e 67 20  ized [threading 
1d140 6d 6f 64 65 5d 20 75 6e 6c 65 73 73 20 73 69 6e  mode] unless sin
1d150 67 6c 65 2d 74 68 72 65 61 64 20 77 61 73 0a 2a  gle-thread was.*
1d160 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 6c  * previously sel
1d170 65 63 74 65 64 20 61 74 20 63 6f 6d 70 69 6c 65  ected at compile
1d180 2d 74 69 6d 65 20 6f 72 20 73 74 61 72 74 2d 74  -time or start-t
1d190 69 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 5b 53 51  ime..** ^The [SQ
1d1a0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1d1b0 43 41 43 48 45 5d 20 66 6c 61 67 20 63 61 75 73  CACHE] flag caus
1d1c0 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65 20  es the database 
1d1d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 62 65  connection to be
1d1e0 0a 2a 2a 20 65 6c 69 67 69 62 6c 65 20 74 6f 20  .** eligible to 
1d1f0 75 73 65 20 5b 73 68 61 72 65 64 20 63 61 63 68  use [shared cach
1d200 65 20 6d 6f 64 65 5d 2c 20 72 65 67 61 72 64 6c  e mode], regardl
1d210 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1d220 72 20 6e 6f 74 20 73 68 61 72 65 64 0a 2a 2a 20  r not shared.** 
1d230 63 61 63 68 65 20 69 73 20 65 6e 61 62 6c 65 64  cache is enabled
1d240 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
1d250 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
1d260 63 68 65 28 29 5d 2e 20 20 5e 54 68 65 0a 2a 2a  che()].  ^The.**
1d270 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50 52   [SQLITE_OPEN_PR
1d280 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61 67  IVATECACHE] flag
1d290 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1d2a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d2b0 74 6f 20 6e 6f 74 0a 2a 2a 20 70 61 72 74 69 63  to not.** partic
1d2c0 69 70 61 74 65 20 69 6e 20 5b 73 68 61 72 65 64  ipate in [shared
1d2d0 20 63 61 63 68 65 20 6d 6f 64 65 5d 20 65 76 65   cache mode] eve
1d2e0 6e 20 69 66 20 69 74 20 69 73 20 65 6e 61 62 6c  n if it is enabl
1d2f0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  ed..**.** ^The f
1d300 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65 72 20  ourth parameter 
1d310 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  to sqlite3_open_
1d320 76 32 28 29 20 69 73 20 74 68 65 20 6e 61 6d 65  v2() is the name
1d330 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69   of the.** [sqli
1d340 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 20  te3_vfs] object 
1d350 74 68 61 74 20 64 65 66 69 6e 65 73 20 74 68 65  that defines the
1d360 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
1d370 6d 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74  m interface that
1d380 0a 2a 2a 20 74 68 65 20 6e 65 77 20 64 61 74 61  .** the new data
1d390 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1d3a0 73 68 6f 75 6c 64 20 75 73 65 2e 20 20 5e 49 66  should use.  ^If
1d3b0 20 74 68 65 20 66 6f 75 72 74 68 20 70 61 72 61   the fourth para
1d3c0 6d 65 74 65 72 20 69 73 0a 2a 2a 20 61 20 4e 55  meter is.** a NU
1d3d0 4c 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20  LL pointer then 
1d3e0 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
1d3f0 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
1d400 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a 2a 2a 20   is used..**.** 
1d410 5e 49 66 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  ^If the filename
1d420 20 69 73 20 22 3a 6d 65 6d 6f 72 79 3a 22 2c 20   is ":memory:", 
1d430 74 68 65 6e 20 61 20 70 72 69 76 61 74 65 2c 20  then a private, 
1d440 74 65 6d 70 6f 72 61 72 79 20 69 6e 2d 6d 65 6d  temporary in-mem
1d450 6f 72 79 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  ory database.** 
1d460 69 73 20 63 72 65 61 74 65 64 20 66 6f 72 20 74  is created for t
1d470 68 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20  he connection.  
1d480 5e 54 68 69 73 20 69 6e 2d 6d 65 6d 6f 72 79 20  ^This in-memory 
1d490 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 76 61  database will va
1d4a0 6e 69 73 68 20 77 68 65 6e 0a 2a 2a 20 74 68 65  nish when.** the
1d4b0 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1d4c0 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65 64 2e 20  tion is closed. 
1d4d0 20 46 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   Future versions
1d4e0 20 6f 66 20 53 51 4c 69 74 65 20 6d 69 67 68 74   of SQLite might
1d4f0 0a 2a 2a 20 6d 61 6b 65 20 75 73 65 20 6f 66 20  .** make use of 
1d500 61 64 64 69 74 69 6f 6e 61 6c 20 73 70 65 63 69  additional speci
1d510 61 6c 20 66 69 6c 65 6e 61 6d 65 73 20 74 68 61  al filenames tha
1d520 74 20 62 65 67 69 6e 20 77 69 74 68 20 74 68 65  t begin with the
1d530 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 2e 0a   ":" character..
1d540 2a 2a 20 49 74 20 69 73 20 72 65 63 6f 6d 6d 65  ** It is recomme
1d550 6e 64 65 64 20 74 68 61 74 20 77 68 65 6e 20 61  nded that when a
1d560 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   database filena
1d570 6d 65 20 61 63 74 75 61 6c 6c 79 20 64 6f 65 73  me actually does
1d580 20 62 65 67 69 6e 20 77 69 74 68 0a 2a 2a 20 61   begin with.** a
1d590 20 22 3a 22 20 63 68 61 72 61 63 74 65 72 20 79   ":" character y
1d5a0 6f 75 20 73 68 6f 75 6c 64 20 70 72 65 66 69 78  ou should prefix
1d5b0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 77 69   the filename wi
1d5c0 74 68 20 61 20 70 61 74 68 6e 61 6d 65 20 73 75  th a pathname su
1d5d0 63 68 20 61 73 0a 2a 2a 20 22 2e 2f 22 20 74 6f  ch as.** "./" to
1d5e0 20 61 76 6f 69 64 20 61 6d 62 69 67 75 69 74 79   avoid ambiguity
1d5f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
1d600 66 69 6c 65 6e 61 6d 65 20 69 73 20 61 6e 20 65  filename is an e
1d610 6d 70 74 79 20 73 74 72 69 6e 67 2c 20 74 68 65  mpty string, the
1d620 6e 20 61 20 70 72 69 76 61 74 65 2c 20 74 65 6d  n a private, tem
1d630 70 6f 72 61 72 79 0a 2a 2a 20 6f 6e 2d 64 69 73  porary.** on-dis
1d640 6b 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20  k database will 
1d650 62 65 20 63 72 65 61 74 65 64 2e 20 20 5e 54 68  be created.  ^Th
1d660 69 73 20 70 72 69 76 61 74 65 20 64 61 74 61 62  is private datab
1d670 61 73 65 20 77 69 6c 6c 20 62 65 0a 2a 2a 20 61  ase will be.** a
1d680 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 64 65 6c  utomatically del
1d690 65 74 65 64 20 61 73 20 73 6f 6f 6e 20 61 73 20  eted as soon as 
1d6a0 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
1d6b0 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f 73 65  nection is close
1d6c0 64 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 55 52 49 20 66  d..**.** [[URI f
1d6d0 69 6c 65 6e 61 6d 65 73 20 69 6e 20 73 71 6c 69  ilenames in sqli
1d6e0 74 65 33 5f 6f 70 65 6e 28 29 5d 5d 20 3c 68 33  te3_open()]] <h3
1d6f0 3e 55 52 49 20 46 69 6c 65 6e 61 6d 65 73 3c 2f  >URI Filenames</
1d700 68 33 3e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 5b 55  h3>.**.** ^If [U
1d710 52 49 20 66 69 6c 65 6e 61 6d 65 5d 20 69 6e 74  RI filename] int
1d720 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73 20 65  erpretation is e
1d730 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68 65 20  nabled, and the 
1d740 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e  filename argumen
1d750 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69 74 68  t.** begins with
1d760 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e 20 74   "file:", then t
1d770 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73 20 69  he filename is i
1d780 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 61 20  nterpreted as a 
1d790 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66 69 6c  URI. ^URI.** fil
1d7a0 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61  ename interpreta
1d7b0 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65 64 20  tion is enabled 
1d7c0 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4f  if the [SQLITE_O
1d7d0 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20 69 73  PEN_URI] flag is
1d7e0 0a 2a 2a 20 69 73 20 73 65 74 20 69 6e 20 74 68  .** is set in th
1d7f0 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d 65 6e  e fourth argumen
1d800 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f 70 65  t to sqlite3_ope
1d810 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20 69 74  n_v2(), or if it
1d820 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65 6e 61   has.** been ena
1d830 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20 75 73  bled globally us
1d840 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ing the [SQLITE_
1d850 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70 74 69  CONFIG_URI] opti
1d860 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b  on with the.** [
1d870 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29  sqlite3_config()
1d880 5d 20 6d 65 74 68 6f 64 20 6f 72 20 62 79 20 74  ] method or by t
1d890 68 65 20 5b 53 51 4c 49 54 45 5f 55 53 45 5f 55  he [SQLITE_USE_U
1d8a0 52 49 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65  RI] compile-time
1d8b0 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 41 73 20 6f   option..** As o
1d8c0 66 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e  f SQLite version
1d8d0 20 33 2e 37 2e 37 2c 20 55 52 49 20 66 69 6c 65   3.7.7, URI file
1d8e0 6e 61 6d 65 20 69 6e 74 65 72 70 72 65 74 61 74  name interpretat
1d8f0 69 6f 6e 20 69 73 20 74 75 72 6e 65 64 20 6f 66  ion is turned of
1d900 66 0a 2a 2a 20 62 79 20 64 65 66 61 75 6c 74 2c  f.** by default,
1d910 20 62 75 74 20 66 75 74 75 72 65 20 72 65 6c 65   but future rele
1d920 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ases of SQLite m
1d930 69 67 68 74 20 65 6e 61 62 6c 65 20 55 52 49 20  ight enable URI 
1d940 66 69 6c 65 6e 61 6d 65 0a 2a 2a 20 69 6e 74 65  filename.** inte
1d950 70 72 65 74 61 74 69 6f 6e 20 62 79 20 64 65 66  pretation by def
1d960 61 75 6c 74 2e 20 20 53 65 65 20 22 5b 55 52 49  ault.  See "[URI
1d970 20 66 69 6c 65 6e 61 6d 65 73 5d 22 20 66 6f 72   filenames]" for
1d980 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69   additional.** i
1d990 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a  nformation..**.*
1d9a0 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 20  * URI filenames 
1d9b0 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f 72  are parsed accor
1d9c0 64 69 6e 67 20 74 6f 20 52 46 43 20 33 39 38 36  ding to RFC 3986
1d9d0 2e 20 5e 49 66 20 74 68 65 20 55 52 49 20 63 6f  . ^If the URI co
1d9e0 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 61 75 74  ntains an.** aut
1d9f0 68 6f 72 69 74 79 2c 20 74 68 65 6e 20 69 74 20  hority, then it 
1da00 6d 75 73 74 20 62 65 20 65 69 74 68 65 72 20 61  must be either a
1da10 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20 6f  n empty string o
1da20 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a 2a 2a  r the string .**
1da30 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20 5e 49   "localhost". ^I
1da40 66 20 74 68 65 20 61 75 74 68 6f 72 69 74 79 20  f the authority 
1da50 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74 79 20  is not an empty 
1da60 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63 61 6c  string or "local
1da70 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20 65 72  host", an .** er
1da80 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
1da90 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e 20 5e  to the caller. ^
1daa0 54 68 65 20 66 72 61 67 6d 65 6e 74 20 63 6f 6d  The fragment com
1dab0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 2c  ponent of a URI,
1dac0 20 69 66 20 0a 2a 2a 20 70 72 65 73 65 6e 74 2c   if .** present,
1dad0 20 69 73 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a   is ignored..**.
1dae0 2a 2a 20 5e 53 51 4c 69 74 65 20 75 73 65 73 20  ** ^SQLite uses 
1daf0 74 68 65 20 70 61 74 68 20 63 6f 6d 70 6f 6e 65  the path compone
1db00 6e 74 20 6f 66 20 74 68 65 20 55 52 49 20 61 73  nt of the URI as
1db10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
1db20 20 64 69 73 6b 20 66 69 6c 65 0a 2a 2a 20 77 68   disk file.** wh
1db30 69 63 68 20 63 6f 6e 74 61 69 6e 73 20 74 68 65  ich contains the
1db40 20 64 61 74 61 62 61 73 65 2e 20 5e 49 66 20 74   database. ^If t
1db50 68 65 20 70 61 74 68 20 62 65 67 69 6e 73 20 77  he path begins w
1db60 69 74 68 20 61 20 27 2f 27 20 63 68 61 72 61 63  ith a '/' charac
1db70 74 65 72 2c 20 0a 2a 2a 20 74 68 65 6e 20 69 74  ter, .** then it
1db80 20 69 73 20 69 6e 74 65 72 70 72 65 74 65 64 20   is interpreted 
1db90 61 73 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70  as an absolute p
1dba0 61 74 68 2e 20 5e 49 66 20 74 68 65 20 70 61 74  ath. ^If the pat
1dbb0 68 20 64 6f 65 73 20 6e 6f 74 20 62 65 67 69 6e  h does not begin
1dbc0 20 0a 2a 2a 20 77 69 74 68 20 61 20 27 2f 27 20   .** with a '/' 
1dbd0 28 6d 65 61 6e 69 6e 67 20 74 68 61 74 20 74 68  (meaning that th
1dbe0 65 20 61 75 74 68 6f 72 69 74 79 20 73 65 63 74  e authority sect
1dbf0 69 6f 6e 20 69 73 20 6f 6d 69 74 74 65 64 20 66  ion is omitted f
1dc00 72 6f 6d 20 74 68 65 20 55 52 49 29 0a 2a 2a 20  rom the URI).** 
1dc10 74 68 65 6e 20 74 68 65 20 70 61 74 68 20 69 73  then the path is
1dc20 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1dc30 61 20 72 65 6c 61 74 69 76 65 20 70 61 74 68 2e  a relative path.
1dc40 20 0a 2a 2a 20 5e 4f 6e 20 77 69 6e 64 6f 77 73   .** ^On windows
1dc50 2c 20 74 68 65 20 66 69 72 73 74 20 63 6f 6d 70  , the first comp
1dc60 6f 6e 65 6e 74 20 6f 66 20 61 6e 20 61 62 73 6f  onent of an abso
1dc70 6c 75 74 65 20 70 61 74 68 20 0a 2a 2a 20 69 73  lute path .** is
1dc80 20 61 20 64 72 69 76 65 20 73 70 65 63 69 66 69   a drive specifi
1dc90 63 61 74 69 6f 6e 20 28 65 2e 67 2e 20 22 43 3a  cation (e.g. "C:
1dca0 22 29 2e 0a 2a 2a 0a 2a 2a 20 5b 5b 63 6f 72 65  ")..**.** [[core
1dcb0 20 55 52 49 20 71 75 65 72 79 20 70 61 72 61 6d   URI query param
1dcc0 65 74 65 72 73 5d 5d 0a 2a 2a 20 54 68 65 20 71  eters]].** The q
1dcd0 75 65 72 79 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f  uery component o
1dce0 66 20 61 20 55 52 49 20 6d 61 79 20 63 6f 6e 74  f a URI may cont
1dcf0 61 69 6e 20 70 61 72 61 6d 65 74 65 72 73 20 74  ain parameters t
1dd00 68 61 74 20 61 72 65 20 69 6e 74 65 72 70 72 65  hat are interpre
1dd10 74 65 64 0a 2a 2a 20 65 69 74 68 65 72 20 62 79  ted.** either by
1dd20 20 53 51 4c 69 74 65 20 69 74 73 65 6c 66 2c 20   SQLite itself, 
1dd30 6f 72 20 62 79 20 61 20 5b 56 46 53 20 7c 20 63  or by a [VFS | c
1dd40 75 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d  ustom VFS implem
1dd50 65 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51  entation]..** SQ
1dd60 4c 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20  Lite interprets 
1dd70 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 66 6f  the following fo
1dd80 75 72 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ur query paramet
1dd90 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
1dda0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
1ddb0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
1ddc0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1ddd0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
1dde0 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
1ddf0 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
1de00 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
1de10 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1de20 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1de30 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
1de40 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
1de50 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1de60 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
1de70 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
1de80 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
1de90 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1dea0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
1deb0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
1dec0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
1ded0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
1dee0 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
1def0 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1df00 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
1df10 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
1df20 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
1df30 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
1df40 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1df50 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
1df60 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
1df70 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
1df80 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
1df90 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1dfa0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1dfb0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
1dfc0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
1dfd0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
1dfe0 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
1dff0 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
1e000 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77  w" or.**     "rw
1e010 63 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  c". Attempting t
1e020 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
1e030 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 20 61  other value is a
1e040 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
1e050 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
1e060 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
1e070 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1e080 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
1e090 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
1e0a0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
1e0b0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1e0c0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
1e0d0 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
1e0e0 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
1e0f0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1e100 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1e110 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
1e120 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1e130 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
1e140 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1e150 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1e160 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
1e170 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
1e180 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
1e190 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1e1a0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
1e1b0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1e1c0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
1e1d0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
1e1e0 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
1e1f0 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1e200 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
1e210 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1e220 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
1e230 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73  EN_CREATE. ^If s
1e240 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e250 20 69 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64   is .**     used
1e260 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  , it is an error
1e270 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
1e280 6c 75 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65  lue for the mode
1e290 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
1e2a0 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20  is .**     less 
1e2b0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
1e2c0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
1e2d0 62 79 20 74 68 65 20 66 6c 61 67 73 20 70 61 73  by the flags pas
1e2e0 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
1e2f0 20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74   .**     paramet
1e300 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  er..**.**   <li>
1e310 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
1e320 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
1e330 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
1e340 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
1e350 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
1e360 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
1e370 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
1e380 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1e390 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
1e3a0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
1e3b0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
1e3c0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
1e3d0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
1e3e0 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
1e3f0 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
1e400 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
1e410 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
1e420 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
1e430 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1e440 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
1e450 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1e460 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
1e470 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1e480 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
1e490 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
1e4a0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
1e4b0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
1e4c0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
1e4d0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
1e4e0 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71 75  y behaviour requ
1e4f0 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
1e500 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1e510 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1e520 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
1e530 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
1e540 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e 20 3c  ..**.**   <li> <
1e550 62 3e 72 65 61 64 6f 6e 6c 79 5f 73 68 6d 3c 2f  b>readonly_shm</
1e560 62 3e 3a 20 5e 54 68 65 20 72 65 61 64 6f 6e 6c  b>: ^The readonl
1e570 79 5f 73 68 6d 20 70 61 72 61 6d 65 74 65 72 20  y_shm parameter 
1e580 6d 61 79 20 62 65 20 73 65 74 20 74 6f 20 0a 2a  may be set to .*
1e590 2a 20 20 20 20 20 65 69 74 68 65 72 20 22 31 22  *     either "1"
1e5a0 20 6f 72 20 22 30 22 2e 20 53 65 74 74 69 6e 67   or "0". Setting
1e5b0 20 69 74 20 74 6f 20 22 31 22 20 69 6e 64 69 63   it to "1" indic
1e5c0 61 74 65 73 20 74 68 61 74 20 69 66 20 74 68 65  ates that if the
1e5d0 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 20 20 20   database.**    
1e5e0 20 69 73 20 69 6e 20 57 41 4c 20 6d 6f 64 65 20   is in WAL mode 
1e5f0 61 6e 64 20 72 65 61 64 2d 77 72 69 74 65 20 61  and read-write a
1e600 63 63 65 73 73 20 74 6f 20 74 68 65 20 61 73 73  ccess to the ass
1e610 6f 63 69 61 74 65 64 20 73 68 61 72 65 64 20 0a  ociated shared .
1e620 2a 2a 20 20 20 20 20 6d 65 6d 6f 72 79 20 72 65  **     memory re
1e630 67 69 6f 6e 20 63 61 6e 6e 6f 74 20 62 65 20 6f  gion cannot be o
1e640 62 74 61 69 6e 65 64 2c 20 74 68 65 6e 20 61 6e  btained, then an
1e650 20 61 74 74 65 6d 70 74 20 73 68 6f 75 6c 64 20   attempt should 
1e660 62 65 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 0a  be made to open.
1e670 2a 2a 20 20 20 20 20 74 68 65 20 73 68 61 72 65  **     the share
1e680 64 2d 6d 65 6d 6f 72 79 20 69 6e 20 72 65 61 64  d-memory in read
1e690 2d 6f 6e 6c 79 20 6d 6f 64 65 20 69 6e 73 74 65  -only mode inste
1e6a0 61 64 2e 20 49 66 20 74 68 65 72 65 20 65 78 69  ad. If there exi
1e6b0 73 74 20 6f 6e 65 20 6f 72 0a 2a 2a 20 20 20 20  st one or.**    
1e6c0 20 6d 6f 72 65 20 6f 74 68 65 72 20 64 61 74 61   more other data
1e6d0 62 61 73 65 20 63 6c 69 65 6e 74 73 20 74 68 61  base clients tha
1e6e0 74 20 68 61 76 65 20 72 65 61 64 2d 77 72 69 74  t have read-writ
1e6f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 74 6f  e connections to
1e700 20 74 68 65 0a 2a 2a 20 20 20 20 20 64 61 74 61   the.**     data
1e710 62 61 73 65 20 73 68 61 72 65 64 2d 6d 65 6d 6f  base shared-memo
1e720 72 79 2c 20 74 68 65 6e 20 61 20 72 65 61 64 2d  ry, then a read-
1e730 6f 6e 6c 79 20 73 68 61 72 65 64 2d 6d 65 6d 6f  only shared-memo
1e740 72 79 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 6f  ry connection wo
1e750 72 6b 73 20 0a 2a 2a 20 20 20 20 20 66 69 6e 65  rks .**     fine
1e760 2e 20 48 6f 77 65 76 65 72 2c 20 69 66 20 74 68  . However, if th
1e770 65 72 65 20 65 78 69 73 74 20 6e 6f 20 63 6c 69  ere exist no cli
1e780 65 6e 74 73 20 77 69 74 68 20 72 65 61 64 2d 77  ents with read-w
1e790 72 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 73  rite connections
1e7a0 20 0a 2a 2a 20 20 20 20 20 74 6f 20 74 68 65 20   .**     to the 
1e7b0 73 68 61 72 65 64 2d 6d 65 6d 6f 72 79 20 61 6e  shared-memory an
1e7c0 64 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  d the most recen
1e7d0 74 20 73 75 63 68 20 63 72 61 73 68 65 64 20 6f  t such crashed o
1e7e0 72 20 77 61 73 20 69 6e 74 65 72 72 75 70 74 65  r was interrupte
1e7f0 64 0a 2a 2a 20 20 20 20 20 62 79 20 61 20 70 6f  d.**     by a po
1e800 77 65 72 20 66 61 69 6c 75 72 65 2c 20 74 68 65  wer failure, the
1e810 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
1e820 20 66 6f 72 20 61 20 64 61 74 61 62 61 73 65 20   for a database 
1e830 63 6c 69 65 6e 74 20 75 73 69 6e 67 20 61 0a 2a  client using a.*
1e840 2a 20 20 20 20 20 72 65 61 64 2d 6f 6e 6c 79 20  *     read-only 
1e850 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f 20 72 65  connection to re
1e860 74 75 72 6e 20 69 6e 63 6f 72 72 65 63 74 20 64  turn incorrect d
1e870 61 74 61 2c 20 69 6e 63 6f 72 72 65 63 74 6c 79  ata, incorrectly
1e880 20 72 65 70 6f 72 74 20 0a 2a 2a 20 20 20 20 20   report .**     
1e890 64 61 74 61 62 61 73 65 20 63 6f 72 72 75 70 74  database corrupt
1e8a0 69 6f 6e 2c 20 6f 72 20 72 65 74 75 72 6e 20 61  ion, or return a
1e8b0 6e 20 53 51 4c 49 54 45 5f 52 45 41 44 4f 4e 4c  n SQLITE_READONL
1e8c0 59 20 65 72 72 6f 72 2e 20 4f 72 20 69 66 20 74  Y error. Or if t
1e8d0 68 65 0a 2a 2a 20 20 20 20 20 6d 6f 73 74 20 72  he.**     most r
1e8e0 65 63 65 6e 74 20 72 65 61 64 2d 77 72 69 74 65  ecent read-write
1e8f0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 68 75 74   connection shut
1e900 20 64 6f 77 6e 20 63 6c 65 61 6e 6c 79 2c 20 69   down cleanly, i
1e910 74 20 6d 61 79 20 6e 6f 74 20 62 65 0a 2a 2a 20  t may not be.** 
1e920 20 20 20 20 70 6f 73 73 69 62 6c 65 20 74 6f 20      possible to 
1e930 6f 70 65 6e 20 74 68 65 20 73 68 61 72 65 64 2d  open the shared-
1e940 6d 65 6d 6f 72 79 20 69 6e 20 72 65 61 64 2d 6f  memory in read-o
1e950 6e 6c 79 20 6d 6f 64 65 20 61 74 20 61 6c 6c 2c  nly mode at all,
1e960 20 61 6e 64 20 53 51 4c 69 74 65 0a 2a 2a 20 20   and SQLite.**  
1e970 20 20 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 53     will return S
1e980 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 2e 0a  QLITE_CANTOPEN..
1e990 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 5e  ** </ul>.**.** ^
1e9a0 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75 6e  Specifying an un
1e9b0 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65 72 20  known parameter 
1e9c0 69 6e 20 74 68 65 20 71 75 65 72 79 20 63 6f 6d  in the query com
1e9d0 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20  ponent of a URI 
1e9e0 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65 72 72  is not an.** err
1e9f0 6f 72 2e 20 20 46 75 74 75 72 65 20 76 65 72 73  or.  Future vers
1ea00 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20 6d  ions of SQLite m
1ea10 69 67 68 74 20 75 6e 64 65 72 73 74 61 6e 64 20  ight understand 
1ea20 61 64 64 69 74 69 6f 6e 61 6c 20 71 75 65 72 79  additional query
1ea30 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e 20  .** parameters. 
1ea40 20 53 65 65 20 22 5b 71 75 65 72 79 20 70 61 72   See "[query par
1ea50 61 6d 65 74 65 72 73 20 77 69 74 68 20 73 70 65  ameters with spe
1ea60 63 69 61 6c 20 6d 65 61 6e 69 6e 67 20 74 6f 20  cial meaning to 
1ea70 53 51 4c 69 74 65 5d 22 20 66 6f 72 0a 2a 2a 20  SQLite]" for.** 
1ea80 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
1ea90 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5b 5b  mation..**.** [[
1eaa0 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 65 78 61  URI filename exa
1eab0 6d 70 6c 65 73 5d 5d 20 3c 68 33 3e 55 52 49 20  mples]] <h3>URI 
1eac0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1ead0 73 3c 2f 68 33 3e 0a 2a 2a 0a 2a 2a 20 3c 74 61  s</h3>.**.** <ta
1eae0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 20 61  ble border="1" a
1eaf0 6c 69 67 6e 3d 63 65 6e 74 65 72 20 63 65 6c 6c  lign=center cell
1eb00 70 61 64 64 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74  padding=5>.** <t
1eb10 72 3e 3c 74 68 3e 20 55 52 49 20 66 69 6c 65 6e  r><th> URI filen
1eb20 61 6d 65 73 20 3c 74 68 3e 20 52 65 73 75 6c 74  ames <th> Result
1eb30 73 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  s.** <tr><td> fi
1eb40 6c 65 3a 64 61 74 61 2e 64 62 20 3c 74 64 3e 20  le:data.db <td> 
1eb50 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65  .**          Ope
1eb60 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61 74 61  n the file "data
1eb70 2e 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72  .db" in the curr
1eb80 65 6e 74 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a  ent directory..*
1eb90 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1eba0 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e  /home/fred/data.
1ebb0 64 62 3c 62 72 3e 0a 2a 2a 20 20 20 20 20 20 20  db<br>.**       
1ebc0 20 20 20 66 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f     file:///home/
1ebd0 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62 72  fred/data.db <br
1ebe0 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  > .**          f
1ebf0 69 6c 65 3a 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f  ile://localhost/
1ec00 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64  home/fred/data.d
1ec10 62 20 3c 62 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20  b <br> <td> .** 
1ec20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1ec30 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 20  e database file 
1ec40 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  "/home/fred/data
1ec50 2e 64 62 22 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  .db"..** <tr><td
1ec60 3e 20 66 69 6c 65 3a 2f 2f 64 61 72 6b 73 74 61  > file://darksta
1ec70 72 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74 61  r/home/fred/data
1ec80 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20  .db <td> .**    
1ec90 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e 20        An error. 
1eca0 22 64 61 72 6b 73 74 61 72 22 20 69 73 20 6e 6f  "darkstar" is no
1ecb0 74 20 61 20 72 65 63 6f 67 6e 69 7a 65 64 20 61  t a recognized a
1ecc0 75 74 68 6f 72 69 74 79 2e 0a 2a 2a 20 3c 74 72  uthority..** <tr
1ecd0 3e 3c 74 64 20 73 74 79 6c 65 3d 22 77 68 69 74  ><td style="whit
1ece0 65 2d 73 70 61 63 65 3a 6e 6f 77 72 61 70 22 3e  e-space:nowrap">
1ecf0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66 69   .**          fi
1ed00 6c 65 3a 2f 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e  le:///C:/Documen
1ed10 74 73 25 32 30 61 6e 64 25 32 30 53 65 74 74 69  ts%20and%20Setti
1ed20 6e 67 73 2f 66 72 65 64 2f 44 65 73 6b 74 6f 70  ngs/fred/Desktop
1ed30 2f 64 61 74 61 2e 64 62 0a 2a 2a 20 20 20 20 20  /data.db.**     
1ed40 3c 74 64 3e 20 57 69 6e 64 6f 77 73 20 6f 6e 6c  <td> Windows onl
1ed50 79 3a 20 4f 70 65 6e 20 74 68 65 20 66 69 6c 65  y: Open the file
1ed60 20 22 64 61 74 61 2e 64 62 22 20 6f 6e 20 66 72   "data.db" on fr
1ed70 65 64 27 73 20 64 65 73 6b 74 6f 70 20 6f 6e 20  ed's desktop on 
1ed80 64 72 69 76 65 0a 2a 2a 20 20 20 20 20 20 20 20  drive.**        
1ed90 20 20 43 3a 2e 20 4e 6f 74 65 20 74 68 61 74 20    C:. Note that 
1eda0 74 68 65 20 25 32 30 20 65 73 63 61 70 69 6e 67  the %20 escaping
1edb0 20 69 6e 20 74 68 69 73 20 65 78 61 6d 70 6c 65   in this example
1edc0 20 69 73 20 6e 6f 74 20 73 74 72 69 63 74 6c 79   is not strictly
1edd0 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 6e 65   .**          ne
1ede0 63 65 73 73 61 72 79 20 2d 20 73 70 61 63 65 20  cessary - space 
1edf0 63 68 61 72 61 63 74 65 72 73 20 63 61 6e 20 62  characters can b
1ee00 65 20 75 73 65 64 20 6c 69 74 65 72 61 6c 6c 79  e used literally
1ee10 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 69 6e 20  .**          in 
1ee20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a  URI filenames..*
1ee30 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a  * <tr><td> file:
1ee40 64 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26  data.db?mode=ro&
1ee50 63 61 63 68 65 3d 70 72 69 76 61 74 65 20 3c 74  cache=private <t
1ee60 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20 20 20  d> .**          
1ee70 4f 70 65 6e 20 66 69 6c 65 20 22 64 61 74 61 2e  Open file "data.
1ee80 64 62 22 20 69 6e 20 74 68 65 20 63 75 72 72 65  db" in the curre
1ee90 6e 74 20 64 69 72 65 63 74 6f 72 79 20 66 6f 72  nt directory for
1eea0 20 72 65 61 64 2d 6f 6e 6c 79 20 61 63 63 65 73   read-only acces
1eeb0 73 2e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 52  s..**          R
1eec0 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
1eed0 74 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72  ther or not shar
1eee0 65 64 2d 63 61 63 68 65 20 6d 6f 64 65 20 69 73  ed-cache mode is
1eef0 20 65 6e 61 62 6c 65 64 20 62 79 0a 2a 2a 20 20   enabled by.**  
1ef00 20 20 20 20 20 20 20 20 64 65 66 61 75 6c 74 2c          default,
1ef10 20 75 73 65 20 61 20 70 72 69 76 61 74 65 20 63   use a private c
1ef20 61 63 68 65 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  ache..** <tr><td
1ef30 3e 20 66 69 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65  > file:/home/fre
1ef40 64 2f 64 61 74 61 2e 64 62 3f 76 66 73 3d 75 6e  d/data.db?vfs=un
1ef50 69 78 2d 6e 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a  ix-nolock <td>.*
1ef60 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20  *          Open 
1ef70 66 69 6c 65 20 22 2f 68 6f 6d 65 2f 66 72 65 64  file "/home/fred
1ef80 2f 64 61 74 61 2e 64 62 22 2e 20 55 73 65 20 74  /data.db". Use t
1ef90 68 65 20 73 70 65 63 69 61 6c 20 56 46 53 20 22  he special VFS "
1efa0 75 6e 69 78 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a  unix-nolock"..**
1efb0 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1efc0 61 74 61 2e 64 62 3f 6d 6f 64 65 3d 72 65 61 64  ata.db?mode=read
1efd0 6f 6e 6c 79 20 3c 74 64 3e 20 0a 2a 2a 20 20 20  only <td> .**   
1efe0 20 20 20 20 20 20 20 41 6e 20 65 72 72 6f 72 2e         An error.
1eff0 20 22 72 65 61 64 6f 6e 6c 79 22 20 69 73 20 6e   "readonly" is n
1f000 6f 74 20 61 20 76 61 6c 69 64 20 6f 70 74 69 6f  ot a valid optio
1f010 6e 20 66 6f 72 20 74 68 65 20 22 6d 6f 64 65 22  n for the "mode"
1f020 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c   parameter..** <
1f030 2f 74 61 62 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55  /table>.**.** ^U
1f040 52 49 20 68 65 78 61 64 65 63 69 6d 61 6c 20 65  RI hexadecimal e
1f050 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73 20  scape sequences 
1f060 28 25 48 48 29 20 61 72 65 20 73 75 70 70 6f 72  (%HH) are suppor
1f070 74 65 64 20 77 69 74 68 69 6e 20 74 68 65 20 70  ted within the p
1f080 61 74 68 20 61 6e 64 0a 2a 2a 20 71 75 65 72 79  ath and.** query
1f090 20 63 6f 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61   components of a
1f0a0 20 55 52 49 2e 20 41 20 68 65 78 61 64 65 63 69   URI. A hexadeci
1f0b0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1f0c0 6e 63 65 20 63 6f 6e 73 69 73 74 73 20 6f 66 20  nce consists of 
1f0d0 61 0a 2a 2a 20 70 65 72 63 65 6e 74 20 73 69 67  a.** percent sig
1f0e0 6e 20 2d 20 22 25 22 20 2d 20 66 6f 6c 6c 6f 77  n - "%" - follow
1f0f0 65 64 20 62 79 20 65 78 61 63 74 6c 79 20 74 77  ed by exactly tw
1f100 6f 20 68 65 78 61 64 65 63 69 6d 61 6c 20 64 69  o hexadecimal di
1f110 67 69 74 73 20 0a 2a 2a 20 73 70 65 63 69 66 79  gits .** specify
1f120 69 6e 67 20 61 6e 20 6f 63 74 65 74 20 76 61 6c  ing an octet val
1f130 75 65 2e 20 5e 42 65 66 6f 72 65 20 74 68 65 20  ue. ^Before the 
1f140 70 61 74 68 20 6f 72 20 71 75 65 72 79 20 63 6f  path or query co
1f150 6d 70 6f 6e 65 6e 74 73 20 6f 66 20 61 0a 2a 2a  mponents of a.**
1f160 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 61 72   URI filename ar
1f170 65 20 69 6e 74 65 72 70 72 65 74 65 64 2c 20 74  e interpreted, t
1f180 68 65 79 20 61 72 65 20 65 6e 63 6f 64 65 64 20  hey are encoded 
1f190 75 73 69 6e 67 20 55 54 46 2d 38 20 61 6e 64 20  using UTF-8 and 
1f1a0 61 6c 6c 20 0a 2a 2a 20 68 65 78 61 64 65 63 69  all .** hexadeci
1f1b0 6d 61 6c 20 65 73 63 61 70 65 20 73 65 71 75 65  mal escape seque
1f1c0 6e 63 65 73 20 72 65 70 6c 61 63 65 64 20 62 79  nces replaced by
1f1d0 20 61 20 73 69 6e 67 6c 65 20 62 79 74 65 20 63   a single byte c
1f1e0 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 0a 2a 2a  ontaining the.**
1f1f0 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 6f   corresponding o
1f200 63 74 65 74 2e 20 49 66 20 74 68 69 73 20 70 72  ctet. If this pr
1f210 6f 63 65 73 73 20 67 65 6e 65 72 61 74 65 73 20  ocess generates 
1f220 61 6e 20 69 6e 76 61 6c 69 64 20 55 54 46 2d 38  an invalid UTF-8
1f230 20 65 6e 63 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68   encoding,.** th
1f240 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
1f250 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c  defined..**.** <
1f260 62 3e 4e 6f 74 65 20 74 6f 20 57 69 6e 64 6f 77  b>Note to Window
1f270 73 20 75 73 65 72 73 3a 3c 2f 62 3e 20 20 54 68  s users:</b>  Th
1f280 65 20 65 6e 63 6f 64 69 6e 67 20 75 73 65 64 20  e encoding used 
1f290 66 6f 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65  for the filename
1f2a0 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20   argument.** of 
1f2b0 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 61  sqlite3_open() a
1f2c0 6e 64 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nd sqlite3_open_
1f2d0 76 32 28 29 20 6d 75 73 74 20 62 65 20 55 54 46  v2() must be UTF
1f2e0 2d 38 2c 20 6e 6f 74 20 77 68 61 74 65 76 65 72  -8, not whatever
1f2f0 0a 2a 2a 20 63 6f 64 65 70 61 67 65 20 69 73 20  .** codepage is 
1f300 63 75 72 72 65 6e 74 6c 79 20 64 65 66 69 6e 65  currently define
1f310 64 2e 20 20 46 69 6c 65 6e 61 6d 65 73 20 63 6f  d.  Filenames co
1f320 6e 74 61 69 6e 69 6e 67 20 69 6e 74 65 72 6e 61  ntaining interna
1f330 74 69 6f 6e 61 6c 0a 2a 2a 20 63 68 61 72 61 63  tional.** charac
1f340 74 65 72 73 20 6d 75 73 74 20 62 65 20 63 6f 6e  ters must be con
1f350 76 65 72 74 65 64 20 74 6f 20 55 54 46 2d 38 20  verted to UTF-8 
1f360 70 72 69 6f 72 20 74 6f 20 70 61 73 73 69 6e 67  prior to passing
1f370 20 74 68 65 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71   them into.** sq
1f380 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1f390 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1f3a0 29 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  )..*/.int sqlite
1f3b0 33 5f 6f 70 65 6e 28 0a 20 20 63 6f 6e 73 74 20  3_open(.  const 
1f3c0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1f3d0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1f3e0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1f3f0 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f400 44 62 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db          /* O
1f410 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f420 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73  ndle */.);.int s
1f430 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 0a 20  qlite3_open16(. 
1f440 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 66 69 6c   const void *fil
1f450 65 6e 61 6d 65 2c 20 20 20 2f 2a 20 44 61 74 61  ename,   /* Data
1f460 62 61 73 65 20 66 69 6c 65 6e 61 6d 65 20 28 55  base filename (U
1f470 54 46 2d 31 36 29 20 2a 2f 0a 20 20 73 71 6c 69  TF-16) */.  sqli
1f480 74 65 33 20 2a 2a 70 70 44 62 20 20 20 20 20 20  te3 **ppDb      
1f490 20 20 20 20 2f 2a 20 4f 55 54 3a 20 53 51 4c 69      /* OUT: SQLi
1f4a0 74 65 20 64 62 20 68 61 6e 64 6c 65 20 2a 2f 0a  te db handle */.
1f4b0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f  );.int sqlite3_o
1f4c0 70 65 6e 5f 76 32 28 0a 20 20 63 6f 6e 73 74 20  pen_v2(.  const 
1f4d0 63 68 61 72 20 2a 66 69 6c 65 6e 61 6d 65 2c 20  char *filename, 
1f4e0 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 66 69    /* Database fi
1f4f0 6c 65 6e 61 6d 65 20 28 55 54 46 2d 38 29 20 2a  lename (UTF-8) *
1f500 2f 0a 20 20 73 71 6c 69 74 65 33 20 2a 2a 70 70  /.  sqlite3 **pp
1f510 44 62 2c 20 20 20 20 20 20 20 20 20 2f 2a 20 4f  Db,         /* O
1f520 55 54 3a 20 53 51 4c 69 74 65 20 64 62 20 68 61  UT: SQLite db ha
1f530 6e 64 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 66 6c  ndle */.  int fl
1f540 61 67 73 2c 20 20 20 20 20 20 20 20 20 20 20 20  ags,            
1f550 20 20 2f 2a 20 46 6c 61 67 73 20 2a 2f 0a 20 20    /* Flags */.  
1f560 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 56 66 73  const char *zVfs
1f570 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
1f580 6f 66 20 56 46 53 20 6d 6f 64 75 6c 65 20 74 6f  of VFS module to
1f590 20 75 73 65 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a   use */.);../*.*
1f5a0 2a 20 43 41 50 49 33 52 45 46 3a 20 4f 62 74 61  * CAPI3REF: Obta
1f5b0 69 6e 20 56 61 6c 75 65 73 20 46 6f 72 20 55 52  in Values For UR
1f5c0 49 20 50 61 72 61 6d 65 74 65 72 73 0a 2a 2a 0a  I Parameters.**.
1f5d0 2a 2a 20 54 68 69 73 20 69 73 20 61 20 75 74 69  ** This is a uti
1f5e0 6c 69 74 79 20 72 6f 75 74 69 6e 65 2c 20 75 73  lity routine, us
1f5f0 65 66 75 6c 20 74 6f 20 56 46 53 20 69 6d 70 6c  eful to VFS impl
1f600 65 6d 65 6e 74 61 74 69 6f 6e 73 2c 20 74 68 61  ementations, tha
1f610 74 20 63 68 65 63 6b 73 0a 2a 2a 20 74 6f 20 73  t checks.** to s
1f620 65 65 20 69 66 20 61 20 64 61 74 61 62 61 73 65  ee if a database
1f630 20 66 69 6c 65 20 77 61 73 20 61 20 55 52 49 20   file was a URI 
1f640 74 68 61 74 20 63 6f 6e 74 61 69 6e 65 64 20 61  that contained a
1f650 20 73 70 65 63 69 66 69 63 20 71 75 65 72 79 20   specific query 
1f660 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2c 20 61  .** parameter, a
1f670 6e 64 20 69 66 20 73 6f 20 6f 62 74 61 69 6e 73  nd if so obtains
1f680 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
1f690 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74 65  e query paramete
1f6a0 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a 46 69  r..**.** The zFi
1f6b0 6c 65 6e 61 6d 65 20 61 72 67 75 6d 65 6e 74 20  lename argument 
1f6c0 69 73 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  is the filename 
1f6d0 70 6f 69 6e 74 65 72 20 70 61 73 73 65 64 20 69  pointer passed i
1f6e0 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e 28 29 0a  nto the xOpen().
1f6f0 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61 20 56  ** method of a V
1f700 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
1f710 6e 2e 20 20 54 68 65 20 7a 50 61 72 61 6d 20 61  n.  The zParam a
1f720 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20 6e  rgument is the n
1f730 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20 71 75  ame of the.** qu
1f740 65 72 79 20 70 61 72 61 6d 65 74 65 72 20 77 65  ery parameter we
1f750 20 73 65 65 6b 2e 20 20 54 68 69 73 20 72 6f 75   seek.  This rou
1f760 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
1f770 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20 7a 50   value of the zP
1f780 61 72 61 6d 0a 2a 2a 20 70 61 72 61 6d 65 74 65  aram.** paramete
1f790 72 20 69 66 20 69 74 20 65 78 69 73 74 73 2e 20  r if it exists. 
1f7a0 20 49 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   If the paramete
1f7b0 72 20 64 6f 65 73 20 6e 6f 74 20 65 78 69 73 74  r does not exist
1f7c0 2c 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  , this routine.*
1f7d0 2a 20 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c  * returns a NULL
1f7e0 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20   pointer..**.** 
1f7f0 49 66 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65  If the zFilename
1f800 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 69   argument to thi
1f810 73 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 6e 6f  s function is no
1f820 74 20 61 20 70 6f 69 6e 74 65 72 20 74 68 61 74  t a pointer that
1f830 20 53 51 4c 69 74 65 0a 2a 2a 20 70 61 73 73 65   SQLite.** passe
1f840 64 20 69 6e 74 6f 20 74 68 65 20 78 4f 70 65 6e  d into the xOpen
1f850 20 56 46 53 20 6d 65 74 68 6f 64 2c 20 74 68 65   VFS method, the
1f860 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 6f  n the behavior o
1f870 66 20 74 68 69 73 20 72 6f 75 74 69 6e 65 0a 2a  f this routine.*
1f880 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  * is undefined a
1f890 6e 64 20 70 72 6f 62 61 62 6c 79 20 75 6e 64 65  nd probably unde
1f8a0 73 69 72 61 62 6c 65 2e 0a 2a 2f 0a 63 6f 6e 73  sirable..*/.cons
1f8b0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1f8c0 75 72 69 5f 70 61 72 61 6d 65 74 65 72 28 63 6f  uri_parameter(co
1f8d0 6e 73 74 20 63 68 61 72 20 2a 7a 46 69 6c 65 6e  nst char *zFilen
1f8e0 61 6d 65 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  ame, const char 
1f8f0 2a 7a 50 61 72 61 6d 29 3b 0a 0a 0a 2f 2a 0a 2a  *zParam);.../*.*
1f900 2a 20 43 41 50 49 33 52 45 46 3a 20 45 72 72 6f  * CAPI3REF: Erro
1f910 72 20 43 6f 64 65 73 20 41 6e 64 20 4d 65 73 73  r Codes And Mess
1f920 61 67 65 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ages.**.** ^The 
1f930 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1f940 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75  ) interface retu
1f950 72 6e 73 20 74 68 65 20 6e 75 6d 65 72 69 63 20  rns the numeric 
1f960 5b 72 65 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72  [result code] or
1f970 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1f980 73 75 6c 74 20 63 6f 64 65 5d 20 66 6f 72 20 74  sult code] for t
1f990 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 66  he most recent f
1f9a0 61 69 6c 65 64 20 73 71 6c 69 74 65 33 5f 2a 20  ailed sqlite3_* 
1f9b0 41 50 49 20 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f  API call.** asso
1f9c0 63 69 61 74 65 64 20 77 69 74 68 20 61 20 5b 64  ciated with a [d
1f9d0 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
1f9e0 6f 6e 5d 2e 20 49 66 20 61 20 70 72 69 6f 72 20  on]. If a prior 
1f9f0 41 50 49 20 63 61 6c 6c 20 66 61 69 6c 65 64 0a  API call failed.
1fa00 2a 2a 20 62 75 74 20 74 68 65 20 6d 6f 73 74 20  ** but the most 
1fa10 72 65 63 65 6e 74 20 41 50 49 20 63 61 6c 6c 20  recent API call 
1fa20 73 75 63 63 65 65 64 65 64 2c 20 74 68 65 20 72  succeeded, the r
1fa30 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72 6f 6d  eturn value from
1fa40 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 65 72 72 63  .** sqlite3_errc
1fa50 6f 64 65 28 29 20 69 73 20 75 6e 64 65 66 69 6e  ode() is undefin
1fa60 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
1fa70 33 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f  3_extended_errco
1fa80 64 65 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  de().** interfac
1fa90 65 20 69 73 20 74 68 65 20 73 61 6d 65 20 65 78  e is the same ex
1faa0 63 65 70 74 20 74 68 61 74 20 69 74 20 61 6c 77  cept that it alw
1fab0 61 79 73 20 72 65 74 75 72 6e 73 20 74 68 65 20  ays returns the 
1fac0 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
1fad0 73 75 6c 74 20 63 6f 64 65 5d 20 65 76 65 6e 20  sult code] even 
1fae0 77 68 65 6e 20 65 78 74 65 6e 64 65 64 20 72 65  when extended re
1faf0 73 75 6c 74 20 63 6f 64 65 73 20 61 72 65 0a 2a  sult codes are.*
1fb00 2a 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  * disabled..**.*
1fb10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65  * ^The sqlite3_e
1fb20 72 72 6d 73 67 28 29 20 61 6e 64 20 73 71 6c 69  rrmsg() and sqli
1fb30 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 20 72  te3_errmsg16() r
1fb40 65 74 75 72 6e 20 45 6e 67 6c 69 73 68 2d 6c 61  eturn English-la
1fb50 6e 67 75 61 67 65 0a 2a 2a 20 74 65 78 74 20 74  nguage.** text t
1fb60 68 61 74 20 64 65 73 63 72 69 62 65 73 20 74 68  hat describes th
1fb70 65 20 65 72 72 6f 72 2c 20 61 73 20 65 69 74 68  e error, as eith
1fb80 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46 2d  er UTF-8 or UTF-
1fb90 31 36 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  16 respectively.
1fba0 0a 2a 2a 20 5e 28 4d 65 6d 6f 72 79 20 74 6f 20  .** ^(Memory to 
1fbb0 68 6f 6c 64 20 74 68 65 20 65 72 72 6f 72 20 6d  hold the error m
1fbc0 65 73 73 61 67 65 20 73 74 72 69 6e 67 20 69 73  essage string is
1fbd0 20 6d 61 6e 61 67 65 64 20 69 6e 74 65 72 6e 61   managed interna
1fbe0 6c 6c 79 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  lly..** The appl
1fbf0 69 63 61 74 69 6f 6e 20 64 6f 65 73 20 6e 6f 74  ication does not
1fc00 20 6e 65 65 64 20 74 6f 20 77 6f 72 72 79 20 61   need to worry a
1fc10 62 6f 75 74 20 66 72 65 65 69 6e 67 20 74 68 65  bout freeing the
1fc20 20 72 65 73 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65   result..** Howe
1fc30 76 65 72 2c 20 74 68 65 20 65 72 72 6f 72 20 73  ver, the error s
1fc40 74 72 69 6e 67 20 6d 69 67 68 74 20 62 65 20 6f  tring might be o
1fc50 76 65 72 77 72 69 74 74 65 6e 20 6f 72 20 64 65  verwritten or de
1fc60 61 6c 6c 6f 63 61 74 65 64 20 62 79 0a 2a 2a 20  allocated by.** 
1fc70 73 75 62 73 65 71 75 65 6e 74 20 63 61 6c 6c 73  subsequent calls
1fc80 20 74 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   to other SQLite
1fc90 20 69 6e 74 65 72 66 61 63 65 20 66 75 6e 63 74   interface funct
1fca0 69 6f 6e 73 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68  ions.)^.**.** Wh
1fcb0 65 6e 20 74 68 65 20 73 65 72 69 61 6c 69 7a 65  en the serialize
1fcc0 64 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64  d [threading mod
1fcd0 65 5d 20 69 73 20 69 6e 20 75 73 65 2c 20 69 74  e] is in use, it
1fce0 20 6d 69 67 68 74 20 62 65 20 74 68 65 0a 2a 2a   might be the.**
1fcf0 20 63 61 73 65 20 74 68 61 74 20 61 20 73 65 63   case that a sec
1fd00 6f 6e 64 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ond error occurs
1fd10 20 6f 6e 20 61 20 73 65 70 61 72 61 74 65 20 74   on a separate t
1fd20 68 72 65 61 64 20 69 6e 20 62 65 74 77 65 65 6e  hread in between
1fd30 0a 2a 2a 20 74 68 65 20 74 69 6d 65 20 6f 66 20  .** the time of 
1fd40 74 68 65 20 66 69 72 73 74 20 65 72 72 6f 72 20  the first error 
1fd50 61 6e 64 20 74 68 65 20 63 61 6c 6c 20 74 6f 20  and the call to 
1fd60 74 68 65 73 65 20 69 6e 74 65 72 66 61 63 65 73  these interfaces
1fd70 2e 0a 2a 2a 20 57 68 65 6e 20 74 68 61 74 20 68  ..** When that h
1fd80 61 70 70 65 6e 73 2c 20 74 68 65 20 73 65 63 6f  appens, the seco
1fd90 6e 64 20 65 72 72 6f 72 20 77 69 6c 6c 20 62 65  nd error will be
1fda0 20 72 65 70 6f 72 74 65 64 20 73 69 6e 63 65 20   reported since 
1fdb0 74 68 65 73 65 0a 2a 2a 20 69 6e 74 65 72 66 61  these.** interfa
1fdc0 63 65 73 20 61 6c 77 61 79 73 20 72 65 70 6f 72  ces always repor
1fdd0 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e  t the most recen
1fde0 74 20 72 65 73 75 6c 74 2e 20 20 54 6f 20 61 76  t result.  To av
1fdf0 6f 69 64 0a 2a 2a 20 74 68 69 73 2c 20 65 61 63  oid.** this, eac
1fe00 68 20 74 68 72 65 61 64 20 63 61 6e 20 6f 62 74  h thread can obt
1fe10 61 69 6e 20 65 78 63 6c 75 73 69 76 65 20 75 73  ain exclusive us
1fe20 65 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61  e of the [databa
1fe30 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
1fe40 0a 2a 2a 20 62 79 20 69 6e 76 6f 6b 69 6e 67 20  .** by invoking 
1fe50 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f 65  [sqlite3_mutex_e
1fe60 6e 74 65 72 5d 28 5b 73 71 6c 69 74 65 33 5f 64  nter]([sqlite3_d
1fe70 62 5f 6d 75 74 65 78 5d 28 44 29 29 20 62 65 66  b_mutex](D)) bef
1fe80 6f 72 65 20 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a  ore beginning.**
1fe90 20 74 6f 20 75 73 65 20 44 20 61 6e 64 20 69 6e   to use D and in
1fea0 76 6f 6b 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f  voking [sqlite3_
1feb0 6d 75 74 65 78 5f 6c 65 61 76 65 5d 28 5b 73 71  mutex_leave]([sq
1fec0 6c 69 74 65 33 5f 64 62 5f 6d 75 74 65 78 5d 28  lite3_db_mutex](
1fed0 44 29 29 20 61 66 74 65 72 0a 2a 2a 20 61 6c 6c  D)) after.** all
1fee0 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 69 6e   calls to the in
1fef0 74 65 72 66 61 63 65 73 20 6c 69 73 74 65 64 20  terfaces listed 
1ff00 68 65 72 65 20 61 72 65 20 63 6f 6d 70 6c 65 74  here are complet
1ff10 65 64 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20  ed..**.** If an 
1ff20 69 6e 74 65 72 66 61 63 65 20 66 61 69 6c 73 20  interface fails 
1ff30 77 69 74 68 20 53 51 4c 49 54 45 5f 4d 49 53 55  with SQLITE_MISU
1ff40 53 45 2c 20 74 68 61 74 20 6d 65 61 6e 73 20 74  SE, that means t
1ff50 68 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20  he interface.** 
1ff60 77 61 73 20 69 6e 76 6f 6b 65 64 20 69 6e 63 6f  was invoked inco
1ff70 72 72 65 63 74 6c 79 20 62 79 20 74 68 65 20 61  rrectly by the a
1ff80 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20 49 6e 20  pplication.  In 
1ff90 74 68 61 74 20 63 61 73 65 2c 20 74 68 65 0a 2a  that case, the.*
1ffa0 2a 20 65 72 72 6f 72 20 63 6f 64 65 20 61 6e 64  * error code and
1ffb0 20 6d 65 73 73 61 67 65 20 6d 61 79 20 6f 72 20   message may or 
1ffc0 6d 61 79 20 6e 6f 74 20 62 65 20 73 65 74 2e 0a  may not be set..
1ffd0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  */.int sqlite3_e
1ffe0 72 72 63 6f 64 65 28 73 71 6c 69 74 65 33 20 2a  rrcode(sqlite3 *
1fff0 64 62 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  db);.int sqlite3
20000 5f 65 78 74 65 6e 64 65 64 5f 65 72 72 63 6f 64  _extended_errcod
20010 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b 0a  e(sqlite3 *db);.
20020 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
20030 74 65 33 5f 65 72 72 6d 73 67 28 73 71 6c 69 74  te3_errmsg(sqlit
20040 65 33 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64  e3*);.const void
20050 20 2a 73 71 6c 69 74 65 33 5f 65 72 72 6d 73 67   *sqlite3_errmsg
20060 31 36 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  16(sqlite3*);../
20070 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53  *.** CAPI3REF: S
20080 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 4f 62 6a  QL Statement Obj
20090 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
200a0 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   {prepared state
200b0 6d 65 6e 74 7d 20 7b 70 72 65 70 61 72 65 64 20  ment} {prepared 
200c0 73 74 61 74 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a  statements}.**.*
200d0 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
200e0 20 74 68 69 73 20 6f 62 6a 65 63 74 20 72 65 70   this object rep
200f0 72 65 73 65 6e 74 73 20 61 20 73 69 6e 67 6c 65  resents a single
20100 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2e 0a   SQL statement..
20110 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74 20 69  ** This object i
20120 73 20 76 61 72 69 6f 75 73 6c 79 20 6b 6e 6f 77  s variously know
20130 6e 20 61 73 20 61 20 22 70 72 65 70 61 72 65 64  n as a "prepared
20140 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20 61   statement" or a
20150 0a 2a 2a 20 22 63 6f 6d 70 69 6c 65 64 20 53 51  .** "compiled SQ
20160 4c 20 73 74 61 74 65 6d 65 6e 74 22 20 6f 72 20  L statement" or 
20170 73 69 6d 70 6c 79 20 61 73 20 61 20 22 73 74 61  simply as a "sta
20180 74 65 6d 65 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54  tement"..**.** T
20190 68 65 20 6c 69 66 65 20 6f 66 20 61 20 73 74 61  he life of a sta
201a0 74 65 6d 65 6e 74 20 6f 62 6a 65 63 74 20 67 6f  tement object go
201b0 65 73 20 73 6f 6d 65 74 68 69 6e 67 20 6c 69 6b  es something lik
201c0 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f  e this:.**.** <o
201d0 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 43 72 65 61 74  l>.** <li> Creat
201e0 65 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69  e the object usi
201f0 6e 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  ng [sqlite3_prep
20200 61 72 65 5f 76 32 28 29 5d 20 6f 72 20 61 20 72  are_v2()] or a r
20210 65 6c 61 74 65 64 0a 2a 2a 20 20 20 20 20 20 66  elated.**      f
20220 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e  unction..** <li>
20230 20 42 69 6e 64 20 76 61 6c 75 65 73 20 74 6f 20   Bind values to 
20240 5b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73  [host parameters
20250 5d 20 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69  ] using the sqli
20260 74 65 33 5f 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20  te3_bind_*().** 
20270 20 20 20 20 20 69 6e 74 65 72 66 61 63 65 73 2e       interfaces.
20280 0a 2a 2a 20 3c 6c 69 3e 20 52 75 6e 20 74 68 65  .** <li> Run the
20290 20 53 51 4c 20 62 79 20 63 61 6c 6c 69 6e 67 20   SQL by calling 
202a0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
202b0 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20 74 69 6d   one or more tim
202c0 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 52 65 73 65  es..** <li> Rese
202d0 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  t the statement 
202e0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 72  using [sqlite3_r
202f0 65 73 65 74 28 29 5d 20 74 68 65 6e 20 67 6f 20  eset()] then go 
20300 62 61 63 6b 0a 2a 2a 20 20 20 20 20 20 74 6f 20  back.**      to 
20310 73 74 65 70 20 32 2e 20 20 44 6f 20 74 68 69 73  step 2.  Do this
20320 20 7a 65 72 6f 20 6f 72 20 6d 6f 72 65 20 74 69   zero or more ti
20330 6d 65 73 2e 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73  mes..** <li> Des
20340 74 72 6f 79 20 74 68 65 20 6f 62 6a 65 63 74 20  troy the object 
20350 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66  using [sqlite3_f
20360 69 6e 61 6c 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c  inalize()]..** <
20370 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72  /ol>.**.** Refer
20380 20 74 6f 20 64 6f 63 75 6d 65 6e 74 61 74 69 6f   to documentatio
20390 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75 61 6c 20  n on individual 
203a0 6d 65 74 68 6f 64 73 20 61 62 6f 76 65 20 66 6f  methods above fo
203b0 72 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20  r additional.** 
203c0 69 6e 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a  information..*/.
203d0 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
203e0 71 6c 69 74 65 33 5f 73 74 6d 74 20 73 71 6c 69  qlite3_stmt sqli
203f0 74 65 33 5f 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a  te3_stmt;../*.**
20400 20 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 74   CAPI3REF: Run-t
20410 69 6d 65 20 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a  ime Limits.**.**
20420 20 5e 28 54 68 69 73 20 69 6e 74 65 72 66 61 63   ^(This interfac
20430 65 20 61 6c 6c 6f 77 73 20 74 68 65 20 73 69 7a  e allows the siz
20440 65 20 6f 66 20 76 61 72 69 6f 75 73 20 63 6f 6e  e of various con
20450 73 74 72 75 63 74 73 20 74 6f 20 62 65 20 6c 69  structs to be li
20460 6d 69 74 65 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f  mited.** on a co
20470 6e 6e 65 63 74 69 6f 6e 20 62 79 20 63 6f 6e 6e  nnection by conn
20480 65 63 74 69 6f 6e 20 62 61 73 69 73 2e 20 20 54  ection basis.  T
20490 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
204a0 65 72 20 69 73 20 74 68 65 0a 2a 2a 20 5b 64 61  er is the.** [da
204b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
204c0 6e 5d 20 77 68 6f 73 65 20 6c 69 6d 69 74 20 69  n] whose limit i
204d0 73 20 74 6f 20 62 65 20 73 65 74 20 6f 72 20 71  s to be set or q
204e0 75 65 72 69 65 64 2e 20 20 54 68 65 0a 2a 2a 20  ueried.  The.** 
204f0 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
20500 20 69 73 20 6f 6e 65 20 6f 66 20 74 68 65 20 5b   is one of the [
20510 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
20520 5d 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 0a  ] that define a.
20530 2a 2a 20 63 6c 61 73 73 20 6f 66 20 63 6f 6e 73  ** class of cons
20540 74 72 75 63 74 73 20 74 6f 20 62 65 20 73 69 7a  tructs to be siz
20550 65 20 6c 69 6d 69 74 65 64 2e 20 20 54 68 65 20  e limited.  The 
20560 74 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20  third parameter 
20570 69 73 20 74 68 65 0a 2a 2a 20 6e 65 77 20 6c 69  is the.** new li
20580 6d 69 74 20 66 6f 72 20 74 68 61 74 20 63 6f 6e  mit for that con
20590 73 74 72 75 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  struct.)^.**.** 
205a0 5e 49 66 20 74 68 65 20 6e 65 77 20 6c 69 6d 69  ^If the new limi
205b0 74 20 69 73 20 61 20 6e 65 67 61 74 69 76 65 20  t is a negative 
205c0 6e 75 6d 62 65 72 2c 20 74 68 65 20 6c 69 6d 69  number, the limi
205d0 74 20 69 73 20 75 6e 63 68 61 6e 67 65 64 2e 0a  t is unchanged..
205e0 2a 2a 20 5e 28 46 6f 72 20 65 61 63 68 20 6c 69  ** ^(For each li
205f0 6d 69 74 20 63 61 74 65 67 6f 72 79 20 53 51 4c  mit category SQL
20600 49 54 45 5f 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d  ITE_LIMIT_<i>NAM
20610 45 3c 2f 69 3e 20 74 68 65 72 65 20 69 73 20 61  E</i> there is a
20620 20 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20 7c 20 68   .** [limits | h
20630 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 5d  ard upper bound]
20640 0a 2a 2a 20 73 65 74 20 61 74 20 63 6f 6d 70 69  .** set at compi
20650 6c 65 2d 74 69 6d 65 20 62 79 20 61 20 43 20 70  le-time by a C p
20660 72 65 70 72 6f 63 65 73 73 6f 72 20 6d 61 63 72  reprocessor macr
20670 6f 20 63 61 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d  o called.** [lim
20680 69 74 73 20 7c 20 53 51 4c 49 54 45 5f 4d 41 58  its | SQLITE_MAX
20690 5f 3c 69 3e 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a  _<i>NAME</i>]..*
206a0 2a 20 28 54 68 65 20 22 5f 4c 49 4d 49 54 5f 22  * (The "_LIMIT_"
206b0 20 69 6e 20 74 68 65 20 6e 61 6d 65 20 69 73 20   in the name is 
206c0 63 68 61 6e 67 65 64 20 74 6f 20 22 5f 4d 41 58  changed to "_MAX
206d0 5f 22 2e 29 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d  _".))^.** ^Attem
206e0 70 74 73 20 74 6f 20 69 6e 63 72 65 61 73 65 20  pts to increase 
206f0 61 20 6c 69 6d 69 74 20 61 62 6f 76 65 20 69 74  a limit above it
20700 73 20 68 61 72 64 20 75 70 70 65 72 20 62 6f 75  s hard upper bou
20710 6e 64 20 61 72 65 0a 2a 2a 20 73 69 6c 65 6e 74  nd are.** silent
20720 6c 79 20 74 72 75 6e 63 61 74 65 64 20 74 6f 20  ly truncated to 
20730 74 68 65 20 68 61 72 64 20 75 70 70 65 72 20 62  the hard upper b
20740 6f 75 6e 64 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67  ound..**.** ^Reg
20750 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68  ardless of wheth
20760 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 6c 69  er or not the li
20770 6d 69 74 20 77 61 73 20 63 68 61 6e 67 65 64 2c  mit was changed,
20780 20 74 68 65 20 0a 2a 2a 20 5b 73 71 6c 69 74 65   the .** [sqlite
20790 33 5f 6c 69 6d 69 74 28 29 5d 20 69 6e 74 65 72  3_limit()] inter
207a0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
207b0 20 70 72 69 6f 72 20 76 61 6c 75 65 20 6f 66 20   prior value of 
207c0 74 68 65 20 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48  the limit..** ^H
207d0 65 6e 63 65 2c 20 74 6f 20 66 69 6e 64 20 74 68  ence, to find th
207e0 65 20 63 75 72 72 65 6e 74 20 76 61 6c 75 65 20  e current value 
207f0 6f 66 20 61 20 6c 69 6d 69 74 20 77 69 74 68 6f  of a limit witho
20800 75 74 20 63 68 61 6e 67 69 6e 67 20 69 74 2c 0a  ut changing it,.
20810 2a 2a 20 73 69 6d 70 6c 79 20 69 6e 76 6f 6b 65  ** simply invoke
20820 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
20830 77 69 74 68 20 74 68 65 20 74 68 69 72 64 20 70  with the third p
20840 61 72 61 6d 65 74 65 72 20 73 65 74 20 74 6f 20  arameter set to 
20850 2d 31 2e 0a 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69  -1..**.** Run-ti
20860 6d 65 20 6c 69 6d 69 74 73 20 61 72 65 20 69 6e  me limits are in
20870 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65 20 69  tended for use i
20880 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20 74  n applications t
20890 68 61 74 20 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f  hat manage.** bo
208a0 74 68 20 74 68 65 69 72 20 6f 77 6e 20 69 6e 74  th their own int
208b0 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 20 61  ernal database a
208c0 6e 64 20 61 6c 73 6f 20 64 61 74 61 62 61 73 65  nd also database
208d0 73 20 74 68 61 74 20 61 72 65 20 63 6f 6e 74 72  s that are contr
208e0 6f 6c 6c 65 64 0a 2a 2a 20 62 79 20 75 6e 74 72  olled.** by untr
208f0 75 73 74 65 64 20 65 78 74 65 72 6e 61 6c 20 73  usted external s
20900 6f 75 72 63 65 73 2e 20 20 41 6e 20 65 78 61 6d  ources.  An exam
20910 70 6c 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  ple application 
20920 6d 69 67 68 74 20 62 65 20 61 0a 2a 2a 20 77 65  might be a.** we
20930 62 20 62 72 6f 77 73 65 72 20 74 68 61 74 20 68  b browser that h
20940 61 73 20 69 74 73 20 6f 77 6e 20 64 61 74 61 62  as its own datab
20950 61 73 65 73 20 66 6f 72 20 73 74 6f 72 69 6e 67  ases for storing
20960 20 68 69 73 74 6f 72 79 20 61 6e 64 0a 2a 2a 20   history and.** 
20970 73 65 70 61 72 61 74 65 20 64 61 74 61 62 61 73  separate databas
20980 65 73 20 63 6f 6e 74 72 6f 6c 6c 65 64 20 62 79  es controlled by
20990 20 4a 61 76 61 53 63 72 69 70 74 20 61 70 70 6c   JavaScript appl
209a0 69 63 61 74 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61  ications downloa
209b0 64 65 64 0a 2a 2a 20 6f 66 66 20 74 68 65 20 49  ded.** off the I
209c0 6e 74 65 72 6e 65 74 2e 20 20 54 68 65 20 69 6e  nternet.  The in
209d0 74 65 72 6e 61 6c 20 64 61 74 61 62 61 73 65 73  ternal databases
209e0 20 63 61 6e 20 62 65 20 67 69 76 65 6e 20 74 68   can be given th
209f0 65 0a 2a 2a 20 6c 61 72 67 65 2c 20 64 65 66 61  e.** large, defa
20a00 75 6c 74 20 6c 69 6d 69 74 73 2e 20 20 44 61 74  ult limits.  Dat
20a10 61 62 61 73 65 73 20 6d 61 6e 61 67 65 64 20 62  abases managed b
20a20 79 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  y external sourc
20a30 65 73 20 63 61 6e 0a 2a 2a 20 62 65 20 67 69 76  es can.** be giv
20a40 65 6e 20 6d 75 63 68 20 73 6d 61 6c 6c 65 72 20  en much smaller 
20a50 6c 69 6d 69 74 73 20 64 65 73 69 67 6e 65 64 20  limits designed 
20a60 74 6f 20 70 72 65 76 65 6e 74 20 61 20 64 65 6e  to prevent a den
20a70 69 61 6c 20 6f 66 20 73 65 72 76 69 63 65 0a 2a  ial of service.*
20a80 2a 20 61 74 74 61 63 6b 2e 20 20 44 65 76 65 6c  * attack.  Devel
20a90 6f 70 65 72 73 20 6d 69 67 68 74 20 61 6c 73 6f  opers might also
20aa0 20 77 61 6e 74 20 74 6f 20 75 73 65 20 74 68 65   want to use the
20ab0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
20ac0 74 68 6f 72 69 7a 65 72 28 29 5d 0a 2a 2a 20 69  thorizer()].** i
20ad0 6e 74 65 72 66 61 63 65 20 74 6f 20 66 75 72 74  nterface to furt
20ae0 68 65 72 20 63 6f 6e 74 72 6f 6c 20 75 6e 74 72  her control untr
20af0 75 73 74 65 64 20 53 51 4c 2e 20 20 54 68 65 20  usted SQL.  The 
20b00 73 69 7a 65 20 6f 66 20 74 68 65 20 64 61 74 61  size of the data
20b10 62 61 73 65 0a 2a 2a 20 63 72 65 61 74 65 64 20  base.** created 
20b20 62 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20  by an untrusted 
20b30 73 63 72 69 70 74 20 63 61 6e 20 62 65 20 63 6f  script can be co
20b40 6e 74 61 69 6e 65 64 20 75 73 69 6e 67 20 74 68  ntained using th
20b50 65 0a 2a 2a 20 5b 6d 61 78 5f 70 61 67 65 5f 63  e.** [max_page_c
20b60 6f 75 6e 74 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a  ount] [PRAGMA]..
20b70 2a 2a 0a 2a 2a 20 4e 65 77 20 72 75 6e 2d 74 69  **.** New run-ti
20b80 6d 65 20 6c 69 6d 69 74 20 63 61 74 65 67 6f 72  me limit categor
20b90 69 65 73 20 6d 61 79 20 62 65 20 61 64 64 65 64  ies may be added
20ba0 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65 61   in future relea
20bb0 73 65 73 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ses..*/.int sqli
20bc0 74 65 33 5f 6c 69 6d 69 74 28 73 71 6c 69 74 65  te3_limit(sqlite
20bd0 33 2a 2c 20 69 6e 74 20 69 64 2c 20 69 6e 74 20  3*, int id, int 
20be0 6e 65 77 56 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20  newVal);../*.** 
20bf0 43 41 50 49 33 52 45 46 3a 20 52 75 6e 2d 54 69  CAPI3REF: Run-Ti
20c00 6d 65 20 4c 69 6d 69 74 20 43 61 74 65 67 6f 72  me Limit Categor
20c10 69 65 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ies.** KEYWORDS:
20c20 20 7b 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 79   {limit category
20c30 7d 20 7b 2a 6c 69 6d 69 74 20 63 61 74 65 67 6f  } {*limit catego
20c40 72 69 65 73 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73  ries}.**.** Thes
20c50 65 20 63 6f 6e 73 74 61 6e 74 73 20 64 65 66 69  e constants defi
20c60 6e 65 20 76 61 72 69 6f 75 73 20 70 65 72 66 6f  ne various perfo
20c70 72 6d 61 6e 63 65 20 6c 69 6d 69 74 73 0a 2a 2a  rmance limits.**
20c80 20 74 68 61 74 20 63 61 6e 20 62 65 20 6c 6f 77   that can be low
20c90 65 72 65 64 20 61 74 20 72 75 6e 2d 74 69 6d 65  ered at run-time
20ca0 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
20cb0 6c 69 6d 69 74 28 29 5d 2e 0a 2a 2a 20 54 68 65  limit()]..** The
20cc0 20 73 79 6e 6f 70 73 69 73 20 6f 66 20 74 68 65   synopsis of the
20cd0 20 6d 65 61 6e 69 6e 67 73 20 6f 66 20 74 68 65   meanings of the
20ce0 20 76 61 72 69 6f 75 73 20 6c 69 6d 69 74 73 20   various limits 
20cf0 69 73 20 73 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a  is shown below..
20d00 2a 2a 20 41 64 64 69 74 69 6f 6e 61 6c 20 69 6e  ** Additional in
20d10 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 61 76 61  formation is ava
20d20 69 6c 61 62 6c 65 20 61 74 20 5b 6c 69 6d 69 74  ilable at [limit
20d30 73 20 7c 20 4c 69 6d 69 74 73 20 69 6e 20 53 51  s | Limits in SQ
20d40 4c 69 74 65 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c  Lite]..**.** <dl
20d50 3e 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  >.** [[SQLITE_LI
20d60 4d 49 54 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c  MIT_LENGTH]] ^(<
20d70 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
20d80 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c  LENGTH</dt>.** <
20d90 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 73  dd>The maximum s
20da0 69 7a 65 20 6f 66 20 61 6e 79 20 73 74 72 69 6e  ize of any strin
20db0 67 20 6f 72 20 42 4c 4f 42 20 6f 72 20 74 61 62  g or BLOB or tab
20dc0 6c 65 20 72 6f 77 2c 20 69 6e 20 62 79 74 65 73  le row, in bytes
20dd0 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  .<dd>)^.**.** [[
20de0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
20df0 5f 4c 45 4e 47 54 48 5d 5d 20 5e 28 3c 64 74 3e  _LENGTH]] ^(<dt>
20e00 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 53 51 4c  SQLITE_LIMIT_SQL
20e10 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
20e20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20e30 6c 65 6e 67 74 68 20 6f 66 20 61 6e 20 53 51 4c  length of an SQL
20e40 20 73 74 61 74 65 6d 65 6e 74 2c 20 69 6e 20 62   statement, in b
20e50 79 74 65 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a  ytes.</dd>)^.**.
20e60 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49  ** [[SQLITE_LIMI
20e70 54 5f 43 4f 4c 55 4d 4e 5d 5d 20 5e 28 3c 64 74  T_COLUMN]] ^(<dt
20e80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
20e90 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
20ea0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
20eb0 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
20ec0 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
20ed0 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
20ee0 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
20ef0 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
20f00 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
20f10 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
20f20 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
20f30 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
20f40 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
20f50 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  </dd>)^.**.** [[
20f60 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
20f70 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c 64 74 3e  R_DEPTH]] ^(<dt>
20f80 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 45 58 50  SQLITE_LIMIT_EXP
20f90 52 5f 44 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20  R_DEPTH</dt>.** 
20fa0 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
20fb0 64 65 70 74 68 20 6f 66 20 74 68 65 20 70 61 72  depth of the par
20fc0 73 65 20 74 72 65 65 20 6f 6e 20 61 6e 79 20 65  se tree on any e
20fd0 78 70 72 65 73 73 69 6f 6e 2e 3c 2f 64 64 3e 29  xpression.</dd>)
20fe0 5e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45  ^.**.** [[SQLITE
20ff0 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f  _LIMIT_COMPOUND_
21000 53 45 4c 45 43 54 5d 5d 20 5e 28 3c 64 74 3e 53  SELECT]] ^(<dt>S
21010 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50  QLITE_LIMIT_COMP
21020 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f 64 74 3e  OUND_SELECT</dt>
21030 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
21040 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74 65  mum number of te
21050 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70 6f 75 6e  rms in a compoun
21060 64 20 53 45 4c 45 43 54 20 73 74 61 74 65 6d 65  d SELECT stateme
21070 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  nt.</dd>)^.**.**
21080 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f   [[SQLITE_LIMIT_
21090 56 44 42 45 5f 4f 50 5d 5d 20 5e 28 3c 64 74 3e  VDBE_OP]] ^(<dt>
210a0 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42  SQLITE_LIMIT_VDB
210b0 45 5f 4f 50 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  E_OP</dt>.** <dd
210c0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
210d0 62 65 72 20 6f 66 20 69 6e 73 74 72 75 63 74 69  ber of instructi
210e0 6f 6e 73 20 69 6e 20 61 20 76 69 72 74 75 61 6c  ons in a virtual
210f0 20 6d 61 63 68 69 6e 65 20 70 72 6f 67 72 61 6d   machine program
21100 0a 2a 2a 20 75 73 65 64 20 74 6f 20 69 6d 70 6c  .** used to impl
21110 65 6d 65 6e 74 20 61 6e 20 53 51 4c 20 73 74 61  ement an SQL sta
21120 74 65 6d 65 6e 74 2e 20 20 54 68 69 73 20 6c 69  tement.  This li
21130 6d 69 74 20 69 73 20 6e 6f 74 20 63 75 72 72 65  mit is not curre
21140 6e 74 6c 79 0a 2a 2a 20 65 6e 66 6f 72 63 65 64  ntly.** enforced
21150 2c 20 74 68 6f 75 67 68 20 74 68 61 74 20 6d 69  , though that mi
21160 67 68 74 20 62 65 20 61 64 64 65 64 20 69 6e 20  ght be added in 
21170 73 6f 6d 65 20 66 75 74 75 72 65 20 72 65 6c 65  some future rele
21180 61 73 65 20 6f 66 0a 2a 2a 20 53 51 4c 69 74 65  ase of.** SQLite
21190 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5b  .</dd>)^.**.** [
211a0 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55  [SQLITE_LIMIT_FU
211b0 4e 43 54 49 4f 4e 5f 41 52 47 5d 5d 20 5e 28 3c  NCTION_ARG]] ^(<
211c0 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
211d0 46 55 4e 43 54 49 4f 4e 5f 41 52 47 3c 2f 64 74  FUNCTION_ARG</dt
211e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
211f0 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 61  imum number of a
21200 72 67 75 6d 65 6e 74 73 20 6f 6e 20 61 20 66 75  rguments on a fu
21210 6e 63 74 69 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a  nction.</dd>)^.*
21220 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49  *.** [[SQLITE_LI
21230 4d 49 54 5f 41 54 54 41 43 48 45 44 5d 5d 20 5e  MIT_ATTACHED]] ^
21240 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49  (<dt>SQLITE_LIMI
21250 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74 3e 0a  T_ATTACHED</dt>.
21260 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
21270 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b 41 54  um number of [AT
21280 54 41 43 48 20 7c 20 61 74 74 61 63 68 65 64 20  TACH | attached 
21290 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c 2f 64  databases].)^</d
212a0 64 3e 0a 2a 2a 0a 2a 2a 20 5b 5b 53 51 4c 49 54  d>.**.** [[SQLIT
212b0 45 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54  E_LIMIT_LIKE_PAT
212c0 54 45 52 4e 5f 4c 45 4e 47 54 48 5d 5d 0a 2a 2a  TERN_LENGTH]].**
212d0 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
212e0 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54 45 52 4e  MIT_LIKE_PATTERN
212f0 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a 2a 2a 20  _LENGTH</dt>.** 
21300 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20  <dd>The maximum 
21310 6c 65 6e 67 74 68 20 6f 66 20 74 68 65 20 70 61  length of the pa
21320 74 74 65 72 6e 20 61 72 67 75 6d 65 6e 74 20 74  ttern argument t
21330 6f 20 74 68 65 20 5b 4c 49 4b 45 5d 20 6f 72 0a  o the [LIKE] or.
21340 2a 2a 20 5b 47 4c 4f 42 5d 20 6f 70 65 72 61 74  ** [GLOB] operat
21350 6f 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a  ors.</dd>)^.**.*
21360 2a 20 5b 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  * [[SQLITE_LIMIT
21370 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
21380 5d 5d 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49  ]].** ^(<dt>SQLI
21390 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c  TE_LIMIT_VARIABL
213a0 45 5f 4e 55 4d 42 45 52 3c 2f 64 74 3e 0a 2a 2a  E_NUMBER</dt>.**
213b0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
213c0 20 69 6e 64 65 78 20 6e 75 6d 62 65 72 20 6f 66   index number of
213d0 20 61 6e 79 20 5b 70 61 72 61 6d 65 74 65 72 5d   any [parameter]
213e0 20 69 6e 20 61 6e 20 53 51 4c 20 73 74 61 74 65   in an SQL state
213f0 6d 65 6e 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5b 5b  ment.)^.**.** [[
21400 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 54 52 49  SQLITE_LIMIT_TRI
21410 47 47 45 52 5f 44 45 50 54 48 5d 5d 20 5e 28 3c  GGER_DEPTH]] ^(<
21420 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  dt>SQLITE_LIMIT_
21430 54 52 49 47 47 45 52 5f 44 45 50 54 48 3c 2f 64  TRIGGER_DEPTH</d
21440 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61  t>.** <dd>The ma
21450 78 69 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 72  ximum depth of r
21460 65 63 75 72 73 69 6f 6e 20 66 6f 72 20 74 72 69  ecursion for tri
21470 67 67 65 72 73 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ggers.</dd>)^.**
21480 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
21490 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c  e SQLITE_LIMIT_L
214a0 45 4e 47 54 48 20 20 20 20 20 20 20 20 20 20 20  ENGTH           
214b0 20 20 20 20 20 20 20 20 20 30 0a 23 64 65 66 69           0.#defi
214c0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
214d0 53 51 4c 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  SQL_LENGTH      
214e0 20 20 20 20 20 20 20 20 20 20 31 0a 23 64 65 66            1.#def
214f0 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54  ine SQLITE_LIMIT
21500 5f 43 4f 4c 55 4d 4e 20 20 20 20 20 20 20 20 20  _COLUMN         
21510 20 20 20 20 20 20 20 20 20 20 20 32 0a 23 64 65             2.#de
21520 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49  fine SQLITE_LIMI
21530 54 5f 45 58 50 52 5f 44 45 50 54 48 20 20 20 20  T_EXPR_DEPTH    
21540 20 20 20 20 20 20 20 20 20 20 20 20 33 0a 23 64              3.#d
21550 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d  efine SQLITE_LIM
21560 49 54 5f 43 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45  IT_COMPOUND_SELE
21570 43 54 20 20 20 20 20 20 20 20 20 20 20 34 0a 23  CT           4.#
21580 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 49  define SQLITE_LI
21590 4d 49 54 5f 56 44 42 45 5f 4f 50 20 20 20 20 20  MIT_VDBE_OP     
215a0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 35 0a                5.
215b0 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c  #define SQLITE_L
215c0 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41 52  IMIT_FUNCTION_AR
215d0 47 20 20 20 20 20 20 20 20 20 20 20 20 20 20 36  G              6
215e0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
215f0 4c 49 4d 49 54 5f 41 54 54 41 43 48 45 44 20 20  LIMIT_ATTACHED  
21600 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
21610 37 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  7.#define SQLITE
21620 5f 4c 49 4d 49 54 5f 4c 49 4b 45 5f 50 41 54 54  _LIMIT_LIKE_PATT
21630 45 52 4e 5f 4c 45 4e 47 54 48 20 20 20 20 20 20  ERN_LENGTH      
21640 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   8.#define SQLIT
21650 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42 4c 45  E_LIMIT_VARIABLE
21660 5f 4e 55 4d 42 45 52 20 20 20 20 20 20 20 20 20  _NUMBER         
21670 20 20 39 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    9.#define SQLI
21680 54 45 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52  TE_LIMIT_TRIGGER
21690 5f 44 45 50 54 48 20 20 20 20 20 20 20 20 20 20  _DEPTH          
216a0 20 20 31 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    10../*.** CAPI
216b0 33 52 45 46 3a 20 43 6f 6d 70 69 6c 69 6e 67 20  3REF: Compiling 
216c0 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
216d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
216e0 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 63 6f 6d  QL statement com
216f0 70 69 6c 65 72 7d 0a 2a 2a 0a 2a 2a 20 54 6f 20  piler}.**.** To 
21700 65 78 65 63 75 74 65 20 61 6e 20 53 51 4c 20 71  execute an SQL q
21710 75 65 72 79 2c 20 69 74 20 6d 75 73 74 20 66 69  uery, it must fi
21720 72 73 74 20 62 65 20 63 6f 6d 70 69 6c 65 64 20  rst be compiled 
21730 69 6e 74 6f 20 61 20 62 79 74 65 2d 63 6f 64 65  into a byte-code
21740 0a 2a 2a 20 70 72 6f 67 72 61 6d 20 75 73 69 6e  .** program usin
21750 67 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20 72  g one of these r
21760 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a 2a 2a 20 54  outines..**.** T
21770 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
21780 74 2c 20 22 64 62 22 2c 20 69 73 20 61 20 5b 64  t, "db", is a [d
21790 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
217a0 6f 6e 5d 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  on] obtained fro
217b0 6d 20 61 0a 2a 2a 20 70 72 69 6f 72 20 73 75 63  m a.** prior suc
217c0 63 65 73 73 66 75 6c 20 63 61 6c 6c 20 74 6f 20  cessful call to 
217d0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 5d  [sqlite3_open()]
217e0 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  , [sqlite3_open_
217f0 76 32 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  v2()] or.** [sql
21800 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e 20  ite3_open16()]. 
21810 20 54 68 65 20 64 61 74 61 62 61 73 65 20 63 6f   The database co
21820 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  nnection must no
21830 74 20 68 61 76 65 20 62 65 65 6e 20 63 6c 6f 73  t have been clos
21840 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 65  ed..**.** The se
21850 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 2c 20 22  cond argument, "
21860 7a 53 71 6c 22 2c 20 69 73 20 74 68 65 20 73 74  zSql", is the st
21870 61 74 65 6d 65 6e 74 20 74 6f 20 62 65 20 63 6f  atement to be co
21880 6d 70 69 6c 65 64 2c 20 65 6e 63 6f 64 65 64 0a  mpiled, encoded.
21890 2a 2a 20 61 73 20 65 69 74 68 65 72 20 55 54 46  ** as either UTF
218a0 2d 38 20 6f 72 20 55 54 46 2d 31 36 2e 20 20 54  -8 or UTF-16.  T
218b0 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  he sqlite3_prepa
218c0 72 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  re() and sqlite3
218d0 5f 70 72 65 70 61 72 65 5f 76 32 28 29 0a 2a 2a  _prepare_v2().**
218e0 20 69 6e 74 65 72 66 61 63 65 73 20 75 73 65 20   interfaces use 
218f0 55 54 46 2d 38 2c 20 61 6e 64 20 73 71 6c 69 74  UTF-8, and sqlit
21900 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 20 61  e3_prepare16() a
21910 6e 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nd sqlite3_prepa
21920 72 65 31 36 5f 76 32 28 29 0a 2a 2a 20 75 73 65  re16_v2().** use
21930 20 55 54 46 2d 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e   UTF-16..**.** ^
21940 49 66 20 74 68 65 20 6e 42 79 74 65 20 61 72 67  If the nByte arg
21950 75 6d 65 6e 74 20 69 73 20 6c 65 73 73 20 74 68  ument is less th
21960 61 6e 20 7a 65 72 6f 2c 20 74 68 65 6e 20 7a 53  an zero, then zS
21970 71 6c 20 69 73 20 72 65 61 64 20 75 70 20 74 6f  ql is read up to
21980 20 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 7a 65   the.** first ze
21990 72 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 5e  ro terminator. ^
219a0 49 66 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  If nByte is non-
219b0 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20 69  negative, then i
219c0 74 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75 6d  t is the maximum
219d0 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 20 62  .** number of  b
219e0 79 74 65 73 20 72 65 61 64 20 66 72 6f 6d 20 7a  ytes read from z
219f0 53 71 6c 2e 20 20 5e 57 68 65 6e 20 6e 42 79 74  Sql.  ^When nByt
21a00 65 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76  e is non-negativ
21a10 65 2c 20 74 68 65 0a 2a 2a 20 7a 53 71 6c 20 73  e, the.** zSql s
21a20 74 72 69 6e 67 20 65 6e 64 73 20 61 74 20 65 69  tring ends at ei
21a30 74 68 65 72 20 74 68 65 20 66 69 72 73 74 20 27  ther the first '
21a40 5c 30 30 30 27 20 6f 72 20 27 5c 75 30 30 30 30  \000' or '\u0000
21a50 27 20 63 68 61 72 61 63 74 65 72 20 6f 72 0a 2a  ' character or.*
21a60 2a 20 74 68 65 20 6e 42 79 74 65 2d 74 68 20 62  * the nByte-th b
21a70 79 74 65 2c 20 77 68 69 63 68 65 76 65 72 20 63  yte, whichever c
21a80 6f 6d 65 73 20 66 69 72 73 74 2e 20 49 66 20 74  omes first. If t
21a90 68 65 20 63 61 6c 6c 65 72 20 6b 6e 6f 77 73 0a  he caller knows.
21aa0 2a 2a 20 74 68 61 74 20 74 68 65 20 73 75 70 70  ** that the supp
21ab0 6c 69 65 64 20 73 74 72 69 6e 67 20 69 73 20 6e  lied string is n
21ac0 75 6c 2d 74 65 72 6d 69 6e 61 74 65 64 2c 20 74  ul-terminated, t
21ad0 68 65 6e 20 74 68 65 72 65 20 69 73 20 61 20 73  hen there is a s
21ae0 6d 61 6c 6c 0a 2a 2a 20 70 65 72 66 6f 72 6d 61  mall.** performa
21af0 6e 63 65 20 61 64 76 61 6e 74 61 67 65 20 74 6f  nce advantage to
21b00 20 62 65 20 67 61 69 6e 65 64 20 62 79 20 70 61   be gained by pa
21b10 73 73 69 6e 67 20 61 6e 20 6e 42 79 74 65 20 70  ssing an nByte p
21b20 61 72 61 6d 65 74 65 72 20 74 68 61 74 0a 2a 2a  arameter that.**
21b30 20 69 73 20 65 71 75 61 6c 20 74 6f 20 74 68 65   is equal to the
21b40 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
21b50 20 69 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74   in the input st
21b60 72 69 6e 67 20 3c 69 3e 69 6e 63 6c 75 64 69 6e  ring <i>includin
21b70 67 3c 2f 69 3e 0a 2a 2a 20 74 68 65 20 6e 75 6c  g</i>.** the nul
21b80 2d 74 65 72 6d 69 6e 61 74 6f 72 20 62 79 74 65  -terminator byte
21b90 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 70 7a 54  s..**.** ^If pzT
21ba0 61 69 6c 20 69 73 20 6e 6f 74 20 4e 55 4c 4c 20  ail is not NULL 
21bb0 74 68 65 6e 20 2a 70 7a 54 61 69 6c 20 69 73 20  then *pzTail is 
21bc0 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74 6f  made to point to
21bd0 20 74 68 65 20 66 69 72 73 74 20 62 79 74 65 0a   the first byte.
21be0 2a 2a 20 70 61 73 74 20 74 68 65 20 65 6e 64 20  ** past the end 
21bf0 6f 66 20 74 68 65 20 66 69 72 73 74 20 53 51 4c  of the first SQL
21c00 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53   statement in zS
21c10 71 6c 2e 20 20 54 68 65 73 65 20 72 6f 75 74 69  ql.  These routi
21c20 6e 65 73 20 6f 6e 6c 79 0a 2a 2a 20 63 6f 6d 70  nes only.** comp
21c30 69 6c 65 20 74 68 65 20 66 69 72 73 74 20 73 74  ile the first st
21c40 61 74 65 6d 65 6e 74 20 69 6e 20 7a 53 71 6c 2c  atement in zSql,
21c50 20 73 6f 20 2a 70 7a 54 61 69 6c 20 69 73 20 6c   so *pzTail is l
21c60 65 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 0a  eft pointing to.
21c70 2a 2a 20 77 68 61 74 20 72 65 6d 61 69 6e 73 20  ** what remains 
21c80 75 6e 63 6f 6d 70 69 6c 65 64 2e 0a 2a 2a 0a 2a  uncompiled..**.*
21c90 2a 20 5e 2a 70 70 53 74 6d 74 20 69 73 20 6c 65  * ^*ppStmt is le
21ca0 66 74 20 70 6f 69 6e 74 69 6e 67 20 74 6f 20 61  ft pointing to a
21cb0 20 63 6f 6d 70 69 6c 65 64 20 5b 70 72 65 70 61   compiled [prepa
21cc0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
21cd0 68 61 74 20 63 61 6e 20 62 65 0a 2a 2a 20 65 78  hat can be.** ex
21ce0 65 63 75 74 65 64 20 75 73 69 6e 67 20 5b 73 71  ecuted using [sq
21cf0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 2e 20 20  lite3_step()].  
21d00 5e 49 66 20 74 68 65 72 65 20 69 73 20 61 6e 20  ^If there is an 
21d10 65 72 72 6f 72 2c 20 2a 70 70 53 74 6d 74 20 69  error, *ppStmt i
21d20 73 20 73 65 74 0a 2a 2a 20 74 6f 20 4e 55 4c 4c  s set.** to NULL
21d30 2e 20 20 5e 49 66 20 74 68 65 20 69 6e 70 75 74  .  ^If the input
21d40 20 74 65 78 74 20 63 6f 6e 74 61 69 6e 73 20 6e   text contains n
21d50 6f 20 53 51 4c 20 28 69 66 20 74 68 65 20 69 6e  o SQL (if the in
21d60 70 75 74 20 69 73 20 61 6e 20 65 6d 70 74 79 0a  put is an empty.
21d70 2a 2a 20 73 74 72 69 6e 67 20 6f 72 20 61 20 63  ** string or a c
21d80 6f 6d 6d 65 6e 74 29 20 74 68 65 6e 20 2a 70 70  omment) then *pp
21d90 53 74 6d 74 20 69 73 20 73 65 74 20 74 6f 20 4e  Stmt is set to N
21da0 55 4c 4c 2e 0a 2a 2a 20 54 68 65 20 63 61 6c 6c  ULL..** The call
21db0 69 6e 67 20 70 72 6f 63 65 64 75 72 65 20 69 73  ing procedure is
21dc0 20 72 65 73 70 6f 6e 73 69 62 6c 65 20 66 6f 72   responsible for
21dd0 20 64 65 6c 65 74 69 6e 67 20 74 68 65 20 63 6f   deleting the co
21de0 6d 70 69 6c 65 64 0a 2a 2a 20 53 51 4c 20 73 74  mpiled.** SQL st
21df0 61 74 65 6d 65 6e 74 20 75 73 69 6e 67 20 5b 73  atement using [s
21e00 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
21e10 29 5d 20 61 66 74 65 72 20 69 74 20 68 61 73 20  )] after it has 
21e20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69 74  finished with it
21e30 2e 0a 2a 2a 20 70 70 53 74 6d 74 20 6d 61 79 20  ..** ppStmt may 
21e40 6e 6f 74 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  not be NULL..**.
21e50 2a 2a 20 5e 4f 6e 20 73 75 63 63 65 73 73 2c 20  ** ^On success, 
21e60 74 68 65 20 73 71 6c 69 74 65 33 5f 70 72 65 70  the sqlite3_prep
21e70 61 72 65 28 29 20 66 61 6d 69 6c 79 20 6f 66 20  are() family of 
21e80 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20  routines return 
21e90 5b 53 51 4c 49 54 45 5f 4f 4b 5d 3b 0a 2a 2a 20  [SQLITE_OK];.** 
21ea0 6f 74 68 65 72 77 69 73 65 20 61 6e 20 5b 65 72  otherwise an [er
21eb0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
21ec0 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  urned..**.** The
21ed0 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
21ee0 5f 76 32 28 29 20 61 6e 64 20 73 71 6c 69 74 65  _v2() and sqlite
21ef0 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
21f00 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 0a   interfaces are.
21f10 2a 2a 20 72 65 63 6f 6d 6d 65 6e 64 65 64 20 66  ** recommended f
21f20 6f 72 20 61 6c 6c 20 6e 65 77 20 70 72 6f 67 72  or all new progr
21f30 61 6d 73 2e 20 54 68 65 20 74 77 6f 20 6f 6c 64  ams. The two old
21f40 65 72 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  er interfaces ar
21f50 65 20 72 65 74 61 69 6e 65 64 0a 2a 2a 20 66 6f  e retained.** fo
21f60 72 20 62 61 63 6b 77 61 72 64 73 20 63 6f 6d 70  r backwards comp
21f70 61 74 69 62 69 6c 69 74 79 2c 20 62 75 74 20 74  atibility, but t
21f80 68 65 69 72 20 75 73 65 20 69 73 20 64 69 73 63  heir use is disc
21f90 6f 75 72 61 67 65 64 2e 0a 2a 2a 20 5e 49 6e 20  ouraged..** ^In 
21fa0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
21fb0 63 65 73 2c 20 74 68 65 20 70 72 65 70 61 72 65  ces, the prepare
21fc0 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 74  d statement.** t
21fd0 68 61 74 20 69 73 20 72 65 74 75 72 6e 65 64 20  hat is returned 
21fe0 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
21ff0 6d 74 5d 20 6f 62 6a 65 63 74 29 20 63 6f 6e 74  mt] object) cont
22000 61 69 6e 73 20 61 20 63 6f 70 79 20 6f 66 20 74  ains a copy of t
22010 68 65 0a 2a 2a 20 6f 72 69 67 69 6e 61 6c 20 53  he.** original S
22020 51 4c 20 74 65 78 74 2e 20 54 68 69 73 20 63 61  QL text. This ca
22030 75 73 65 73 20 74 68 65 20 5b 73 71 6c 69 74 65  uses the [sqlite
22040 33 5f 73 74 65 70 28 29 5d 20 69 6e 74 65 72 66  3_step()] interf
22050 61 63 65 20 74 6f 0a 2a 2a 20 62 65 68 61 76 65  ace to.** behave
22060 20 64 69 66 66 65 72 65 6e 74 6c 79 20 69 6e 20   differently in 
22070 74 68 72 65 65 20 77 61 79 73 3a 0a 2a 2a 0a 2a  three ways:.**.*
22080 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69 3e 0a 2a  * <ol>.** <li>.*
22090 2a 20 5e 49 66 20 74 68 65 20 64 61 74 61 62 61  * ^If the databa
220a0 73 65 20 73 63 68 65 6d 61 20 63 68 61 6e 67 65  se schema change
220b0 73 2c 20 69 6e 73 74 65 61 64 20 6f 66 20 72 65  s, instead of re
220c0 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45 5f  turning [SQLITE_
220d0 53 43 48 45 4d 41 5d 20 61 73 20 69 74 0a 2a 2a  SCHEMA] as it.**
220e0 20 61 6c 77 61 79 73 20 75 73 65 64 20 74 6f 20   always used to 
220f0 64 6f 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  do, [sqlite3_ste
22100 70 28 29 5d 20 77 69 6c 6c 20 61 75 74 6f 6d 61  p()] will automa
22110 74 69 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c  tically recompil
22120 65 20 74 68 65 20 53 51 4c 0a 2a 2a 20 73 74 61  e the SQL.** sta
22130 74 65 6d 65 6e 74 20 61 6e 64 20 74 72 79 20 74  tement and try t
22140 6f 20 72 75 6e 20 69 74 20 61 67 61 69 6e 2e 0a  o run it again..
22150 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c  ** </li>.**.** <
22160 6c 69 3e 0a 2a 2a 20 5e 57 68 65 6e 20 61 6e 20  li>.** ^When an 
22170 65 72 72 6f 72 20 6f 63 63 75 72 73 2c 20 5b 73  error occurs, [s
22180 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77  qlite3_step()] w
22190 69 6c 6c 20 72 65 74 75 72 6e 20 6f 6e 65 20 6f  ill return one o
221a0 66 20 74 68 65 20 64 65 74 61 69 6c 65 64 0a 2a  f the detailed.*
221b0 2a 20 5b 65 72 72 6f 72 20 63 6f 64 65 73 5d 20  * [error codes] 
221c0 6f 72 20 5b 65 78 74 65 6e 64 65 64 20 65 72 72  or [extended err
221d0 6f 72 20 63 6f 64 65 73 5d 2e 20 20 5e 54 68 65  or codes].  ^The
221e0 20 6c 65 67 61 63 79 20 62 65 68 61 76 69 6f 72   legacy behavior
221f0 20 77 61 73 20 74 68 61 74 0a 2a 2a 20 5b 73 71   was that.** [sq
22200 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 77 6f  lite3_step()] wo
22210 75 6c 64 20 6f 6e 6c 79 20 72 65 74 75 72 6e 20  uld only return 
22220 61 20 67 65 6e 65 72 69 63 20 5b 53 51 4c 49 54  a generic [SQLIT
22230 45 5f 45 52 52 4f 52 5d 20 72 65 73 75 6c 74 20  E_ERROR] result 
22240 63 6f 64 65 0a 2a 2a 20 61 6e 64 20 74 68 65 20  code.** and the 
22250 61 70 70 6c 69 63 61 74 69 6f 6e 20 77 6f 75 6c  application woul
22260 64 20 68 61 76 65 20 74 6f 20 6d 61 6b 65 20 61  d have to make a
22270 20 73 65 63 6f 6e 64 20 63 61 6c 6c 20 74 6f 20   second call to 
22280 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
22290 5d 0a 2a 2a 20 69 6e 20 6f 72 64 65 72 20 74 6f  ].** in order to
222a0 20 66 69 6e 64 20 74 68 65 20 75 6e 64 65 72 6c   find the underl
222b0 79 69 6e 67 20 63 61 75 73 65 20 6f 66 20 74 68  ying cause of th
222c0 65 20 70 72 6f 62 6c 65 6d 2e 20 57 69 74 68 20  e problem. With 
222d0 74 68 65 20 22 76 32 22 20 70 72 65 70 61 72 65  the "v2" prepare
222e0 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 2c 20  .** interfaces, 
222f0 74 68 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 72  the underlying r
22300 65 61 73 6f 6e 20 66 6f 72 20 74 68 65 20 65 72  eason for the er
22310 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65 64 20  ror is returned 
22320 69 6d 6d 65 64 69 61 74 65 6c 79 2e 0a 2a 2a 20  immediately..** 
22330 3c 2f 6c 69 3e 0a 2a 2a 0a 2a 2a 20 3c 6c 69 3e  </li>.**.** <li>
22340 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70 65 63  .** ^If the spec
22350 69 66 69 63 20 76 61 6c 75 65 20 62 6f 75 6e 64  ific value bound
22360 20 74 6f 20 5b 70 61 72 61 6d 65 74 65 72 20 7c   to [parameter |
22370 20 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72 5d   host parameter]
22380 20 69 6e 20 74 68 65 20 0a 2a 2a 20 57 48 45 52   in the .** WHER
22390 45 20 63 6c 61 75 73 65 20 6d 69 67 68 74 20 69  E clause might i
223a0 6e 66 6c 75 65 6e 63 65 20 74 68 65 20 63 68 6f  nfluence the cho
223b0 69 63 65 20 6f 66 20 71 75 65 72 79 20 70 6c 61  ice of query pla
223c0 6e 20 66 6f 72 20 61 20 73 74 61 74 65 6d 65 6e  n for a statemen
223d0 74 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 73  t,.** then the s
223e0 74 61 74 65 6d 65 6e 74 20 77 69 6c 6c 20 62 65  tatement will be
223f0 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
22400 65 63 6f 6d 70 69 6c 65 64 2c 20 61 73 20 69 66  ecompiled, as if
22410 20 74 68 65 72 65 20 68 61 64 20 62 65 65 6e 20   there had been 
22420 0a 2a 2a 20 61 20 73 63 68 65 6d 61 20 63 68 61  .** a schema cha
22430 6e 67 65 2c 20 6f 6e 20 74 68 65 20 66 69 72 73  nge, on the firs
22440 74 20 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  t  [sqlite3_step
22450 28 29 5d 20 63 61 6c 6c 20 66 6f 6c 6c 6f 77 69  ()] call followi
22460 6e 67 20 61 6e 79 20 63 68 61 6e 67 65 0a 2a 2a  ng any change.**
22470 20 74 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33   to the [sqlite3
22480 5f 62 69 6e 64 5f 74 65 78 74 20 7c 20 62 69 6e  _bind_text | bin
22490 64 69 6e 67 73 5d 20 6f 66 20 74 68 61 74 20 5b  dings] of that [
224a0 70 61 72 61 6d 65 74 65 72 5d 2e 20 0a 2a 2a 20  parameter]. .** 
224b0 5e 54 68 65 20 73 70 65 63 69 66 69 63 20 76 61  ^The specific va
224c0 6c 75 65 20 6f 66 20 57 48 45 52 45 2d 63 6c 61  lue of WHERE-cla
224d0 75 73 65 20 5b 70 61 72 61 6d 65 74 65 72 5d 20  use [parameter] 
224e0 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
224f0 74 68 65 20 0a 2a 2a 20 63 68 6f 69 63 65 20 6f  the .** choice o
22500 66 20 71 75 65 72 79 20 70 6c 61 6e 20 69 66 20  f query plan if 
22510 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 69 73  the parameter is
22520 20 74 68 65 20 6c 65 66 74 2d 68 61 6e 64 20 73   the left-hand s
22530 69 64 65 20 6f 66 20 61 20 5b 4c 49 4b 45 5d 0a  ide of a [LIKE].
22540 2a 2a 20 6f 72 20 5b 47 4c 4f 42 5d 20 6f 70 65  ** or [GLOB] ope
22550 72 61 74 6f 72 20 6f 72 20 69 66 20 74 68 65 20  rator or if the 
22560 70 61 72 61 6d 65 74 65 72 20 69 73 20 63 6f 6d  parameter is com
22570 70 61 72 65 64 20 74 6f 20 61 6e 20 69 6e 64 65  pared to an inde
22580 78 65 64 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 61 6e  xed column.** an
22590 64 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 45 4e  d the [SQLITE_EN
225a0 41 42 4c 45 5f 53 54 41 54 32 5d 20 63 6f 6d 70  ABLE_STAT2] comp
225b0 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20  ile-time option 
225c0 69 73 20 65 6e 61 62 6c 65 64 2e 0a 2a 2a 20 74  is enabled..** t
225d0 68 65 20 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 20  he .** </li>.** 
225e0 3c 2f 6f 6c 3e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  </ol>.*/.int sql
225f0 69 74 65 33 5f 70 72 65 70 61 72 65 28 0a 20 20  ite3_prepare(.  
22600 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
22610 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74 61 62          /* Datab
22620 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ase handle */.  
22630 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 53 71 6c  const char *zSql
22640 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 20 73  ,       /* SQL s
22650 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20  tatement, UTF-8 
22660 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74  encoded */.  int
22670 20 6e 42 79 74 65 2c 20 20 20 20 20 20 20 20 20   nByte,         
22680 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20       /* Maximum 
22690 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71 6c 20 69  length of zSql i
226a0 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71  n bytes. */.  sq
226b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53  lite3_stmt **ppS
226c0 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74  tmt,  /* OUT: St
226d0 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a  atement handle *
226e0 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
226f0 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f  *pzTail     /* O
22700 55 54 3a 20 50 6f 69 6e 74 65 72 20 74 6f 20 75  UT: Pointer to u
22710 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66  nused portion of
22720 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20   zSql */.);.int 
22730 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
22740 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
22750 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a  b,            /*
22760 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65   Database handle
22770 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
22780 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a   *zSql,       /*
22790 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20   SQL statement, 
227a0 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a 2f  UTF-8 encoded */
227b0 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20  .  int nByte,   
227c0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61             /* Ma
227d0 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20  ximum length of 
227e0 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a  zSql in bytes. *
227f0 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  /.  sqlite3_stmt
22800 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f   **ppStmt,  /* O
22810 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61  UT: Statement ha
22820 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20  ndle */.  const 
22830 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20 20  char **pzTail   
22840 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65    /* OUT: Pointe
22850 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74  r to unused port
22860 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29  ion of zSql */.)
22870 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72  ;.int sqlite3_pr
22880 65 70 61 72 65 31 36 28 0a 20 20 73 71 6c 69 74  epare16(.  sqlit
22890 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
228a0 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
228b0 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
228c0 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
228d0 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
228e0 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
228f0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
22900 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
22910 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
22920 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
22930 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
22940 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
22950 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
22960 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
22970 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
22980 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
22990 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
229a0 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
229b0 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69  l */.);.int sqli
229c0 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32  te3_prepare16_v2
229d0 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c  (.  sqlite3 *db,
229e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44              /* D
229f0 61 74 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a  atabase handle *
22a00 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a  /.  const void *
22a10 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53  zSql,       /* S
22a20 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54  QL statement, UT
22a30 46 2d 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a  F-16 encoded */.
22a40 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20    int nByte,    
22a50 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78            /* Max
22a60 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a  imum length of z
22a70 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f  Sql in bytes. */
22a80 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20  .  sqlite3_stmt 
22a90 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55  **ppStmt,  /* OU
22aa0 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e  T: Statement han
22ab0 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76  dle */.  const v
22ac0 6f 69 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20  oid **pzTail    
22ad0 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72   /* OUT: Pointer
22ae0 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69   to unused porti
22af0 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b  on of zSql */.);
22b00 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
22b10 3a 20 52 65 74 72 69 65 76 69 6e 67 20 53 74 61  : Retrieving Sta
22b20 74 65 6d 65 6e 74 20 53 51 4c 0a 2a 2a 0a 2a 2a  tement SQL.**.**
22b30 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
22b40 20 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20   can be used to 
22b50 72 65 74 72 69 65 76 65 20 61 20 73 61 76 65 64  retrieve a saved
22b60 20 63 6f 70 79 20 6f 66 20 74 68 65 20 6f 72 69   copy of the ori
22b70 67 69 6e 61 6c 0a 2a 2a 20 53 51 4c 20 74 65 78  ginal.** SQL tex
22b80 74 20 75 73 65 64 20 74 6f 20 63 72 65 61 74 65  t used to create
22b90 20 61 20 5b 70 72 65 70 61 72 65 64 20 73 74 61   a [prepared sta
22ba0 74 65 6d 65 6e 74 5d 20 69 66 20 74 68 61 74 20  tement] if that 
22bb0 73 74 61 74 65 6d 65 6e 74 20 77 61 73 0a 2a 2a  statement was.**
22bc0 20 63 6f 6d 70 69 6c 65 64 20 75 73 69 6e 67 20   compiled using 
22bd0 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65 33 5f  either [sqlite3_
22be0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
22bf0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
22c00 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2f 0a 63 6f  e16_v2()]..*/.co
22c10 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65  nst char *sqlite
22c20 33 5f 73 71 6c 28 73 71 6c 69 74 65 33 5f 73 74  3_sql(sqlite3_st
22c30 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a 0a  mt *pStmt);../*.
22c40 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 74  ** CAPI3REF: Det
22c50 65 72 6d 69 6e 65 20 49 66 20 41 6e 20 53 51 4c  ermine If An SQL
22c60 20 53 74 61 74 65 6d 65 6e 74 20 57 72 69 74 65   Statement Write
22c70 73 20 54 68 65 20 44 61 74 61 62 61 73 65 0a 2a  s The Database.*
22c80 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
22c90 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28  3_stmt_readonly(
22ca0 58 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 74  X) interface ret
22cb0 75 72 6e 73 20 74 72 75 65 20 28 6e 6f 6e 2d 7a  urns true (non-z
22cc0 65 72 6f 29 20 69 66 0a 2a 2a 20 61 6e 64 20 6f  ero) if.** and o
22cd0 6e 6c 79 20 69 66 20 74 68 65 20 5b 70 72 65 70  nly if the [prep
22ce0 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20  ared statement] 
22cf0 58 20 6d 61 6b 65 73 20 6e 6f 20 64 69 72 65 63  X makes no direc
22d00 74 20 63 68 61 6e 67 65 73 20 74 6f 0a 2a 2a 20  t changes to.** 
22d10 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74  the content of t
22d20 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
22d30 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65 20 74 68 61  ..**.** Note tha
22d40 74 20 5b 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  t [application-d
22d50 65 66 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74  efined SQL funct
22d60 69 6f 6e 73 5d 20 6f 72 0a 2a 2a 20 5b 76 69 72  ions] or.** [vir
22d70 74 75 61 6c 20 74 61 62 6c 65 73 5d 20 6d 69 67  tual tables] mig
22d80 68 74 20 63 68 61 6e 67 65 20 74 68 65 20 64 61  ht change the da
22d90 74 61 62 61 73 65 20 69 6e 64 69 72 65 63 74 6c  tabase indirectl
22da0 79 20 61 73 20 61 20 73 69 64 65 20 65 66 66 65  y as a side effe
22db0 63 74 2e 20 20 0a 2a 2a 20 5e 28 46 6f 72 20 65  ct.  .** ^(For e
22dc0 78 61 6d 70 6c 65 2c 20 69 66 20 61 6e 20 61 70  xample, if an ap
22dd0 70 6c 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65  plication define
22de0 73 20 61 20 66 75 6e 63 74 69 6f 6e 20 22 65 76  s a function "ev
22df0 61 6c 28 29 22 20 74 68 61 74 20 0a 2a 2a 20 63  al()" that .** c
22e00 61 6c 6c 73 20 5b 73 71 6c 69 74 65 33 5f 65 78  alls [sqlite3_ex
22e10 65 63 28 29 5d 2c 20 74 68 65 6e 20 74 68 65 20  ec()], then the 
22e20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c 20 73 74  following SQL st
22e30 61 74 65 6d 65 6e 74 20 77 6f 75 6c 64 0a 2a 2a  atement would.**
22e40 20 63 68 61 6e 67 65 20 74 68 65 20 64 61 74 61   change the data
22e50 62 61 73 65 20 66 69 6c 65 20 74 68 72 6f 75 67  base file throug
22e60 68 20 73 69 64 65 2d 65 66 66 65 63 74 73 3a 0a  h side-effects:.
22e70 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74  **.** <blockquot
22e80 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20 53 45  e><pre>.**    SE
22e90 4c 45 43 54 20 65 76 61 6c 28 27 44 45 4c 45 54  LECT eval('DELET
22ea0 45 20 46 52 4f 4d 20 74 31 27 29 20 46 52 4f 4d  E FROM t1') FROM
22eb0 20 74 32 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f   t2;.** </pre></
22ec0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a  blockquote>.**.*
22ed0 2a 20 42 75 74 20 62 65 63 61 75 73 65 20 74 68  * But because th
22ee0 65 20 5b 53 45 4c 45 43 54 5d 20 73 74 61 74 65  e [SELECT] state
22ef0 6d 65 6e 74 20 64 6f 65 73 20 6e 6f 74 20 63 68  ment does not ch
22f00 61 6e 67 65 20 74 68 65 20 64 61 74 61 62 61 73  ange the databas
22f10 65 20 66 69 6c 65 0a 2a 2a 20 64 69 72 65 63 74  e file.** direct
22f20 6c 79 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  ly, sqlite3_stmt
22f30 5f 72 65 61 64 6f 6e 6c 79 28 29 20 77 6f 75 6c  _readonly() woul
22f40 64 20 73 74 69 6c 6c 20 72 65 74 75 72 6e 20 74  d still return t
22f50 72 75 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 54 72  rue.)^.**.** ^Tr
22f60 61 6e 73 61 63 74 69 6f 6e 20 63 6f 6e 74 72 6f  ansaction contro
22f70 6c 20 73 74 61 74 65 6d 65 6e 74 73 20 73 75 63  l statements suc
22f80 68 20 61 73 20 5b 42 45 47 49 4e 5d 2c 20 5b 43  h as [BEGIN], [C
22f90 4f 4d 4d 49 54 5d 2c 20 5b 52 4f 4c 4c 42 41 43  OMMIT], [ROLLBAC
22fa0 4b 5d 2c 0a 2a 2a 20 5b 53 41 56 45 50 4f 49 4e  K],.** [SAVEPOIN
22fb0 54 5d 2c 20 61 6e 64 20 5b 52 45 4c 45 41 53 45  T], and [RELEASE
22fc0 5d 20 63 61 75 73 65 20 73 71 6c 69 74 65 33 5f  ] cause sqlite3_
22fd0 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 29 20  stmt_readonly() 
22fe0 74 6f 20 72 65 74 75 72 6e 20 74 72 75 65 2c 0a  to return true,.
22ff0 2a 2a 20 73 69 6e 63 65 20 74 68 65 20 73 74 61  ** since the sta
23000 74 65 6d 65 6e 74 73 20 74 68 65 6d 73 65 6c 76  tements themselv
23010 65 73 20 64 6f 20 6e 6f 74 20 61 63 74 75 61 6c  es do not actual
23020 6c 79 20 6d 6f 64 69 66 79 20 74 68 65 20 64 61  ly modify the da
23030 74 61 62 61 73 65 20 62 75 74 0a 2a 2a 20 72 61  tabase but.** ra
23040 74 68 65 72 20 74 68 65 79 20 63 6f 6e 74 72 6f  ther they contro
23050 6c 20 74 68 65 20 74 69 6d 69 6e 67 20 6f 66 20  l the timing of 
23060 77 68 65 6e 20 6f 74 68 65 72 20 73 74 61 74 65  when other state
23070 6d 65 6e 74 73 20 6d 6f 64 69 66 79 20 74 68 65  ments modify the
23080 20 0a 2a 2a 20 64 61 74 61 62 61 73 65 2e 20 20   .** database.  
23090 5e 54 68 65 20 5b 41 54 54 41 43 48 5d 20 61 6e  ^The [ATTACH] an
230a0 64 20 5b 44 45 54 41 43 48 5d 20 73 74 61 74 65  d [DETACH] state
230b0 6d 65 6e 74 73 20 61 6c 73 6f 20 63 61 75 73 65  ments also cause
230c0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73 74 6d 74  .** sqlite3_stmt
230d0 5f 72 65 61 64 6f 6e 6c 79 28 29 20 74 6f 20 72  _readonly() to r
230e0 65 74 75 72 6e 20 74 72 75 65 20 73 69 6e 63 65  eturn true since
230f0 2c 20 77 68 69 6c 65 20 74 68 6f 73 65 20 73 74  , while those st
23100 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 63 68 61 6e  atements.** chan
23110 67 65 20 74 68 65 20 63 6f 6e 66 69 67 75 72 61  ge the configura
23120 74 69 6f 6e 20 6f 66 20 61 20 64 61 74 61 62 61  tion of a databa
23130 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2c 20 74  se connection, t
23140 68 65 79 20 64 6f 20 6e 6f 74 20 6d 61 6b 65 20  hey do not make 
23150 0a 2a 2a 20 63 68 61 6e 67 65 73 20 74 6f 20 74  .** changes to t
23160 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20 74 68  he content of th
23170 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65 73  e database files
23180 20 6f 6e 20 64 69 73 6b 2e 0a 2a 2f 0a 69 6e 74   on disk..*/.int
23190 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
231a0 61 64 6f 6e 6c 79 28 73 71 6c 69 74 65 33 5f 73  adonly(sqlite3_s
231b0 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
231c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 79  .** CAPI3REF: Dy
231d0 6e 61 6d 69 63 61 6c 6c 79 20 54 79 70 65 64 20  namically Typed 
231e0 56 61 6c 75 65 20 4f 62 6a 65 63 74 0a 2a 2a 20  Value Object.** 
231f0 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72 6f 74 65  KEYWORDS: {prote
23200 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
23210 75 65 7d 20 7b 75 6e 70 72 6f 74 65 63 74 65 64  ue} {unprotected
23220 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 7d 0a   sqlite3_value}.
23230 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73 65  **.** SQLite use
23240 73 20 74 68 65 20 73 71 6c 69 74 65 33 5f 76 61  s the sqlite3_va
23250 6c 75 65 20 6f 62 6a 65 63 74 20 74 6f 20 72 65  lue object to re
23260 70 72 65 73 65 6e 74 20 61 6c 6c 20 76 61 6c 75  present all valu
23270 65 73 0a 2a 2a 20 74 68 61 74 20 63 61 6e 20 62  es.** that can b
23280 65 20 73 74 6f 72 65 64 20 69 6e 20 61 20 64 61  e stored in a da
23290 74 61 62 61 73 65 20 74 61 62 6c 65 2e 20 53 51  tabase table. SQ
232a0 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
232b0 63 20 74 79 70 69 6e 67 0a 2a 2a 20 66 6f 72 20  c typing.** for 
232c0 74 68 65 20 76 61 6c 75 65 73 20 69 74 20 73 74  the values it st
232d0 6f 72 65 73 2e 20 20 5e 56 61 6c 75 65 73 20 73  ores.  ^Values s
232e0 74 6f 72 65 64 20 69 6e 20 73 71 6c 69 74 65 33  tored in sqlite3
232f0 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 0a 2a  _value objects.*
23300 2a 20 63 61 6e 20 62 65 20 69 6e 74 65 67 65 72  * can be integer
23310 73 2c 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  s, floating poin
23320 74 20 76 61 6c 75 65 73 2c 20 73 74 72 69 6e 67  t values, string
23330 73 2c 20 42 4c 4f 42 73 2c 20 6f 72 20 4e 55 4c  s, BLOBs, or NUL
23340 4c 2e 0a 2a 2a 0a 2a 2a 20 41 6e 20 73 71 6c 69  L..**.** An sqli
23350 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
23360 20 6d 61 79 20 62 65 20 65 69 74 68 65 72 20 22   may be either "
23370 70 72 6f 74 65 63 74 65 64 22 20 6f 72 20 22 75  protected" or "u
23380 6e 70 72 6f 74 65 63 74 65 64 22 2e 0a 2a 2a 20  nprotected"..** 
23390 53 6f 6d 65 20 69 6e 74 65 72 66 61 63 65 73 20  Some interfaces 
233a0 72 65 71 75 69 72 65 20 61 20 70 72 6f 74 65 63  require a protec
233b0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
233c0 65 2e 20 20 4f 74 68 65 72 20 69 6e 74 65 72 66  e.  Other interf
233d0 61 63 65 73 0a 2a 2a 20 77 69 6c 6c 20 61 63 63  aces.** will acc
233e0 65 70 74 20 65 69 74 68 65 72 20 61 20 70 72 6f  ept either a pro
233f0 74 65 63 74 65 64 20 6f 72 20 61 6e 20 75 6e 70  tected or an unp
23400 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
23410 5f 76 61 6c 75 65 2e 0a 2a 2a 20 45 76 65 72 79  _value..** Every
23420 20 69 6e 74 65 72 66 61 63 65 20 74 68 61 74 20   interface that 
23430 61 63 63 65 70 74 73 20 73 71 6c 69 74 65 33 5f  accepts sqlite3_
23440 76 61 6c 75 65 20 61 72 67 75 6d 65 6e 74 73 20  value arguments 
23450 73 70 65 63 69 66 69 65 73 0a 2a 2a 20 77 68 65  specifies.** whe
23460 74 68 65 72 20 6f 72 20 6e 6f 74 20 69 74 20 72  ther or not it r
23470 65 71 75 69 72 65 73 20 61 20 70 72 6f 74 65 63  equires a protec
23480 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
23490 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 65 72  e..**.** The ter
234a0 6d 73 20 22 70 72 6f 74 65 63 74 65 64 22 20 61  ms "protected" a
234b0 6e 64 20 22 75 6e 70 72 6f 74 65 63 74 65 64 22  nd "unprotected"
234c0 20 72 65 66 65 72 20 74 6f 20 77 68 65 74 68 65   refer to whethe
234d0 72 20 6f 72 20 6e 6f 74 0a 2a 2a 20 61 20 6d 75  r or not.** a mu
234e0 74 65 78 20 69 73 20 68 65 6c 64 2e 20 20 41 6e  tex is held.  An
234f0 20 69 6e 74 65 72 6e 61 6c 20 6d 75 74 65 78 20   internal mutex 
23500 69 73 20 68 65 6c 64 20 66 6f 72 20 61 20 70 72  is held for a pr
23510 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
23520 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 20  e3_value object 
23530 62 75 74 20 6e 6f 20 6d 75 74 65 78 20 69 73 20  but no mutex is 
23540 68 65 6c 64 20 66 6f 72 20 61 6e 20 75 6e 70 72  held for an unpr
23550 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
23560 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 2e  e3_value object.
23570 20 20 49 66 20 53 51 4c 69 74 65 20 69 73 20 63    If SQLite is c
23580 6f 6d 70 69 6c 65 64 20 74 6f 20 62 65 20 73 69  ompiled to be si
23590 6e 67 6c 65 2d 74 68 72 65 61 64 65 64 0a 2a 2a  ngle-threaded.**
235a0 20 28 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 54   (with [SQLITE_T
235b0 48 52 45 41 44 53 41 46 45 3d 30 5d 20 61 6e 64  HREADSAFE=0] and
235c0 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33 5f 74   with [sqlite3_t
235d0 68 72 65 61 64 73 61 66 65 28 29 5d 20 72 65 74  hreadsafe()] ret
235e0 75 72 6e 69 6e 67 20 30 29 0a 2a 2a 20 6f 72 20  urning 0).** or 
235f0 69 66 20 53 51 4c 69 74 65 20 69 73 20 72 75 6e  if SQLite is run
23600 20 69 6e 20 6f 6e 65 20 6f 66 20 72 65 64 75 63   in one of reduc
23610 65 64 20 6d 75 74 65 78 20 6d 6f 64 65 73 20 0a  ed mutex modes .
23620 2a 2a 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ** [SQLITE_CONFI
23630 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 5d 20  G_SINGLETHREAD] 
23640 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  or [SQLITE_CONFI
23650 47 5f 4d 55 4c 54 49 54 48 52 45 41 44 5d 0a 2a  G_MULTITHREAD].*
23660 2a 20 74 68 65 6e 20 74 68 65 72 65 20 69 73 20  * then there is 
23670 6e 6f 20 64 69 73 74 69 6e 63 74 69 6f 6e 20 62  no distinction b
23680 65 74 77 65 65 6e 20 70 72 6f 74 65 63 74 65 64  etween protected
23690 20 61 6e 64 20 75 6e 70 72 6f 74 65 63 74 65 64   and unprotected
236a0 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  .** sqlite3_valu
236b0 65 20 6f 62 6a 65 63 74 73 20 61 6e 64 20 74 68  e objects and th
236c0 65 79 20 63 61 6e 20 62 65 20 75 73 65 64 20 69  ey can be used i
236d0 6e 74 65 72 63 68 61 6e 67 65 61 62 6c 79 2e 20  nterchangeably. 
236e0 20 48 6f 77 65 76 65 72 2c 0a 2a 2a 20 66 6f 72   However,.** for
236f0 20 6d 61 78 69 6d 75 6d 20 63 6f 64 65 20 70 6f   maximum code po
23700 72 74 61 62 69 6c 69 74 79 20 69 74 20 69 73 20  rtability it is 
23710 72 65 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74  recommended that
23720 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   applications.**
23730 20 73 74 69 6c 6c 20 6d 61 6b 65 20 74 68 65 20   still make the 
23740 64 69 73 74 69 6e 63 74 69 6f 6e 20 62 65 74 77  distinction betw
23750 65 65 6e 20 70 72 6f 74 65 63 74 65 64 20 61 6e  een protected an
23760 64 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a 2a  d unprotected.**
23770 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f   sqlite3_value o
23780 62 6a 65 63 74 73 20 65 76 65 6e 20 77 68 65 6e  bjects even when
23790 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 72 65   not strictly re
237a0 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  quired..**.** ^T
237b0 68 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  he sqlite3_value
237c0 20 6f 62 6a 65 63 74 73 20 74 68 61 74 20 61 72   objects that ar
237d0 65 20 70 61 73 73 65 64 20 61 73 20 70 61 72 61  e passed as para
237e0 6d 65 74 65 72 73 20 69 6e 74 6f 20 74 68 65 0a  meters into the.
237f0 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
23800 6e 20 6f 66 20 5b 61 70 70 6c 69 63 61 74 69 6f  n of [applicatio
23810 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
23820 6e 63 74 69 6f 6e 73 5d 20 61 72 65 20 70 72 6f  nctions] are pro
23830 74 65 63 74 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  tected..** ^The 
23840 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
23850 6a 65 63 74 20 72 65 74 75 72 6e 65 64 20 62 79  ject returned by
23860 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
23870 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
23880 75 6e 70 72 6f 74 65 63 74 65 64 2e 0a 2a 2a 20  unprotected..** 
23890 55 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69  Unprotected sqli
238a0 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74  te3_value object
238b0 73 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  s may only be us
238c0 65 64 20 77 69 74 68 0a 2a 2a 20 5b 73 71 6c 69  ed with.** [sqli
238d0 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
238e0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
238f0 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 2e 0a  _bind_value()]..
23900 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f  ** The [sqlite3_
23910 76 61 6c 75 65 5f 62 6c 6f 62 20 7c 20 73 71 6c  value_blob | sql
23920 69 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28  ite3_value_type(
23930 29 5d 20 66 61 6d 69 6c 79 20 6f 66 0a 2a 2a 20  )] family of.** 
23940 69 6e 74 65 72 66 61 63 65 73 20 72 65 71 75 69  interfaces requi
23950 72 65 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c  re protected sql
23960 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
23970 74 73 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  ts..*/.typedef s
23980 74 72 75 63 74 20 4d 65 6d 20 73 71 6c 69 74 65  truct Mem sqlite
23990 33 5f 76 61 6c 75 65 3b 0a 0a 2f 2a 0a 2a 2a 20  3_value;../*.** 
239a0 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 46 75  CAPI3REF: SQL Fu
239b0 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78 74 20 4f  nction Context O
239c0 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65 20  bject.**.** The 
239d0 63 6f 6e 74 65 78 74 20 69 6e 20 77 68 69 63 68  context in which
239e0 20 61 6e 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e   an SQL function
239f0 20 65 78 65 63 75 74 65 73 20 69 73 20 73 74 6f   executes is sto
23a00 72 65 64 20 69 6e 20 61 6e 0a 2a 2a 20 73 71 6c  red in an.** sql
23a10 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62 6a  ite3_context obj
23a20 65 63 74 2e 20 20 5e 41 20 70 6f 69 6e 74 65 72  ect.  ^A pointer
23a30 20 74 6f 20 61 6e 20 73 71 6c 69 74 65 33 5f 63   to an sqlite3_c
23a40 6f 6e 74 65 78 74 20 6f 62 6a 65 63 74 0a 2a 2a  ontext object.**
23a50 20 69 73 20 61 6c 77 61 79 73 20 66 69 72 73 74   is always first
23a60 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 61   parameter to [a
23a70 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
23a80 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ed SQL functions
23a90 5d 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63  ]..** The applic
23aa0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
23ab0 4c 20 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65  L function imple
23ac0 6d 65 6e 74 61 74 69 6f 6e 20 77 69 6c 6c 20 70  mentation will p
23ad0 61 73 73 20 74 68 69 73 0a 2a 2a 20 70 6f 69 6e  ass this.** poin
23ae0 74 65 72 20 74 68 72 6f 75 67 68 20 69 6e 74 6f  ter through into
23af0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
23b00 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 20 7c 20  e3_result_int | 
23b10 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 28 29  sqlite3_result()
23b20 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 61  ],.** [sqlite3_a
23b30 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
23b40 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 75 73  ()], [sqlite3_us
23b50 65 72 5f 64 61 74 61 28 29 5d 2c 0a 2a 2a 20 5b  er_data()],.** [
23b60 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f  sqlite3_context_
23b70 64 62 5f 68 61 6e 64 6c 65 28 29 5d 2c 20 5b 73  db_handle()], [s
23b80 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
23b90 74 61 28 29 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f 72  ta()],.** and/or
23ba0 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75   [sqlite3_set_au
23bb0 78 64 61 74 61 28 29 5d 2e 0a 2a 2f 0a 74 79 70  xdata()]..*/.typ
23bc0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
23bd0 74 65 33 5f 63 6f 6e 74 65 78 74 20 73 71 6c 69  te3_context sqli
23be0 74 65 33 5f 63 6f 6e 74 65 78 74 3b 0a 0a 2f 2a  te3_context;../*
23bf0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 42 69  .** CAPI3REF: Bi
23c00 6e 64 69 6e 67 20 56 61 6c 75 65 73 20 54 6f 20  nding Values To 
23c10 50 72 65 70 61 72 65 64 20 53 74 61 74 65 6d 65  Prepared Stateme
23c20 6e 74 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  nts.** KEYWORDS:
23c30 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65 72   {host parameter
23c40 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65 74 65  } {host paramete
23c50 72 73 7d 20 7b 68 6f 73 74 20 70 61 72 61 6d 65  rs} {host parame
23c60 74 65 72 20 6e 61 6d 65 7d 0a 2a 2a 20 4b 45 59  ter name}.** KEY
23c70 57 4f 52 44 53 3a 20 7b 53 51 4c 20 70 61 72 61  WORDS: {SQL para
23c80 6d 65 74 65 72 7d 20 7b 53 51 4c 20 70 61 72 61  meter} {SQL para
23c90 6d 65 74 65 72 73 7d 20 7b 70 61 72 61 6d 65 74  meters} {paramet
23ca0 65 72 20 62 69 6e 64 69 6e 67 7d 0a 2a 2a 0a 2a  er binding}.**.*
23cb0 2a 20 5e 28 49 6e 20 74 68 65 20 53 51 4c 20 73  * ^(In the SQL s
23cc0 74 61 74 65 6d 65 6e 74 20 74 65 78 74 20 69 6e  tatement text in
23cd0 70 75 74 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  put to [sqlite3_
23ce0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e  prepare_v2()] an
23cf0 64 20 69 74 73 20 76 61 72 69 61 6e 74 73 2c 0a  d its variants,.
23d00 2a 2a 20 6c 69 74 65 72 61 6c 73 20 6d 61 79 20  ** literals may 
23d10 62 65 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  be replaced by a
23d20 20 5b 70 61 72 61 6d 65 74 65 72 5d 20 74 68 61   [parameter] tha
23d30 74 20 6d 61 74 63 68 65 73 20 6f 6e 65 20 6f 66  t matches one of
23d40 20 66 6f 6c 6c 6f 77 69 6e 67 0a 2a 2a 20 74 65   following.** te
23d50 6d 70 6c 61 74 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  mplates:.**.** <
23d60 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 3f 0a 2a  ul>.** <li>  ?.*
23d70 2a 20 3c 6c 69 3e 20 20 3f 4e 4e 4e 0a 2a 2a 20  * <li>  ?NNN.** 
23d80 3c 6c 69 3e 20 20 3a 56 56 56 0a 2a 2a 20 3c 6c  <li>  :VVV.** <l
23d90 69 3e 20 20 40 56 56 56 0a 2a 2a 20 3c 6c 69 3e  i>  @VVV.** <li>
23da0 20 20 24 56 56 56 0a 2a 2a 20 3c 2f 75 6c 3e 0a    $VVV.** </ul>.
23db0 2a 2a 0a 2a 2a 20 49 6e 20 74 68 65 20 74 65 6d  **.** In the tem
23dc0 70 6c 61 74 65 73 20 61 62 6f 76 65 2c 20 4e 4e  plates above, NN
23dd0 4e 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20  N represents an 
23de0 69 6e 74 65 67 65 72 20 6c 69 74 65 72 61 6c 2c  integer literal,
23df0 0a 2a 2a 20 61 6e 64 20 56 56 56 20 72 65 70 72  .** and VVV repr
23e00 65 73 65 6e 74 73 20 61 6e 20 61 6c 70 68 61 6e  esents an alphan
23e10 75 6d 65 72 69 63 20 69 64 65 6e 74 69 66 69 65  umeric identifie
23e20 72 2e 29 5e 20 20 5e 54 68 65 20 76 61 6c 75 65  r.)^  ^The value
23e30 73 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20 70 61  s of these.** pa
23e40 72 61 6d 65 74 65 72 73 20 28 61 6c 73 6f 20 63  rameters (also c
23e50 61 6c 6c 65 64 20 22 68 6f 73 74 20 70 61 72 61  alled "host para
23e60 6d 65 74 65 72 20 6e 61 6d 65 73 22 20 6f 72 20  meter names" or 
23e70 22 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73 22  "SQL parameters"
23e80 29 0a 2a 2a 20 63 61 6e 20 62 65 20 73 65 74 20  ).** can be set 
23e90 75 73 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65  using the sqlite
23ea0 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
23eb0 6e 65 73 20 64 65 66 69 6e 65 64 20 68 65 72 65  nes defined here
23ec0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 72  ..**.** ^The fir
23ed0 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 74  st argument to t
23ee0 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
23ef0 2a 28 29 20 72 6f 75 74 69 6e 65 73 20 69 73 20  *() routines is 
23f00 61 6c 77 61 79 73 0a 2a 2a 20 61 20 70 6f 69 6e  always.** a poin
23f10 74 65 72 20 74 6f 20 74 68 65 20 5b 73 71 6c 69  ter to the [sqli
23f20 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63 74  te3_stmt] object
23f30 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 0a 2a   returned from.*
23f40 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  * [sqlite3_prepa
23f50 72 65 5f 76 32 28 29 5d 20 6f 72 20 69 74 73 20  re_v2()] or its 
23f60 76 61 72 69 61 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20  variants..**.** 
23f70 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
23f80 6d 65 6e 74 20 69 73 20 74 68 65 20 69 6e 64 65  ment is the inde
23f90 78 20 6f 66 20 74 68 65 20 53 51 4c 20 70 61 72  x of the SQL par
23fa0 61 6d 65 74 65 72 20 74 6f 20 62 65 20 73 65 74  ameter to be set
23fb0 2e 0a 2a 2a 20 5e 54 68 65 20 6c 65 66 74 6d 6f  ..** ^The leftmo
23fc0 73 74 20 53 51 4c 20 70 61 72 61 6d 65 74 65 72  st SQL parameter
23fd0 20 68 61 73 20 61 6e 20 69 6e 64 65 78 20 6f 66   has an index of
23fe0 20 31 2e 20 20 5e 57 68 65 6e 20 74 68 65 20 73   1.  ^When the s
23ff0 61 6d 65 20 6e 61 6d 65 64 0a 2a 2a 20 53 51 4c  ame named.** SQL
24000 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 75 73   parameter is us
24010 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 63  ed more than onc
24020 65 2c 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75  e, second and su
24030 62 73 65 71 75 65 6e 74 0a 2a 2a 20 6f 63 63 75  bsequent.** occu
24040 72 72 65 6e 63 65 73 20 68 61 76 65 20 74 68 65  rrences have the
24050 20 73 61 6d 65 20 69 6e 64 65 78 20 61 73 20 74   same index as t
24060 68 65 20 66 69 72 73 74 20 6f 63 63 75 72 72 65  he first occurre
24070 6e 63 65 2e 0a 2a 2a 20 5e 54 68 65 20 69 6e 64  nce..** ^The ind
24080 65 78 20 66 6f 72 20 6e 61 6d 65 64 20 70 61 72  ex for named par
24090 61 6d 65 74 65 72 73 20 63 61 6e 20 62 65 20 6c  ameters can be l
240a0 6f 6f 6b 65 64 20 75 70 20 75 73 69 6e 67 20 74  ooked up using t
240b0 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62  he.** [sqlite3_b
240c0 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e  ind_parameter_in
240d0 64 65 78 28 29 5d 20 41 50 49 20 69 66 20 64 65  dex()] API if de
240e0 73 69 72 65 64 2e 20 20 5e 54 68 65 20 69 6e 64  sired.  ^The ind
240f0 65 78 0a 2a 2a 20 66 6f 72 20 22 3f 4e 4e 4e 22  ex.** for "?NNN"
24100 20 70 61 72 61 6d 65 74 65 72 73 20 69 73 20 74   parameters is t
24110 68 65 20 76 61 6c 75 65 20 6f 66 20 4e 4e 4e 2e  he value of NNN.
24120 0a 2a 2a 20 5e 54 68 65 20 4e 4e 4e 20 76 61 6c  .** ^The NNN val
24130 75 65 20 6d 75 73 74 20 62 65 20 62 65 74 77 65  ue must be betwe
24140 65 6e 20 31 20 61 6e 64 20 74 68 65 20 5b 73 71  en 1 and the [sq
24150 6c 69 74 65 33 5f 6c 69 6d 69 74 28 29 5d 0a 2a  lite3_limit()].*
24160 2a 20 70 61 72 61 6d 65 74 65 72 20 5b 53 51 4c  * parameter [SQL
24170 49 54 45 5f 4c 49 4d 49 54 5f 56 41 52 49 41 42  ITE_LIMIT_VARIAB
24180 4c 45 5f 4e 55 4d 42 45 52 5d 20 28 64 65 66 61  LE_NUMBER] (defa
24190 75 6c 74 20 76 61 6c 75 65 3a 20 39 39 39 29 2e  ult value: 999).
241a0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69 72  .**.** ^The thir
241b0 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
241c0 65 20 76 61 6c 75 65 20 74 6f 20 62 69 6e 64 20  e value to bind 
241d0 74 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  to the parameter
241e0 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68 6f  ..**.** ^(In tho
241f0 73 65 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74  se routines that
24200 20 68 61 76 65 20 61 20 66 6f 75 72 74 68 20 61   have a fourth a
24210 72 67 75 6d 65 6e 74 2c 20 69 74 73 20 76 61 6c  rgument, its val
24220 75 65 20 69 73 20 74 68 65 0a 2a 2a 20 6e 75 6d  ue is the.** num
24230 62 65 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20  ber of bytes in 
24240 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 20 20  the parameter.  
24250 54 6f 20 62 65 20 63 6c 65 61 72 3a 20 74 68 65  To be clear: the
24260 20 76 61 6c 75 65 20 69 73 20 74 68 65 0a 2a 2a   value is the.**
24270 20 6e 75 6d 62 65 72 20 6f 66 20 3c 75 3e 62 79   number of <u>by
24280 74 65 73 3c 2f 75 3e 20 69 6e 20 74 68 65 20 76  tes</u> in the v
24290 61 6c 75 65 2c 20 6e 6f 74 20 74 68 65 20 6e 75  alue, not the nu
242a0 6d 62 65 72 20 6f 66 20 63 68 61 72 61 63 74 65  mber of characte
242b0 72 73 2e 29 5e 0a 2a 2a 20 5e 49 66 20 74 68 65  rs.)^.** ^If the
242c0 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65 74 65   fourth paramete
242d0 72 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74  r is negative, t
242e0 68 65 20 6c 65 6e 67 74 68 20 6f 66 20 74 68 65  he length of the
242f0 20 73 74 72 69 6e 67 20 69 73 0a 2a 2a 20 74 68   string is.** th
24300 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
24310 73 20 75 70 20 74 6f 20 74 68 65 20 66 69 72 73  s up to the firs
24320 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74 6f  t zero terminato
24330 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  r..**.** ^The fi
24340 66 74 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  fth argument to 
24350 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f  sqlite3_bind_blo
24360 62 28 29 2c 20 73 71 6c 69 74 65 33 5f 62 69 6e  b(), sqlite3_bin
24370 64 5f 74 65 78 74 28 29 2c 20 61 6e 64 0a 2a 2a  d_text(), and.**
24380 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65   sqlite3_bind_te
24390 78 74 31 36 28 29 20 69 73 20 61 20 64 65 73 74  xt16() is a dest
243a0 72 75 63 74 6f 72 20 75 73 65 64 20 74 6f 20 64  ructor used to d
243b0 69 73 70 6f 73 65 20 6f 66 20 74 68 65 20 42 4c  ispose of the BL
243c0 4f 42 20 6f 72 0a 2a 2a 20 73 74 72 69 6e 67 20  OB or.** string 
243d0 61 66 74 65 72 20 53 51 4c 69 74 65 20 68 61 73  after SQLite has
243e0 20 66 69 6e 69 73 68 65 64 20 77 69 74 68 20 69   finished with i
243f0 74 2e 20 20 5e 54 68 65 20 64 65 73 74 72 75 63  t.  ^The destruc
24400 74 6f 72 20 69 73 20 63 61 6c 6c 65 64 0a 2a 2a  tor is called.**
24410 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66 20 74   to dispose of t
24420 68 65 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  he BLOB or strin
24430 67 20 65 76 65 6e 20 69 66 20 74 68 65 20 63 61  g even if the ca
24440 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 62 69  ll to sqlite3_bi
24450 6e 64 5f 62 6c 6f 62 28 29 2c 0a 2a 2a 20 73 71  nd_blob(),.** sq
24460 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28  lite3_bind_text(
24470 29 2c 20 6f 72 20 73 71 6c 69 74 65 33 5f 62 69  ), or sqlite3_bi
24480 6e 64 5f 74 65 78 74 31 36 28 29 20 66 61 69 6c  nd_text16() fail
24490 73 2e 20 20 0a 2a 2a 20 5e 49 66 20 74 68 65 20  s.  .** ^If the 
244a0 66 69 66 74 68 20 61 72 67 75 6d 65 6e 74 20 69  fifth argument i
244b0 73 0a 2a 2a 20 74 68 65 20 73 70 65 63 69 61 6c  s.** the special
244c0 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45 5f 53   value [SQLITE_S
244d0 54 41 54 49 43 5d 2c 20 74 68 65 6e 20 53 51 4c  TATIC], then SQL
244e0 69 74 65 20 61 73 73 75 6d 65 73 20 74 68 61 74  ite assumes that
244f0 20 74 68 65 0a 2a 2a 20 69 6e 66 6f 72 6d 61 74   the.** informat
24500 69 6f 6e 20 69 73 20 69 6e 20 73 74 61 74 69 63  ion is in static
24510 2c 20 75 6e 6d 61 6e 61 67 65 64 20 73 70 61 63  , unmanaged spac
24520 65 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 20 6e  e and does not n
24530 65 65 64 20 74 6f 20 62 65 20 66 72 65 65 64 2e  eed to be freed.
24540 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 66 74  .** ^If the fift
24550 68 20 61 72 67 75 6d 65 6e 74 20 68 61 73 20 74  h argument has t
24560 68 65 20 76 61 6c 75 65 20 5b 53 51 4c 49 54 45  he value [SQLITE
24570 5f 54 52 41 4e 53 49 45 4e 54 5d 2c 20 74 68 65  _TRANSIENT], the
24580 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 6d 61 6b 65  n.** SQLite make
24590 73 20 69 74 73 20 6f 77 6e 20 70 72 69 76 61 74  s its own privat
245a0 65 20 63 6f 70 79 20 6f 66 20 74 68 65 20 64 61  e copy of the da
245b0 74 61 20 69 6d 6d 65 64 69 61 74 65 6c 79 2c 20  ta immediately, 
245c0 62 65 66 6f 72 65 0a 2a 2a 20 74 68 65 20 73 71  before.** the sq
245d0 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20 72  lite3_bind_*() r
245e0 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 2e 0a  outine returns..
245f0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
24600 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f 62  e3_bind_zeroblob
24610 28 29 20 72 6f 75 74 69 6e 65 20 62 69 6e 64 73  () routine binds
24620 20 61 20 42 4c 4f 42 20 6f 66 20 6c 65 6e 67 74   a BLOB of lengt
24630 68 20 4e 20 74 68 61 74 0a 2a 2a 20 69 73 20 66  h N that.** is f
24640 69 6c 6c 65 64 20 77 69 74 68 20 7a 65 72 6f 65  illed with zeroe
24650 73 2e 20 20 5e 41 20 7a 65 72 6f 62 6c 6f 62 20  s.  ^A zeroblob 
24660 75 73 65 73 20 61 20 66 69 78 65 64 20 61 6d 6f  uses a fixed amo
24670 75 6e 74 20 6f 66 20 6d 65 6d 6f 72 79 0a 2a 2a  unt of memory.**
24680 20 28 6a 75 73 74 20 61 6e 20 69 6e 74 65 67 65   (just an intege
24690 72 20 74 6f 20 68 6f 6c 64 20 69 74 73 20 73 69  r to hold its si
246a0 7a 65 29 20 77 68 69 6c 65 20 69 74 20 69 73 20  ze) while it is 
246b0 62 65 69 6e 67 20 70 72 6f 63 65 73 73 65 64 2e  being processed.
246c0 0a 2a 2a 20 5a 65 72 6f 62 6c 6f 62 73 20 61 72  .** Zeroblobs ar
246d0 65 20 69 6e 74 65 6e 64 65 64 20 74 6f 20 73 65  e intended to se
246e0 72 76 65 20 61 73 20 70 6c 61 63 65 68 6f 6c 64  rve as placehold
246f0 65 72 73 20 66 6f 72 20 42 4c 4f 42 73 20 77 68  ers for BLOBs wh
24700 6f 73 65 0a 2a 2a 20 63 6f 6e 74 65 6e 74 20 69  ose.** content i
24710 73 20 6c 61 74 65 72 20 77 72 69 74 74 65 6e 20  s later written 
24720 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74 65  using.** [sqlite
24730 33 5f 62 6c 6f 62 5f 6f 70 65 6e 20 7c 20 69 6e  3_blob_open | in
24740 63 72 65 6d 65 6e 74 61 6c 20 42 4c 4f 42 20 49  cremental BLOB I
24750 2f 4f 5d 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a  /O] routines..**
24760 20 5e 41 20 6e 65 67 61 74 69 76 65 20 76 61 6c   ^A negative val
24770 75 65 20 66 6f 72 20 74 68 65 20 7a 65 72 6f 62  ue for the zerob
24780 6c 6f 62 20 72 65 73 75 6c 74 73 20 69 6e 20 61  lob results in a
24790 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c 4f   zero-length BLO
247a0 42 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e 79  B..**.** ^If any
247b0 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65 33 5f   of the sqlite3_
247c0 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65  bind_*() routine
247d0 73 20 61 72 65 20 63 61 6c 6c 65 64 20 77 69 74  s are called wit
247e0 68 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  h a NULL pointer
247f0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 5b 70 72 65  .** for the [pre
24800 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
24810 20 6f 72 20 77 69 74 68 20 61 20 70 72 65 70 61   or with a prepa
24820 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 66 6f  red statement fo
24830 72 20 77 68 69 63 68 0a 2a 2a 20 5b 73 71 6c 69  r which.** [sqli
24840 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
24850 62 65 65 6e 20 63 61 6c 6c 65 64 20 6d 6f 72 65  been called more
24860 20 72 65 63 65 6e 74 6c 79 20 74 68 61 6e 20 5b   recently than [
24870 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
24880 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 61  ,.** then the ca
24890 6c 6c 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ll will return [
248a0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 2e 20  SQLITE_MISUSE]. 
248b0 20 49 66 20 61 6e 79 20 73 71 6c 69 74 65 33 5f   If any sqlite3_
248c0 62 69 6e 64 5f 28 29 0a 2a 2a 20 72 6f 75 74 69  bind_().** routi
248d0 6e 65 20 69 73 20 70 61 73 73 65 64 20 61 20 5b  ne is passed a [
248e0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
248f0 6e 74 5d 20 74 68 61 74 20 68 61 73 20 62 65 65  nt] that has bee
24900 6e 20 66 69 6e 61 6c 69 7a 65 64 2c 20 74 68 65  n finalized, the
24910 0a 2a 2a 20 72 65 73 75 6c 74 20 69 73 20 75 6e  .** result is un
24920 64 65 66 69 6e 65 64 20 61 6e 64 20 70 72 6f 62  defined and prob
24930 61 62 6c 79 20 68 61 72 6d 66 75 6c 2e 0a 2a 2a  ably harmful..**
24940 0a 2a 2a 20 5e 42 69 6e 64 69 6e 67 73 20 61 72  .** ^Bindings ar
24950 65 20 6e 6f 74 20 63 6c 65 61 72 65 64 20 62 79  e not cleared by
24960 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 72 65   the [sqlite3_re
24970 73 65 74 28 29 5d 20 72 6f 75 74 69 6e 65 2e 0a  set()] routine..
24980 2a 2a 20 5e 55 6e 62 6f 75 6e 64 20 70 61 72 61  ** ^Unbound para
24990 6d 65 74 65 72 73 20 61 72 65 20 69 6e 74 65 72  meters are inter
249a0 70 72 65 74 65 64 20 61 73 20 4e 55 4c 4c 2e 0a  preted as NULL..
249b0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
249c0 65 33 5f 62 69 6e 64 5f 2a 20 72 6f 75 74 69 6e  e3_bind_* routin
249d0 65 73 20 72 65 74 75 72 6e 20 5b 53 51 4c 49 54  es return [SQLIT
249e0 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73 73  E_OK] on success
249f0 20 6f 72 20 61 6e 0a 2a 2a 20 5b 65 72 72 6f 72   or an.** [error
24a00 20 63 6f 64 65 5d 20 69 66 20 61 6e 79 74 68 69   code] if anythi
24a10 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
24a20 2a 20 5e 5b 53 51 4c 49 54 45 5f 52 41 4e 47 45  * ^[SQLITE_RANGE
24a30 5d 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66  ] is returned if
24a40 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a   the parameter.*
24a50 2a 20 69 6e 64 65 78 20 69 73 20 6f 75 74 20 6f  * index is out o
24a60 66 20 72 61 6e 67 65 2e 20 20 5e 5b 53 51 4c 49  f range.  ^[SQLI
24a70 54 45 5f 4e 4f 4d 45 4d 5d 20 69 73 20 72 65 74  TE_NOMEM] is ret
24a80 75 72 6e 65 64 20 69 66 20 6d 61 6c 6c 6f 63 28  urned if malloc(
24a90 29 20 66 61 69 6c 73 2e 0a 2a 2a 0a 2a 2a 20 53  ) fails..**.** S
24aa0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
24ab0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
24ac0 5f 63 6f 75 6e 74 28 29 5d 2c 0a 2a 2a 20 5b 73  _count()],.** [s
24ad0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
24ae0 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c 20 61  meter_name()], a
24af0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  nd [sqlite3_bind
24b00 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
24b10 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ()]..*/.int sqli
24b20 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 73 71  te3_bind_blob(sq
24b30 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
24b40 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
24b50 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
24b60 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
24b70 65 33 5f 62 69 6e 64 5f 64 6f 75 62 6c 65 28 73  e3_bind_double(s
24b80 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
24b90 74 2c 20 64 6f 75 62 6c 65 29 3b 0a 69 6e 74 20  t, double);.int 
24ba0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74  sqlite3_bind_int
24bb0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24bc0 69 6e 74 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73  int, int);.int s
24bd0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 69 6e 74 36  qlite3_bind_int6
24be0 34 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  4(sqlite3_stmt*,
24bf0 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e   int, sqlite3_in
24c00 74 36 34 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  t64);.int sqlite
24c10 33 5f 62 69 6e 64 5f 6e 75 6c 6c 28 73 71 6c 69  3_bind_null(sqli
24c20 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 29 3b  te3_stmt*, int);
24c30 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24c40 64 5f 74 65 78 74 28 73 71 6c 69 74 65 33 5f 73  d_text(sqlite3_s
24c50 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74  tmt*, int, const
24c60 20 63 68 61 72 2a 2c 20 69 6e 74 20 6e 2c 20 76   char*, int n, v
24c70 6f 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a  oid(*)(void*));.
24c80 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
24c90 5f 74 65 78 74 31 36 28 73 71 6c 69 74 65 33 5f  _text16(sqlite3_
24ca0 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73  stmt*, int, cons
24cb0 74 20 76 6f 69 64 2a 2c 20 69 6e 74 2c 20 76 6f  t void*, int, vo
24cc0 69 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69  id(*)(void*));.i
24cd0 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
24ce0 76 61 6c 75 65 28 73 71 6c 69 74 65 33 5f 73 74  value(sqlite3_st
24cf0 6d 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20  mt*, int, const 
24d00 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
24d10 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24d20 64 5f 7a 65 72 6f 62 6c 6f 62 28 73 71 6c 69 74  d_zeroblob(sqlit
24d30 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69  e3_stmt*, int, i
24d40 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  nt n);../*.** CA
24d50 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f  PI3REF: Number O
24d60 66 20 53 51 4c 20 50 61 72 61 6d 65 74 65 72 73  f SQL Parameters
24d70 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75  .**.** ^This rou
24d80 74 69 6e 65 20 63 61 6e 20 62 65 20 75 73 65 64  tine can be used
24d90 20 74 6f 20 66 69 6e 64 20 74 68 65 20 6e 75 6d   to find the num
24da0 62 65 72 20 6f 66 20 5b 53 51 4c 20 70 61 72 61  ber of [SQL para
24db0 6d 65 74 65 72 73 5d 0a 2a 2a 20 69 6e 20 61 20  meters].** in a 
24dc0 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
24dd0 65 6e 74 5d 2e 20 20 53 51 4c 20 70 61 72 61 6d  ent].  SQL param
24de0 65 74 65 72 73 20 61 72 65 20 74 6f 6b 65 6e 73  eters are tokens
24df0 20 6f 66 20 74 68 65 0a 2a 2a 20 66 6f 72 6d 20   of the.** form 
24e00 22 3f 22 2c 20 22 3f 4e 4e 4e 22 2c 20 22 3a 41  "?", "?NNN", ":A
24e10 41 41 22 2c 20 22 24 41 41 41 22 2c 20 6f 72 20  AA", "$AAA", or 
24e20 22 40 41 41 41 22 20 74 68 61 74 20 73 65 72 76  "@AAA" that serv
24e30 65 20 61 73 0a 2a 2a 20 70 6c 61 63 65 68 6f 6c  e as.** placehol
24e40 64 65 72 73 20 66 6f 72 20 76 61 6c 75 65 73 20  ders for values 
24e50 74 68 61 74 20 61 72 65 20 5b 73 71 6c 69 74 65  that are [sqlite
24e60 33 5f 62 69 6e 64 5f 62 6c 6f 62 20 7c 20 62 6f  3_bind_blob | bo
24e70 75 6e 64 5d 0a 2a 2a 20 74 6f 20 74 68 65 20 70  und].** to the p
24e80 61 72 61 6d 65 74 65 72 73 20 61 74 20 61 20 6c  arameters at a l
24e90 61 74 65 72 20 74 69 6d 65 2e 0a 2a 2a 0a 2a 2a  ater time..**.**
24ea0 20 5e 28 54 68 69 73 20 72 6f 75 74 69 6e 65 20   ^(This routine 
24eb0 61 63 74 75 61 6c 6c 79 20 72 65 74 75 72 6e 73  actually returns
24ec0 20 74 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68   the index of th
24ed0 65 20 6c 61 72 67 65 73 74 20 28 72 69 67 68 74  e largest (right
24ee0 6d 6f 73 74 29 0a 2a 2a 20 70 61 72 61 6d 65 74  most).** paramet
24ef0 65 72 2e 20 46 6f 72 20 61 6c 6c 20 66 6f 72 6d  er. For all form
24f00 73 20 65 78 63 65 70 74 20 3f 4e 4e 4e 2c 20 74  s except ?NNN, t
24f10 68 69 73 20 77 69 6c 6c 20 63 6f 72 72 65 73 70  his will corresp
24f20 6f 6e 64 20 74 6f 20 74 68 65 0a 2a 2a 20 6e 75  ond to the.** nu
24f30 6d 62 65 72 20 6f 66 20 75 6e 69 71 75 65 20 70  mber of unique p
24f40 61 72 61 6d 65 74 65 72 73 2e 20 20 49 66 20 70  arameters.  If p
24f50 61 72 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65  arameters of the
24f60 20 3f 4e 4e 4e 20 66 6f 72 6d 20 61 72 65 20 75   ?NNN form are u
24f70 73 65 64 2c 0a 2a 2a 20 74 68 65 72 65 20 6d 61  sed,.** there ma
24f80 79 20 62 65 20 67 61 70 73 20 69 6e 20 74 68 65  y be gaps in the
24f90 20 6c 69 73 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 53   list.)^.**.** S
24fa0 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65  ee also: [sqlite
24fb0 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69  3_bind_blob|sqli
24fc0 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20  te3_bind()],.** 
24fd0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
24fe0 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 29 5d 2c  rameter_name()],
24ff0 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
25000 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
25010 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69 6e 74  index()]..*/.int
25020 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61   sqlite3_bind_pa
25030 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 73 71  rameter_count(sq
25040 6c 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f  lite3_stmt*);../
25050 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
25060 61 6d 65 20 4f 66 20 41 20 48 6f 73 74 20 50 61  ame Of A Host Pa
25070 72 61 6d 65 74 65 72 0a 2a 2a 0a 2a 2a 20 5e 54  rameter.**.** ^T
25080 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  he sqlite3_bind_
25090 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d 65 28 50  parameter_name(P
250a0 2c 4e 29 20 69 6e 74 65 72 66 61 63 65 20 72 65  ,N) interface re
250b0 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e 61 6d  turns.** the nam
250c0 65 20 6f 66 20 74 68 65 20 4e 2d 74 68 20 5b 53  e of the N-th [S
250d0 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 69 6e  QL parameter] in
250e0 20 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73   the [prepared s
250f0 74 61 74 65 6d 65 6e 74 5d 20 50 2e 0a 2a 2a 20  tatement] P..** 
25100 5e 28 53 51 4c 20 70 61 72 61 6d 65 74 65 72 73  ^(SQL parameters
25110 20 6f 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 4e   of the form "?N
25120 4e 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72  NN" or ":AAA" or
25130 20 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41   "@AAA" or "$AAA
25140 22 0a 2a 2a 20 68 61 76 65 20 61 20 6e 61 6d 65  ".** have a name
25150 20 77 68 69 63 68 20 69 73 20 74 68 65 20 73 74   which is the st
25160 72 69 6e 67 20 22 3f 4e 4e 4e 22 20 6f 72 20 22  ring "?NNN" or "
25170 3a 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20  :AAA" or "@AAA" 
25180 6f 72 20 22 24 41 41 41 22 0a 2a 2a 20 72 65 73  or "$AAA".** res
25190 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20 49 6e  pectively..** In
251a0 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
251b0 65 20 69 6e 69 74 69 61 6c 20 22 3a 22 20 6f 72  e initial ":" or
251c0 20 22 24 22 20 6f 72 20 22 40 22 20 6f 72 20 22   "$" or "@" or "
251d0 3f 22 0a 2a 2a 20 69 73 20 69 6e 63 6c 75 64 65  ?".** is include
251e0 64 20 61 73 20 70 61 72 74 20 6f 66 20 74 68 65  d as part of the
251f0 20 6e 61 6d 65 2e 29 5e 0a 2a 2a 20 5e 50 61 72   name.)^.** ^Par
25200 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
25210 6f 72 6d 20 22 3f 22 20 77 69 74 68 6f 75 74 20  orm "?" without 
25220 61 20 66 6f 6c 6c 6f 77 69 6e 67 20 69 6e 74 65  a following inte
25230 67 65 72 20 68 61 76 65 20 6e 6f 20 6e 61 6d 65  ger have no name
25240 0a 2a 2a 20 61 6e 64 20 61 72 65 20 72 65 66 65  .** and are refe
25250 72 72 65 64 20 74 6f 20 61 73 20 22 6e 61 6d 65  rred to as "name
25260 6c 65 73 73 22 20 6f 72 20 22 61 6e 6f 6e 79 6d  less" or "anonym
25270 6f 75 73 20 70 61 72 61 6d 65 74 65 72 73 22 2e  ous parameters".
25280 0a 2a 2a 20 5e 41 6e 79 20 70 61 72 61 6d 65 74  .** ^Any paramet
25290 65 72 20 74 68 61 74 20 69 73 20 6f 70 74 69 6d  er that is optim
252a0 69 7a 65 64 20 6f 75 74 20 6f 66 20 74 68 65 20  ized out of the 
252b0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
252c0 6e 74 20 62 79 20 74 68 65 20 0a 2a 2a 20 71 75  nt by the .** qu
252d0 65 72 79 20 70 6c 61 6e 6e 65 72 20 62 65 63 6f  ery planner beco
252e0 6d 65 73 20 61 20 6e 61 6d 65 6c 65 73 73 20 6f  mes a nameless o
252f0 72 20 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61  r anonymous para
25300 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  meter..**.** ^Th
25310 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61 72  e first host par
25320 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69 6e  ameter has an in
25330 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30 2e  dex of 1, not 0.
25340 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 76  .**.** ^If the v
25350 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f 66  alue N is out of
25360 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68 65   range or if the
25370 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72 20   N-th parameter 
25380 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c 20  is.** nameless, 
25390 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65 74  then NULL is ret
253a0 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65 74  urned.  ^The ret
253b0 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73 0a  urned string is.
253c0 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54 46  ** always in UTF
253d0 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65 6e  -8 encoding even
253e0 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70 61   if the named pa
253f0 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20 6f  rameter was.** o
25400 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69 66  riginally specif
25410 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  ied as UTF-16 in
25420 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25430 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  e16()] or.** [sq
25440 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 5f  lite3_prepare16_
25450 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65 65  v2()]..**.** See
25460 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f   also: [sqlite3_
25470 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74 65  bind_blob|sqlite
25480 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b 73  3_bind()],.** [s
25490 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61  qlite3_bind_para
254a0 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c 20  meter_count()], 
254b0 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
254c0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 69  bind_parameter_i
254d0 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e 73  ndex()]..*/.cons
254e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
254f0 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
25500 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
25510 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  *, int);../*.** 
25520 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78 20  CAPI3REF: Index 
25530 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20 57  Of A Parameter W
25540 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d 65  ith A Given Name
25550 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20 74  .**.** ^Return t
25560 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20 53  he index of an S
25570 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69 76  QL parameter giv
25580 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e 54  en its name.  ^T
25590 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c 75  he.** index valu
255a0 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73 75  e returned is su
255b0 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20 61  itable for use a
255c0 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
255d0 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73 71  parameter to [sq
255e0 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
255f0 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2e  sqlite3_bind()].
25600 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73 20    ^A zero.** is 
25610 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20 6d  returned if no m
25620 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74 65  atching paramete
25630 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54 68  r is found.  ^Th
25640 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20 6e  e parameter.** n
25650 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76 65  ame must be give
25660 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e 20  n in UTF-8 even 
25670 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  if the original 
25680 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61 73  statement.** was
25690 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20 55   prepared from U
256a0 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e 67  TF-16 text using
256b0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
256c0 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a  e16_v2()]..**.**
256d0 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
256e0 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71  te3_bind_blob|sq
256f0 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a  lite3_bind()],.*
25700 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  * [sqlite3_bind_
25710 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28  parameter_count(
25720 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69  )], and.** [sqli
25730 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74  te3_bind_paramet
25740 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a  er_index()]..*/.
25750 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64  int sqlite3_bind
25760 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65 78  _parameter_index
25770 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
25780 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d  const char *zNam
25790 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  e);../*.** CAPI3
257a0 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20 42  REF: Reset All B
257b0 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72 65  indings On A Pre
257c0 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
257d0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79 20  **.** ^Contrary 
257e0 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f 6e  to the intuition
257f0 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69 74   of many, [sqlit
25800 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65 73  e3_reset()] does
25810 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74 68   not reset.** th
25820 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  e [sqlite3_bind_
25830 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73 5d  blob | bindings]
25840 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64 20   on a [prepared 
25850 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20 5e  statement]..** ^
25860 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  Use this routine
25870 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68 6f   to reset all ho
25880 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f  st parameters to
25890 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73 71   NULL..*/.int sq
258a0 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e 64  lite3_clear_bind
258b0 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ings(sqlite3_stm
258c0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
258d0 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66 20  3REF: Number Of 
258e0 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65 73  Columns In A Res
258f0 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e 52  ult Set.**.** ^R
25900 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65 72  eturn the number
25910 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 74   of columns in t
25920 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72 65  he result set re
25930 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a 2a  turned by the.**
25940 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25950 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f 75  ment]. ^This rou
25960 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20 69  tine returns 0 i
25970 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53 51  f pStmt is an SQ
25980 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 74  L.** statement t
25990 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65 74  hat does not ret
259a0 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65 78  urn data (for ex
259b0 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54 45  ample an [UPDATE
259c0 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c  ])..**.** See al
259d0 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61 74  so: [sqlite3_dat
259e0 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69 6e  a_count()].*/.in
259f0 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
25a00 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73  _count(sqlite3_s
25a10 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f 2a  tmt *pStmt);../*
25a20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f  .** CAPI3REF: Co
25a30 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41 20  lumn Names In A 
25a40 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a  Result Set.**.**
25a50 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73   ^These routines
25a60 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d 65   return the name
25a70 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20 70   assigned to a p
25a80 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d 6e  articular column
25a90 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75 6c  .** in the resul
25aa0 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c 45  t set of a [SELE
25ab0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20 20  CT] statement.  
25ac0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c  ^The sqlite3_col
25ad0 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69 6e  umn_name().** in
25ae0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
25af0 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20 7a  a pointer to a z
25b00 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55  ero-terminated U
25b10 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20 61  TF-8 string.** a
25b20 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nd sqlite3_colum
25b30 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75 72  n_name16() retur
25b40 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20  ns a pointer to 
25b50 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
25b60 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
25b70 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74 20  ng.  ^The first 
25b80 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
25b90 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
25ba0 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69 6d  ment].** that im
25bb0 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53 45  plements the [SE
25bc0 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e  LECT] statement.
25bd0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
25be0 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a 2a  ameter is the.**
25bf0 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 20   column number. 
25c00 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
25c10 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72 20  olumn is number 
25c20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72 65  0..**.** ^The re
25c30 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70 6f  turned string po
25c40 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20 75  inter is valid u
25c50 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65 20  ntil either the 
25c60 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25c70 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74 72  ent].** is destr
25c80 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33  oyed by [sqlite3
25c90 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72 20  _finalize()] or 
25ca0 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65 6d  until the statem
25cb0 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69 63  ent is automatic
25cc0 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61 72  ally.** reprepar
25cd0 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74 20  ed by the first 
25ce0 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
25cf0 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20 70  _step()] for a p
25d00 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a 2a  articular run.**
25d10 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e 65   or until the ne
25d20 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73 71  xt call to.** sq
25d30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d  lite3_column_nam
25d40 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 63  e() or sqlite3_c
25d50 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 6f  olumn_name16() o
25d60 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75 6d  n the same colum
25d70 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71 6c  n..**.** ^If sql
25d80 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66 61  ite3_malloc() fa
25d90 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20 70  ils during the p
25da0 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69 74  rocessing of eit
25db0 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20 28  her routine.** (
25dc0 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72 69  for example duri
25dd0 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e 20  ng a conversion 
25de0 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55 54  from UTF-8 to UT
25df0 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a 20  F-16) then a.** 
25e00 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
25e10 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
25e20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20 72  ^The name of a r
25e30 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73 20  esult column is 
25e40 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
25e50 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f 72   "AS" clause for
25e60 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e 2c  .** that column,
25e70 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e 20   if there is an 
25e80 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20 74  AS clause.  If t
25e90 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63 6c  here is no AS cl
25ea0 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ause.** then the
25eb0 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c   name of the col
25ec0 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66 69  umn is unspecifi
25ed0 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e 67  ed and may chang
25ee0 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72 65  e from.** one re
25ef0 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65 20  lease of SQLite 
25f00 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f 0a  to the next..*/.
25f10 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c 69  const char *sqli
25f20 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 28  te3_column_name(
25f30 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
25f40 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  nt N);.const voi
25f50 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
25f60 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  n_name16(sqlite3
25f70 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a  _stmt*, int N);.
25f80 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
25f90 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61 20   Source Of Data 
25fa0 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75 6c  In A Query Resul
25fb0 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  t.**.** ^These r
25fc0 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65 20  outines provide 
25fd0 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65 72  a means to deter
25fe0 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61 73  mine the databas
25ff0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a 2a  e, table, and.**
26000 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74 68   table column th
26010 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69 6e  at is the origin
26020 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61 72   of a particular
26030 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69   result column i
26040 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73 74  n.** [SELECT] st
26050 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  atement..** ^The
26060 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
26070 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20 6f  abase or table o
26080 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65 20  r column can be 
26090 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20 65  returned as.** e
260a0 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f 72  ither a UTF-8 or
260b0 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e 20   UTF-16 string. 
260c0 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65 5f   ^The _database_
260d0 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
260e0 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
260f0 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62 6c   name, the _tabl
26100 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75  e_ routines retu
26110 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61 6d  rn the table nam
26120 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f 72  e, and.** the or
26130 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20 72  igin_ routines r
26140 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d 6e  eturn the column
26150 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20 72   name..** ^The r
26160 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69  eturned string i
26170 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74 68  s valid until th
26180 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
26190 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72 6f  ement] is destro
261a0 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  yed.** using [sq
261b0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
261c0 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 73  ] or until the s
261d0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74 6f  tatement is auto
261e0 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65 70  matically.** rep
261f0 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20 66  repared by the f
26200 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71  irst call to [sq
26210 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66 6f  lite3_step()] fo
26220 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20 72  r a particular r
26230 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20 74  un.** or until t
26240 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61 74  he same informat
26250 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65 64  ion is requested
26260 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20 64  .** again in a d
26270 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69 6e  ifferent encodin
26280 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e 61  g..**.** ^The na
26290 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72 65  mes returned are
262a0 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75 6e   the original un
262b0 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20 6f  -aliased names o
262c0 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73  f the.** databas
262d0 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63 6f  e, table, and co
262e0 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  lumn..**.** ^The
262f0 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20   first argument 
26300 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  to these interfa
26310 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61 72  ces is a [prepar
26320 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
26330 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f  * ^These functio
26340 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72 6d  ns return inform
26350 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65 20  ation about the 
26360 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d  Nth result colum
26370 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a 2a  n returned by.**
26380 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c 20   the statement, 
26390 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20 73  where N is the s
263a0 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20 61  econd function a
263b0 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68 65  rgument..** ^The
263c0 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75 6d   left-most colum
263d0 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66 6f  n is column 0 fo
263e0 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  r these routines
263f0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
26400 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75 72  Nth column retur
26410 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74 65  ned by the state
26420 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72 65  ment is an expre
26430 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62 71  ssion or.** subq
26440 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74 20  uery and is not 
26450 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c 20  a column value, 
26460 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65 73  then all of thes
26470 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74 75  e functions retu
26480 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54 68  rn.** NULL.  ^Th
26490 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67 68  ese routine migh
264a0 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e 55  t also return NU
264b0 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20 61  LL if a memory a
264c0 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72 0a  llocation error.
264d0 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74 68  ** occurs.  ^Oth
264e0 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65 74  erwise, they ret
264f0 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66 20  urn the name of 
26500 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61 74  the attached dat
26510 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a 2a  abase, table,.**
26520 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74 20   or column that 
26530 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f 6c  query result col
26540 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74 65  umn was extracte
26550 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 41  d from..**.** ^A
26560 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65 72  s with all other
26570 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74 68   SQLite APIs, th
26580 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73 20  ose whose names 
26590 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72 65  end with "16" re
265a0 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20 65  turn.** UTF-16 e
265b0 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20 61  ncoded strings a
265c0 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75 6e  nd the other fun
265d0 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55 54  ctions return UT
265e0 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73  F-8..**.** ^Thes
265f0 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79 20  e APIs are only 
26600 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68 65  available if the
26610 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f 6d   library was com
26620 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a 2a  piled with the.*
26630 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  * [SQLITE_ENABLE
26640 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54 41  _COLUMN_METADATA
26650 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f 72  ] C-preprocessor
26660 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20 49   symbol..**.** I
26670 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74 68  f two or more th
26680 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20 6f  reads call one o
26690 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65 20  r more of these 
266a0 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73 74  routines against
266b0 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72 65   the same.** pre
266c0 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
266d0 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74 68  and column at th
266e0 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65 6e  e same time then
266f0 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72 65   the results are
26700 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  .** undefined..*
26710 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20 6d  *.** If two or m
26720 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c 6c  ore threads call
26730 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20   one or more.** 
26740 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  [sqlite3_column_
26750 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c 20  database_name | 
26760 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61 20  column metadata 
26770 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20 66  interfaces].** f
26780 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72 65  or the same [pre
26790 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
267a0 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c 75   and result colu
267b0 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61 6d  mn.** at the sam
267c0 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65 20  e time then the 
267d0 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65  results are unde
267e0 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  fined..*/.const 
267f0 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f  char *sqlite3_co
26800 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61  lumn_database_na
26810 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26820 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
26830 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
26840 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 31  n_database_name1
26850 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
26860 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61 72  int);.const char
26870 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   *sqlite3_column
26880 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c 69  _table_name(sqli
26890 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a  te3_stmt*,int);.
268a0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
268b0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c 65  te3_column_table
268c0 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33 5f  _name16(sqlite3_
268d0 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
268e0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
268f0 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61  column_origin_na
26900 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  me(sqlite3_stmt*
26910 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f 69  ,int);.const voi
26920 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  d *sqlite3_colum
26930 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36 28  n_origin_name16(
26940 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e  sqlite3_stmt*,in
26950 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
26960 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44 61  REF: Declared Da
26970 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65 72  tatype Of A Quer
26980 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20 5e  y Result.**.** ^
26990 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d  (The first param
269a0 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70 61  eter is a [prepa
269b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
269c0 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74 65  ** If this state
269d0 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45 43  ment is a [SELEC
269e0 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e 64  T] statement and
269f0 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e 20   the Nth column 
26a00 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72 6e  of the.** return
26a10 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66  ed result set of
26a20 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20 69   that [SELECT] i
26a30 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e  s a table column
26a40 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70 72   (not an.** expr
26a50 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75 65  ession or subque
26a60 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65 63  ry) then the dec
26a70 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74 68  lared type of th
26a80 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75 6d  e table.** colum
26a90 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29 5e  n is returned.)^
26aa0 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63 6f    ^If the Nth co
26ab0 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73 75  lumn of the resu
26ac0 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a 20  lt set is an.** 
26ad0 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73 75  expression or su
26ae0 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20 4e  bquery, then a N
26af0 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20 72  ULL pointer is r
26b00 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68 65  eturned..** ^The
26b10 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67   returned string
26b20 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d 38   is always UTF-8
26b30 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a 20   encoded..**.** 
26b40 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 67  ^(For example, g
26b50 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61 73  iven the databas
26b60 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a 20  e schema:.**.** 
26b70 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31 28  CREATE TABLE t1(
26b80 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a 0a  c1 VARIANT);.**.
26b90 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c 6f  ** and the follo
26ba0 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 74  wing statement t
26bb0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a 2a  o be compiled:.*
26bc0 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20 2b  *.** SELECT c1 +
26bd0 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b 0a   1, c1 FROM t1;.
26be0 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  **.** this routi
26bf0 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e 20  ne would return 
26c00 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52 49  the string "VARI
26c10 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65 63  ANT" for the sec
26c20 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63 6f  ond result.** co
26c30 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e 64  lumn (i==1), and
26c40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
26c50 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72 65  for the first re
26c60 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d 3d  sult column (i==
26c70 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c  0).)^.**.** ^SQL
26c80 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69 63  ite uses dynamic
26c90 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e 67   run-time typing
26ca0 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63 61  .  ^So just beca
26cb0 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a 20  use a column.** 
26cc0 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20 63  is declared to c
26cd0 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63 75  ontain a particu
26ce0 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e 6f  lar type does no
26cf0 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65 0a  t mean that the.
26d00 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20 69  ** data stored i
26d10 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69 73  n that column is
26d20 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65 64   of the declared
26d30 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20 69   type.  SQLite i
26d40 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74 79  s.** strongly ty
26d50 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79 70  ped, but the typ
26d60 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20 6e  ing is dynamic n
26d70 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79 70  ot static.  ^Typ
26d80 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61 74  e.** is associat
26d90 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64 75  ed with individu
26da0 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20 77  al values, not w
26db0 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e 65  ith the containe
26dc0 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68 6f  rs.** used to ho
26dd0 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73 2e  ld those values.
26de0 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a  .*/.const char *
26df0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 64  sqlite3_column_d
26e00 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33 5f  ecltype(sqlite3_
26e10 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73  stmt*,int);.cons
26e20 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
26e30 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65 31  column_decltype1
26e40 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  6(sqlite3_stmt*,
26e50 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  int);../*.** CAP
26e60 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65 20  I3REF: Evaluate 
26e70 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74  An SQL Statement
26e80 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20 5b  .**.** After a [
26e90 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
26ea0 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72 65  nt] has been pre
26eb0 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74 68  pared using eith
26ec0 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70  er.** [sqlite3_p
26ed0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72 20  repare_v2()] or 
26ee0 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
26ef0 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20  16_v2()] or one 
26f00 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a 2a  of the legacy.**
26f10 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71 6c   interfaces [sql
26f20 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
26f30 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
26f40 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20 66  are16()], this f
26f50 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74 20  unction.** must 
26f60 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f 72  be called one or
26f70 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20 65   more times to e
26f80 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61 74  valuate the stat
26f90 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ement..**.** The
26fa0 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65 20   details of the 
26fb0 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65 20  behavior of the 
26fc0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20 69  sqlite3_step() i
26fd0 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64 0a  nterface depend.
26fe0 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74 68  ** on whether th
26ff0 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73 20  e statement was 
27000 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20 74  prepared using t
27010 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69 6e  he newer "v2" in
27020 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c 69  terface.** [sqli
27030 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29  te3_prepare_v2()
27040 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70  ] and [sqlite3_p
27050 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20 6f  repare16_v2()] o
27060 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67 61  r the older lega
27070 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  cy.** interface 
27080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27090 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
270a0 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20 20  _prepare16()].  
270b0 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a 2a  The use of the.*
270c0 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65 72  * new "v2" inter
270d0 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e  face is recommen
270e0 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70 6c  ded for new appl
270f0 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68 65  ications but the
27100 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65 72   legacy.** inter
27110 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69 6e  face will contin
27120 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72 74  ue to be support
27130 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74 68  ed..**.** ^In th
27140 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66 61  e legacy interfa
27150 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20 76  ce, the return v
27160 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69 74  alue will be eit
27170 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53 59  her [SQLITE_BUSY
27180 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44 4f  ],.** [SQLITE_DO
27190 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f 57  NE], [SQLITE_ROW
271a0 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ], [SQLITE_ERROR
271b0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d 49  ], or [SQLITE_MI
271c0 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68 20  SUSE]..** ^With 
271d0 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
271e0 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20 6f  ce, any of the o
271f0 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f 64  ther [result cod
27200 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e  es] or.** [exten
27210 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65 73  ded result codes
27220 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75 72  ] might be retur
27230 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a 0a  ned as well..**.
27240 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53 59  ** ^[SQLITE_BUSY
27250 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65  ] means that the
27260 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e 65   database engine
27270 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20 61   was unable to a
27280 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64 61  cquire the.** da
27290 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74 20  tabase locks it 
272a0 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73 20  needs to do its 
272b0 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73 74  job.  ^If the st
272c0 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43 4f  atement is a [CO
272d0 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63 75  MMIT].** or occu
272e0 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61 6e  rs outside of an
272f0 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73 61   explicit transa
27300 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75 20  ction, then you 
27310 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a 2a  can retry the.**
27320 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66 20   statement.  If 
27330 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73  the statement is
27340 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d 20   not a [COMMIT] 
27350 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68 69  and occurs withi
27360 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74 20  n a.** explicit 
27370 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65 6e  transaction then
27380 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c 6c   you should roll
27390 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61 63  back the transac
273a0 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20 63  tion before.** c
273b0 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ontinuing..**.**
273c0 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 20   ^[SQLITE_DONE] 
273d0 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20 73  means that the s
273e0 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69 6e  tatement has fin
273f0 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67 0a  ished executing.
27400 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79 2e  ** successfully.
27410 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29    sqlite3_step()
27420 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20 63   should not be c
27430 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20 74  alled again on t
27440 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20 6d  his virtual.** m
27450 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20 66  achine without f
27460 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73 71  irst calling [sq
27470 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 74  lite3_reset()] t
27480 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72 74  o reset the virt
27490 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20 62  ual.** machine b
274a0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
274b0 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a 20  al state..**.** 
274c0 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61 74  ^If the SQL stat
274d0 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65 63  ement being exec
274e0 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e 79  uted returns any
274f0 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51 4c   data, then [SQL
27500 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20 72  ITE_ROW].** is r
27510 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69 6d  eturned each tim
27520 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20 64  e a new row of d
27530 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f 72  ata is ready for
27540 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20 74   processing by t
27550 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54 68  he.** caller. Th
27560 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65 20  e values may be 
27570 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20 74  accessed using t
27580 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65 73  he [column acces
27590 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a  s functions]..**
275a0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
275b0 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e 20  is called again 
275c0 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65 20  to retrieve the 
275d0 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74 61  next row of data
275e0 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45  ..**.** ^[SQLITE
275f0 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74 68  _ERROR] means th
27600 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65 72  at a run-time er
27610 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20 63  ror (such as a c
27620 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69 6f  onstraint.** vio
27630 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63 75  lation) has occu
27640 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f 73  rred.  sqlite3_s
27650 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f 74  tep() should not
27660 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   be called again
27670 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20 4d   on.** the VM. M
27680 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20  ore information 
27690 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79 20  may be found by 
276a0 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65 33  calling [sqlite3
276b0 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20 5e  _errmsg()]..** ^
276c0 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79 20  With the legacy 
276d0 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f 72  interface, a mor
276e0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
276f0 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d 70   code (for examp
27700 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  le,.** [SQLITE_I
27710 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c 49  NTERRUPT], [SQLI
27720 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51 4c  TE_SCHEMA], [SQL
27730 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61 6e  ITE_CORRUPT], an
27740 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20 63  d so forth).** c
27750 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20 62  an be obtained b
27760 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
27770 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20 74  e3_reset()] on t
27780 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20  he.** [prepared 
27790 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49 6e  statement].  ^In
277a0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
277b0 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72 65  ace,.** the more
277c0 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72 20   specific error 
277d0 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65 64  code is returned
277e0 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71 6c   directly by sql
277f0 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a 0a  ite3_step()..**.
27800 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53  ** [SQLITE_MISUS
27810 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  E] means that th
27820 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 77  e this routine w
27830 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70 72  as called inappr
27840 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50 65  opriately..** Pe
27850 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61 6c  rhaps it was cal
27860 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61 72  led on a [prepar
27870 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74 68  ed statement] th
27880 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61 64  at has.** alread
27890 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33 5f  y been [sqlite3_
278a0 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61 6c  finalize | final
278b0 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65 20  ized] or on one 
278c0 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65 76  that had.** prev
278d0 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64 20  iously returned 
278e0 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20 6f  [SQLITE_ERROR] o
278f0 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d 2e  r [SQLITE_DONE].
27900 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a 2a    Or it could.**
27910 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68 61   be the case tha
27920 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62  t the same datab
27930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
27940 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79 20  s being used by 
27950 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20 74  two or.** more t
27960 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73 61  hreads at the sa
27970 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69 6d  me moment in tim
27980 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c 6c  e..**.** For all
27990 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
279a0 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69 6e  ite up to and in
279b0 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e 31  cluding 3.6.23.1
279c0 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b  , a call to.** [
279d0 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d  sqlite3_reset()]
279e0 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61 66   was required af
279f0 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65 70  ter sqlite3_step
27a00 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79 74  () returned anyt
27a10 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74 68  hing.** other th
27a20 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20  an [SQLITE_ROW] 
27a30 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73 65  before any subse
27a40 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f 6e  quent invocation
27a50 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73   of.** sqlite3_s
27a60 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65 20  tep().  Failure 
27a70 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72 65  to reset the pre
27a80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
27a90 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69 74  using .** [sqlit
27aa0 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75 6c  e3_reset()] woul
27ab0 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20 5b  d result in an [
27ac0 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20 72  SQLITE_MISUSE] r
27ad0 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73 71  eturn from.** sq
27ae0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20 42  lite3_step().  B
27af0 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f 6e  ut after version
27b00 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69 74   3.6.23.1, sqlit
27b10 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e 0a  e3_step() began.
27b20 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  ** calling [sqli
27b30 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75 74  te3_reset()] aut
27b40 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74 68  omatically in th
27b50 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65 20  is circumstance 
27b60 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20 72  rather.** than r
27b70 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54 45  eturning [SQLITE
27b80 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73 20  _MISUSE].  This 
27b90 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72 65  is not considere
27ba0 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  d a compatibilit
27bb0 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61 75  y.** break becau
27bc0 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74 69  se any applicati
27bd0 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65 63  on that ever rec
27be0 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45 5f  eives an SQLITE_
27bf0 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a 20  MISUSE error.** 
27c00 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65 66  is broken by def
27c10 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b 53  inition.  The [S
27c20 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f 52  QLITE_OMIT_AUTOR
27c30 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ESET] compile-ti
27c40 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61 6e  me option.** can
27c50 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73 74   be used to rest
27c60 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20 62  ore the legacy b
27c70 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20 3c  ehavior..**.** <
27c80 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61 63  b>Goofy Interfac
27c90 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e 20  e Alert:</b> In 
27ca0 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72  the legacy inter
27cb0 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74 65  face, the sqlite
27cc0 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49 20  3_step().** API 
27cd0 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20 61  always returns a
27ce0 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20 63   generic error c
27cf0 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52  ode, [SQLITE_ERR
27d00 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20 61  OR], following a
27d10 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68 65  ny.** error othe
27d20 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 42  r than [SQLITE_B
27d30 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45  USY] and [SQLITE
27d40 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20 6d  _MISUSE].  You m
27d50 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71 6c  ust call.** [sql
27d60 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 72  ite3_reset()] or
27d70 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69   [sqlite3_finali
27d80 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20 74  ze()] in order t
27d90 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74 68  o find one of th
27da0 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b 65  e.** specific [e
27db0 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61 74  rror codes] that
27dc0 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62 65   better describe
27dd0 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a 20  s the error..** 
27de0 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74 68  We admit that th
27df0 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64 65  is is a goofy de
27e00 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62 6c  sign.  The probl
27e10 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78 65  em has been fixe
27e20 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22 76  d.** with the "v
27e30 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20 49  2" interface.  I
27e40 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61 6c  f you prepare al
27e50 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73 74  l of your SQL st
27e60 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69 6e  atements.** usin
27e70 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74 65  g either [sqlite
27e80 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
27e90 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  or [sqlite3_prep
27ea0 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73 74  are16_v2()] inst
27eb0 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c 65  ead.** of the le
27ec0 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70 72  gacy [sqlite3_pr
27ed0 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73 71  epare()] and [sq
27ee0 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28  lite3_prepare16(
27ef0 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a 2a  )] interfaces,.*
27f00 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65 20  * then the more 
27f10 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72 20  specific [error 
27f20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75 72  codes] are retur
27f30 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a 20  ned directly.** 
27f40 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  by sqlite3_step(
27f50 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20 74  ).  The use of t
27f60 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61 63  he "v2" interfac
27f70 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  e is recommended
27f80 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ..*/.int sqlite3
27f90 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73 74  _step(sqlite3_st
27fa0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
27fb0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f 66  I3REF: Number of
27fc0 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72 65   columns in a re
27fd0 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult set.**.** ^
27fe0 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74 61  The sqlite3_data
27ff0 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72 66  _count(P) interf
28000 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65 20  ace returns the 
28010 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e  number of column
28020 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72 72  s in the.** curr
28030 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20 72  ent row of the r
28040 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70 72  esult set of [pr
28050 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
28060 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65 70  ] P..** ^If prep
28070 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 50  ared statement P
28080 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20 72   does not have r
28090 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f 20  esults ready to 
280a0 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20 63  return.** (via c
280b0 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71 6c  alls to the [sql
280c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 20  ite3_column_int 
280d0 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  | sqlite3_column
280e0 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74 65  _*()] of.** inte
280f0 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71 6c  rfaces) then sql
28100 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28  ite3_data_count(
28110 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a 2a  P) returns 0..**
28120 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61   ^The sqlite3_da
28130 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75 74  ta_count(P) rout
28140 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e 73  ine also returns
28150 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55 4c   0 if P is a NUL
28160 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a  L pointer..**.**
28170 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69   See also: [sqli
28180 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e 74  te3_column_count
28190 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ()].*/.int sqlit
281a0 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73 71  e3_data_count(sq
281b0 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
281c0 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
281d0 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61 6c  REF: Fundamental
281e0 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b 45   Datatypes.** KE
281f0 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f 54  YWORDS: SQLITE_T
28200 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65 72  EXT.**.** ^(Ever
28210 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69 74  y value in SQLit
28220 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69 76  e has one of fiv
28230 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64 61  e fundamental da
28240 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c  tatypes:.**.** <
28250 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62  ul>.** <li> 64-b
28260 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
28270 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69 74  r.** <li> 64-bit
28280 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20 70   IEEE floating p
28290 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20 3c  oint number.** <
282a0 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c 6c  li> string.** <l
282b0 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e 20  i> BLOB.** <li> 
282c0 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a  NULL.** </ul>)^.
282d0 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e 73  **.** These cons
282e0 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73 20  tants are codes 
282f0 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f 73  for each of thos
28300 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20 4e  e types..**.** N
28310 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51 4c  ote that the SQL
28320 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61 6e  ITE_TEXT constan
28330 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64 20  t was also used 
28340 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  in SQLite versio
28350 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f 6d  n 2.** for a com
28360 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65 6e  pletely differen
28370 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66 74  t meaning.  Soft
28380 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73 20  ware that links 
28390 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a 20  against both.** 
283a0 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20 32  SQLite version 2
283b0 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72 73   and SQLite vers
283c0 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73 65  ion 3 should use
283d0 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20 6e   SQLITE3_TEXT, n
283e0 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45 58  ot.** SQLITE_TEX
283f0 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  T..*/.#define SQ
28400 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31 0a  LITE_INTEGER  1.
28410 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 46  #define SQLITE_F
28420 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69 6e  LOAT    2.#defin
28430 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20 20  e SQLITE_BLOB   
28440 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
28450 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23 69  TE_NULL     5.#i
28460 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58 54  fdef SQLITE_TEXT
28470 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45 5f  .# undef SQLITE_
28480 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65 66  TEXT.#else.# def
28490 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54 20  ine SQLITE_TEXT 
284a0 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64 65      3.#endif.#de
284b0 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45 58  fine SQLITE3_TEX
284c0 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20 43  T     3../*.** C
284d0 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74 20  API3REF: Result 
284e0 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51 75  Values From A Qu
284f0 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ery.** KEYWORDS:
28500 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73 20   {column access 
28510 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a 2a  functions}.**.**
28520 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
28530 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c 74  form the "result
28540 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65 2e   set" interface.
28550 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
28560 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69 6e  utines return in
28570 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20  formation about 
28580 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e 20  a single column 
28590 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  of the current.*
285a0 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66 20  * result row of 
285b0 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65 76  a query.  ^In ev
285c0 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69 72  ery case the fir
285d0 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61  st argument is a
285e0 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74   pointer.** to t
285f0 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
28600 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73 20  tement] that is 
28610 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64 20  being evaluated 
28620 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73 74  (the [sqlite3_st
28630 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61 73  mt*].** that was
28640 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20 5b   returned from [
28650 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
28660 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66 20  v2()] or one of 
28670 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a 2a  its variants).**
28680 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64 20   and the second 
28690 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65 20  argument is the 
286a0 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f 6c  index of the col
286b0 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69 6e  umn for which in
286c0 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68 6f  formation.** sho
286d0 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64 2e  uld be returned.
286e0 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20 63   ^The leftmost c
286f0 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
28700 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65 20  ult set has the 
28710 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68 65  index 0..** ^The
28720 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
28730 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74  ns in the result
28740 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69 6e   can be determin
28750 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c  ed using.** [sql
28760 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
28770 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74  t()]..**.** If t
28780 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  he SQL statement
28790 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65 6e   does not curren
287a0 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20 76  tly point to a v
287b0 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66 20  alid row, or if 
287c0 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69 6e  the.** column in
287d0 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72 61  dex is out of ra
287e0 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74 20  nge, the result 
287f0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
28800 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
28810 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  may only be call
28820 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73 74  ed when the most
28830 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f 0a   recent call to.
28840 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ** [sqlite3_step
28850 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65 64  ()] has returned
28860 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61 6e   [SQLITE_ROW] an
28870 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73 71  d neither.** [sq
28880 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6e  lite3_reset()] n
28890 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61  or [sqlite3_fina
288a0 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65 65  lize()] have bee
288b0 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71 75  n called subsequ
288c0 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e 79  ently..** If any
288d0 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
288e0 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61 66  es are called af
288f0 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  ter [sqlite3_res
28900 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c  et()] or.** [sql
28910 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d  ite3_finalize()]
28920 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69 74   or after [sqlit
28930 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20 72  e3_step()] has r
28940 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65 74  eturned.** somet
28950 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e 20  hing other than 
28960 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74 68  [SQLITE_ROW], th
28970 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
28980 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20 5b  defined..** If [
28990 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
289a0 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  or [sqlite3_rese
289b0 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
289c0 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a 20  _finalize()].** 
289d0 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20  are called from 
289e0 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  a different thre
289f0 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66 20  ad while any of 
28a00 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a 2a  these routines.*
28a10 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20 74  * are pending, t
28a20 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20  hen the results 
28a30 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a  are undefined..*
28a40 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
28a50 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
28a60 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
28a70 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49  the.** [SQLITE_I
28a80 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79 70  NTEGER | datatyp
28a90 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20  e code] for the 
28aa0 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79 70  initial data typ
28ab0 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73 75  e.** of the resu
28ac0 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68 65  lt column.  ^The
28ad0 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65 20   returned value 
28ae0 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
28af0 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20 5b  E_INTEGER],.** [
28b00 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20 5b  SQLITE_FLOAT], [
28b10 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b 53  SQLITE_TEXT], [S
28b20 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72 20  QLITE_BLOB], or 
28b30 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20 20  [SQLITE_NULL].  
28b40 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65 74  The value.** ret
28b50 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33  urned by sqlite3
28b60 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20 69  _column_type() i
28b70 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66 75  s only meaningfu
28b80 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a 20  l if no type.** 
28b90 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76 65  conversions have
28ba0 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65 73   occurred as des
28bb0 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20 41  cribed below.  A
28bc0 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e 76  fter a type conv
28bd0 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20 76  ersion,.** the v
28be0 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79  alue returned by
28bf0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28c00 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66 69  type() is undefi
28c10 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a 20  ned.  Future.** 
28c20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69  versions of SQLi
28c30 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74 68  te may change th
28c40 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
28c50 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70  lite3_column_typ
28c60 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67  e().** following
28c70 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73 69   a type conversi
28c80 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  on..**.** ^If th
28c90 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42 4c  e result is a BL
28ca0 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72 69  OB or UTF-8 stri
28cb0 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c 69  ng then the sqli
28cc0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28cd0 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72 65  ().** routine re
28ce0 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
28cf0 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68 61   of bytes in tha
28d00 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e 67  t BLOB or string
28d10 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73  ..** ^If the res
28d20 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36 20  ult is a UTF-16 
28d30 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71 6c  string, then sql
28d40 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28d50 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a 20  s() converts.** 
28d60 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55 54  the string to UT
28d70 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65 74  F-8 and then ret
28d80 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72 20  urns the number 
28d90 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49 66  of bytes..** ^If
28da0 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
28db0 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20 74   numeric value t
28dc0 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
28dd0 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73 0a  mn_bytes() uses.
28de0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72  ** [sqlite3_snpr
28df0 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76 65  intf()] to conve
28e00 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74 6f  rt that value to
28e10 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67 20   a UTF-8 string 
28e20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74  and returns.** t
28e30 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
28e40 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69 6e  es in that strin
28e50 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
28e60 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68  sult is NULL, th
28e70 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28e80 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72 6e  n_bytes() return
28e90 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 49  s zero..**.** ^I
28ea0 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
28eb0 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31 36  a BLOB or UTF-16
28ec0 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68 65   string then the
28ed0 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28ee0 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f 75  bytes16().** rou
28ef0 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68 65  tine returns the
28f00 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73   number of bytes
28f10 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f 72   in that BLOB or
28f20 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66 20   string..** ^If 
28f30 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20  the result is a 
28f40 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74 68  UTF-8 string, th
28f50 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  en sqlite3_colum
28f60 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e 76  n_bytes16() conv
28f70 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72 69  erts.** the stri
28f80 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e 64  ng to UTF-16 and
28f90 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74 68   then returns th
28fa0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
28fb0 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  s..** ^If the re
28fc0 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72 69  sult is a numeri
28fd0 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71 6c  c value then sql
28fe0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
28ff0 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b 73  s16() uses.** [s
29000 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
29010 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  )] to convert th
29020 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55 54  at value to a UT
29030 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64 20  F-16 string and 
29040 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20 6e  returns.** the n
29050 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20 69  umber of bytes i
29060 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a 2a  n that string..*
29070 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c 74  * ^If the result
29080 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 73   is NULL, then s
29090 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
290a0 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73 20  tes16() returns 
290b0 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  zero..**.** ^The
290c0 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65 64   values returned
290d0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
290e0 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e 64  umn_bytes()] and
290f0 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f   .** [sqlite3_co
29100 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d 20  lumn_bytes16()] 
29110 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20 74  do not include t
29120 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61 74  he zero terminat
29130 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a 2a  ors at the end.*
29140 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 2e  * of the string.
29150 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a 20    ^For clarity: 
29160 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72  the values retur
29170 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
29180 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 28  e3_column_bytes(
29190 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
291a0 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29  column_bytes16()
291b0 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65 72  ] are the number
291c0 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e 20   of.** bytes in 
291d0 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74 20  the string, not 
291e0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  the number of ch
291f0 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a 20  aracters..**.** 
29200 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e 65  ^Strings returne
29210 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c  d by sqlite3_col
29220 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20 73  umn_text() and s
29230 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29240 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e 20  xt16(),.** even 
29250 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20 61  empty strings, a
29260 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20 74  re always zero t
29270 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68 65  erminated.  ^The
29280 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75 65   return.** value
29290 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63 6f   from sqlite3_co
292a0 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72 20  lumn_blob() for 
292b0 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42 4c  a zero-length BL
292c0 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69  OB is a NULL poi
292d0 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  nter..**.** ^The
292e0 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
292f0 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c   by [sqlite3_col
29300 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73 20  umn_value()] is 
29310 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63 74  an.** [unprotect
29320 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
29330 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75 6e  ] object.  An un
29340 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
29350 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a 2a  3_value object.*
29360 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75 73  * may only be us
29370 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65 33  ed with [sqlite3
29380 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20 61  _bind_value()] a
29390 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75  nd [sqlite3_resu
293a0 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a 20  lt_value()]..** 
293b0 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65 63  If the [unprotec
293c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
293d0 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e  e] object return
293e0 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65  ed by.** [sqlite
293f0 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 29  3_column_value()
29400 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e 79  ] is used in any
29410 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63 6c   other way, incl
29420 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20 74  uding calls.** t
29430 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65 20  o routines like 
29440 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69  [sqlite3_value_i
29450 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  nt()], [sqlite3_
29460 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a 2a  value_text()],.*
29470 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76 61  * or [sqlite3_va
29480 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74 68  lue_bytes()], th
29490 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72 20  en the behavior 
294a0 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  is undefined..**
294b0 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e  .** These routin
294c0 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63 6f  es attempt to co
294d0 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65 20  nvert the value 
294e0 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61 74  where appropriat
294f0 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61 6d  e.  ^For.** exam
29500 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74 65  ple, if the inte
29510 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61 74  rnal representat
29520 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e 64  ion is FLOAT and
29530 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a 2a   a text result.*
29540 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c 20  * is requested, 
29550 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74  [sqlite3_snprint
29560 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e 74  f()] is used int
29570 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66 6f  ernally to perfo
29580 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65 72  rm the.** conver
29590 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61 6c  sion automatical
295a0 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c 6f  ly.  ^(The follo
295b0 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61 69  wing table detai
295c0 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69 6f  ls the conversio
295d0 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 61  ns.** that are a
295e0 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c 62  pplied:.**.** <b
295f0 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74  lockquote>.** <t
29600 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e  able border="1">
29610 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e 74  .** <tr><th> Int
29620 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c 74  ernal<br>Type <t
29630 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72 3e  h> Requested<br>
29640 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76 65  Type <th>  Conve
29650 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72 3e  rsion.**.** <tr>
29660 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74  <td>  NULL    <t
29670 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
29680 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a 2a  > Result is 0.**
29690 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20   <tr><td>  NULL 
296a0 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20     <td>  FLOAT  
296b0 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69 73    <td> Result is
296c0 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e   0.0.** <tr><td>
296d0 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
296e0 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52 65   TEXT    <td> Re
296f0 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
29700 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
29710 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20 20    NULL    <td>  
29720 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52 65   BLOB    <td> Re
29730 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f 69  sult is NULL poi
29740 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  nter.** <tr><td>
29750 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
29760 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43 6f  FLOAT    <td> Co
29770 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65 67  nvert from integ
29780 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20 3c  er to float.** <
29790 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52 20  tr><td> INTEGER 
297a0 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20   <td>   TEXT    
297b0 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65  <td> ASCII rende
297c0 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74 65  ring of the inte
297d0 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  ger.** <tr><td> 
297e0 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20 20  INTEGER  <td>   
297f0 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61 6d  BLOB    <td> Sam
29800 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54 45  e as INTEGER->TE
29810 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20  XT.** <tr><td>  
29820 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e 54  FLOAT   <td> INT
29830 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e 76  EGER   <td> Conv
29840 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20 74  ert from float t
29850 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74 72  o integer.** <tr
29860 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20 3c  ><td>  FLOAT   <
29870 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
29880 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72 69  d> ASCII renderi
29890 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74 0a  ng of the float.
298a0 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c 4f  ** <tr><td>  FLO
298b0 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f 42  AT   <td>   BLOB
298c0 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61 73      <td> Same as
298d0 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a 20   FLOAT->TEXT.** 
298e0 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20 20  <tr><td>  TEXT  
298f0 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20 20    <td> INTEGER  
29900 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28 29   <td> Use atoi()
29910 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45  .** <tr><td>  TE
29920 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  XT    <td>  FLOA
29930 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61 74  T    <td> Use at
29940 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  of().** <tr><td>
29950 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 20    TEXT    <td>  
29960 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e 6f   BLOB    <td> No
29970 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e 3c   change.** <tr><
29980 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74 64  td>  BLOB    <td
29990 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64 3e  > INTEGER   <td>
299a0 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58 54   Convert to TEXT
299b0 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28 29   then use atoi()
299c0 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42 4c  .** <tr><td>  BL
299d0 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41  OB    <td>  FLOA
299e0 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65 72  T    <td> Conver
299f0 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20 75  t to TEXT then u
29a00 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74 72  se atof().** <tr
29a10 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c  ><td>  BLOB    <
29a20 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c 74  td>   TEXT    <t
29a30 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74 65  d> Add a zero te
29a40 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65 64  rminator if need
29a50 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a  ed.** </table>.*
29a60 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  * </blockquote>)
29a70 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62 6c  ^.**.** The tabl
29a80 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72 65  e above makes re
29a90 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e 64  ference to stand
29aa0 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66 75  ard C library fu
29ab0 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a 2a  nctions atoi().*
29ac0 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20 53  * and atof().  S
29ad0 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20 72  QLite does not r
29ae0 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65 20  eally use these 
29af0 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20 68  functions.  It h
29b00 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65 71  as its.** own eq
29b10 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e 61  uivalent interna
29b20 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68 65  l routines.  The
29b30 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f 66   atoi() and atof
29b40 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a 20  () names are.** 
29b50 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62 6c  used in the tabl
29b60 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61 6e  e for brevity an
29b70 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20 61  d because they a
29b80 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20 6d  re familiar to m
29b90 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61 6d  ost.** C program
29ba0 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  mers..**.** Note
29bb0 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65 20   that when type 
29bc0 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63 75  conversions occu
29bd0 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  r, pointers retu
29be0 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a 2a  rned by prior.**
29bf0 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65   calls to sqlite
29c00 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 2c  3_column_blob(),
29c10 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
29c20 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a 2a  text(), and/or.*
29c30 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
29c40 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62 65  _text16() may be
29c50 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a   invalidated..**
29c60 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f 6e   Type conversion
29c70 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69 6e  s and pointer in
29c80 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67 68  validations migh
29c90 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74 68  t occur.** in th
29ca0 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73 65  e following case
29cb0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a  s:.**.** <ul>.**
29cc0 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29cd0 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20 42  l content is a B
29ce0 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  LOB and sqlite3_
29cf0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72  column_text() or
29d00 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65 33  .**      sqlite3
29d10 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29  _column_text16()
29d20 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20 7a   is called.  A z
29d30 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20 6d  ero-terminator m
29d40 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65 65  ight.**      nee
29d50 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74 6f  d to be added to
29d60 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c 69   the string.</li
29d70 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e  >.** <li> The in
29d80 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73  itial content is
29d90 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64 20   UTF-8 text and 
29da0 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29db0 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20 20  ytes16() or.**  
29dc0 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75      sqlite3_colu
29dd0 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20 63  mn_text16() is c
29de0 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e 74  alled.  The cont
29df0 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e 76  ent must be conv
29e00 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74 6f  erted.**      to
29e10 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a 2a   UTF-16.</li>.**
29e20 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69 61   <li> The initia
29e30 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54 46  l content is UTF
29e40 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71 6c  -16 text and sql
29e50 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
29e60 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20 73  s() or.**      s
29e70 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65  qlite3_column_te
29e80 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e 20  xt() is called. 
29e90 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75 73   The content mus
29ea0 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a 2a  t be converted.*
29eb0 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38 2e  *      to UTF-8.
29ec0 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  </li>.** </ul>.*
29ed0 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f 6e  *.** ^Conversion
29ee0 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31 36  s between UTF-16
29ef0 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65 20  be and UTF-16le 
29f00 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65 20  are always done 
29f10 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f 0a  in place and do.
29f20 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61 74  ** not invalidat
29f30 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74 65  e a prior pointe
29f40 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f 75  r, though of cou
29f50 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  rse the content 
29f60 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a 2a  of the buffer.**
29f70 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72 20   that the prior 
29f80 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e 63  pointer referenc
29f90 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65 65  es will have bee
29fa0 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74 68  n modified.  Oth
29fb0 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20 63  er kinds.** of c
29fc0 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64 6f  onversion are do
29fd0 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65 6e  ne in place when
29fe0 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65 2c   it is possible,
29ff0 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20 74   but sometimes t
2a000 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20 70  hey.** are not p
2a010 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20 74  ossible and in t
2a020 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f 72  hose cases prior
2a030 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69 6e   pointers are in
2a040 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a 2a  validated..**.**
2a050 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64 20   The safest and 
2a060 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65 6d  easiest to remem
2a070 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74 6f  ber policy is to
2a080 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72 6f   invoke these ro
2a090 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e 65  utines.** in one
2a0a0 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e   of the followin
2a0b0 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75  g ways:.**.** <u
2a0c0 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74  l>.**  <li>sqlit
2a0d0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29  e3_column_text()
2a0e0 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c   followed by sql
2a0f0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
2a100 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c 69  s()</li>.**  <li
2a110 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  >sqlite3_column_
2a120 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64 20  blob() followed 
2a130 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  by sqlite3_colum
2a140 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a 2a  n_bytes()</li>.*
2a150 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f 63  *  <li>sqlite3_c
2a160 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 66  olumn_text16() f
2a170 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69 74  ollowed by sqlit
2a180 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31  e3_column_bytes1
2a190 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c  6()</li>.** </ul
2a1a0 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65 72  >.**.** In other
2a1b0 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f 75   words, you shou
2a1c0 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f  ld call sqlite3_
2a1d0 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a 2a  column_text(),.*
2a1e0 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  * sqlite3_column
2a1f0 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c 69  _blob(), or sqli
2a200 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31  te3_column_text1
2a210 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f 72  6() first to for
2a220 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a 2a  ce the result.**
2a230 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72 65   into the desire
2a240 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20 69  d format, then i
2a250 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63 6f  nvoke sqlite3_co
2a260 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72 0a  lumn_bytes() or.
2a270 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
2a280 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20 66  n_bytes16() to f
2a290 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66 20  ind the size of 
2a2a0 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f 20  the result.  Do 
2a2b0 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a 2a  not mix calls.**
2a2c0 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   to sqlite3_colu
2a2d0 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71 6c  mn_text() or sql
2a2e0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a2f0 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f  () with calls to
2a300 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
2a310 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61 6e  mn_bytes16(), an
2a320 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61 6c  d do not mix cal
2a330 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f  ls to sqlite3_co
2a340 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a 2a  lumn_text16().**
2a350 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20 73   with calls to s
2a360 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a370 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  tes()..**.** ^Th
2a380 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75 72  e pointers retur
2a390 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75 6e  ned are valid un
2a3a0 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76 65  til a type conve
2a3b0 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73 0a  rsion occurs as.
2a3c0 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62 6f  ** described abo
2a3d0 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73 71  ve, or until [sq
2a3e0 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 72  lite3_step()] or
2a3f0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2a400 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74 65  )] or.** [sqlite
2a410 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69 73  3_finalize()] is
2a420 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20 6d   called.  ^The m
2a430 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65 64  emory space used
2a440 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67 73   to hold strings
2a450 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69 73  .** and BLOBs is
2a460 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69 63   freed automatic
2a470 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f 74  ally.  Do <b>not
2a480 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70 6f  </b> pass the po
2a490 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64 0a  inters returned.
2a4a0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75  ** [sqlite3_colu
2a4b0 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71 6c  mn_blob()], [sql
2a4c0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a4d0 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a 2a  ()], etc. into.*
2a4e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28  * [sqlite3_free(
2a4f0 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 61  )]..**.** ^(If a
2a500 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
2a510 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20  on error occurs 
2a520 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c 75  during the evalu
2a530 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a 20  ation of any.** 
2a540 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  of these routine
2a550 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61 6c  s, a default val
2a560 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e 20  ue is returned. 
2a570 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61 6c   The default val
2a580 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72 20  ue.** is either 
2a590 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20 74  the integer 0, t
2a5a0 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69 6e  he floating poin
2a5b0 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f 72  t number 0.0, or
2a5c0 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e 74   a NULL.** point
2a5d0 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74 20  er.  Subsequent 
2a5e0 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74 65  calls to [sqlite
2a5f0 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69 6c  3_errcode()] wil
2a600 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51 4c  l return.** [SQL
2a610 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a 2f  ITE_NOMEM].)^.*/
2a620 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
2a630 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62  ite3_column_blob
2a640 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a650 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
2a660 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79  qlite3_column_by
2a670 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  tes(sqlite3_stmt
2a680 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e  *, int iCol);.in
2a690 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  t sqlite3_column
2a6a0 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65 33  _bytes16(sqlite3
2a6b0 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f 6c  _stmt*, int iCol
2a6c0 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74 65  );.double sqlite
2a6d0 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65 28  3_column_double(
2a6e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
2a6f0 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71  nt iCol);.int sq
2a700 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
2a710 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a720 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74  int iCol);.sqlit
2a730 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65 33  e3_int64 sqlite3
2a740 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73 71  _column_int64(sq
2a750 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
2a760 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75 6e   iCol);.const un
2a770 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71 6c  signed char *sql
2a780 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
2a790 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
2a7a0 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74  int iCol);.const
2a7b0 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 63   void *sqlite3_c
2a7c0 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71 6c  olumn_text16(sql
2a7d0 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a7e0 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69 74  iCol);.int sqlit
2a7f0 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 73  e3_column_type(s
2a800 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
2a810 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65 33  t iCol);.sqlite3
2a820 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33 5f  _value *sqlite3_
2a830 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71 6c  column_value(sql
2a840 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20  ite3_stmt*, int 
2a850 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  iCol);../*.** CA
2a860 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79 20  PI3REF: Destroy 
2a870 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74 65  A Prepared State
2a880 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a  ment Object.**.*
2a890 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 66  * ^The sqlite3_f
2a8a0 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74 69  inalize() functi
2a8b0 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f 20  on is called to 
2a8c0 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61 72  delete a [prepar
2a8d0 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a  ed statement]..*
2a8e0 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72  * ^If the most r
2a8f0 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f 6e  ecent evaluation
2a900 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   of the statemen
2a910 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e 6f  t encountered no
2a920 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f 72   errors or.** or
2a930 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65 6e   if the statemen
2a940 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e 20  t is never been 
2a950 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e 20  evaluated, then 
2a960 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65  sqlite3_finalize
2a970 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53 51  () returns.** SQ
2a980 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74 68  LITE_OK.  ^If th
2a990 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65 76  e most recent ev
2a9a0 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61 74  aluation of stat
2a9b0 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c 20  ement S failed, 
2a9c0 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  then.** sqlite3_
2a9d0 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74 75  finalize(S) retu
2a9e0 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72 69  rns the appropri
2a9f0 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d  ate [error code]
2aa00 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64   or.** [extended
2aa10 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a 2a   error code]..**
2aa20 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2aa30 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f 75  _finalize(S) rou
2aa40 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c 6c  tine can be call
2aa50 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74 20  ed at any point 
2aa60 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c 69  during.** the li
2aa70 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72 65  fe cycle of [pre
2aa80 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
2aa90 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73 74   S:.** before st
2aaa0 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76 65  atement S is eve
2aab0 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66 74  r evaluated, aft
2aac0 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f 72  er.** one or mor
2aad0 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  e calls to [sqli
2aae0 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f 72  te3_reset()], or
2aaf0 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c 0a   after any call.
2ab00 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f 73  ** to [sqlite3_s
2ab10 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65 73  tep()] regardles
2ab20 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72 20  s of whether or 
2ab30 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65 6e  not the statemen
2ab40 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65 74  t has.** complet
2ab50 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a 2a  ed execution..**
2ab60 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73 71  .** ^Invoking sq
2ab70 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
2ab80 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74   on a NULL point
2ab90 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73 73  er is a harmless
2aba0 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54 68   no-op..**.** Th
2abb0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75  e application mu
2abc0 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65 72  st finalize ever
2abd0 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  y [prepared stat
2abe0 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72 20  ement] in order 
2abf0 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73 6f  to avoid.** reso
2ac00 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74 20  urce leaks.  It 
2ac10 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65 72  is a grievous er
2ac20 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70 6c  ror for the appl
2ac30 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20 74  ication to try t
2ac40 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70 61  o use.** a prepa
2ac50 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61 66  red statement af
2ac60 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e 20  ter it has been 
2ac70 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79 20  finalized.  Any 
2ac80 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72 65  use of a prepare
2ac90 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61  d.** statement a
2aca0 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
2acb0 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20 72   finalized can r
2acc0 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69 6e  esult in undefin
2acd0 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73 69  ed and.** undesi
2ace0 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20 73  rable behavior s
2acf0 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74 73  uch as segfaults
2ad00 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75 70   and heap corrup
2ad10 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  tion..*/.int sql
2ad20 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73 71  ite3_finalize(sq
2ad30 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
2ad40 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
2ad50 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72 65  REF: Reset A Pre
2ad60 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 20  pared Statement 
2ad70 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68 65  Object.**.** The
2ad80 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29   sqlite3_reset()
2ad90 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61 6c   function is cal
2ada0 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20 5b  led to reset a [
2adb0 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
2adc0 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62 61  nt].** object ba
2add0 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69 61  ck to its initia
2ade0 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20 74  l state, ready t
2adf0 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65 64  o be re-executed
2ae00 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73 74  ..** ^Any SQL st
2ae10 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c 65  atement variable
2ae20 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75 65  s that had value
2ae30 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d 20  s bound to them 
2ae40 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73 71  using.** the [sq
2ae50 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 20  lite3_bind_blob 
2ae60 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  | sqlite3_bind_*
2ae70 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20 74  () API] retain t
2ae80 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a 20  heir values..** 
2ae90 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c 65  Use [sqlite3_cle
2aea0 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20 74  ar_bindings()] t
2aeb0 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e 64  o reset the bind
2aec0 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ings..**.** ^The
2aed0 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28   [sqlite3_reset(
2aee0 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72 65  S)] interface re
2aef0 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61 72  sets the [prepar
2af00 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 0a  ed statement] S.
2af10 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20 62  ** back to the b
2af20 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73 20  eginning of its 
2af30 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  program..**.** ^
2af40 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  If the most rece
2af50 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69  nt call to [sqli
2af60 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f 72  te3_step(S)] for
2af70 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65   the.** [prepare
2af80 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20 72  d statement] S r
2af90 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45 5f  eturned [SQLITE_
2afa0 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  ROW] or [SQLITE_
2afb0 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66 20  DONE],.** or if 
2afc0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53 29  [sqlite3_step(S)
2afd0 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66 6f  ] has never befo
2afe0 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20 6f  re been called o
2aff0 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73 71  n S,.** then [sq
2b000 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20  lite3_reset(S)] 
2b010 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45 5f  returns [SQLITE_
2b020 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  OK]..**.** ^If t
2b030 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 63  he most recent c
2b040 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
2b050 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68 65  step(S)] for the
2b060 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74  .** [prepared st
2b070 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69 63  atement] S indic
2b080 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20 74  ated an error, t
2b090 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  hen.** [sqlite3_
2b0a0 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72 6e  reset(S)] return
2b0b0 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65  s an appropriate
2b0c0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a   [error code]..*
2b0d0 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69 74  *.** ^The [sqlit
2b0e0 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e 74  e3_reset(S)] int
2b0f0 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74 20  erface does not 
2b100 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75 65  change the value
2b110 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71 6c  s.** of any [sql
2b120 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 62  ite3_bind_blob|b
2b130 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65 20  indings] on the 
2b140 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
2b150 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20 73  ent] S..*/.int s
2b160 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71 6c  qlite3_reset(sql
2b170 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
2b180 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2b190 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52 65  EF: Create Or Re
2b1a0 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63 74  define SQL Funct
2b1b0 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  ions.** KEYWORDS
2b1c0 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65 61  : {function crea
2b1d0 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a 2a  tion routines}.*
2b1e0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b1f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b200 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a 2a   SQL function}.*
2b210 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70 70  * KEYWORDS: {app
2b220 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2b230 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d 0a   SQL functions}.
2b240 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e  **.** ^These fun
2b250 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74 69  ctions (collecti
2b260 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22 66  vely known as "f
2b270 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f 6e  unction creation
2b280 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20 61   routines").** a
2b290 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20 53  re used to add S
2b2a0 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72 20  QL functions or 
2b2b0 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74 6f  aggregates or to
2b2c0 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62 65   redefine the be
2b2d0 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78 69  havior.** of exi
2b2e0 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74 69  sting SQL functi
2b2f0 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74 65  ons or aggregate
2b300 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69 66  s.  The only dif
2b310 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65 6e  ferences between
2b320 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69 6e  .** these routin
2b330 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74 20  es are the text 
2b340 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74 65  encoding expecte
2b350 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65 63  d for.** the sec
2b360 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28 74  ond parameter (t
2b370 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 66  he name of the f
2b380 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63 72  unction being cr
2b390 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74 68  eated).** and th
2b3a0 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61 62  e presence or ab
2b3b0 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74 72  sence of a destr
2b3c0 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20 66  uctor callback f
2b3d0 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63  or.** the applic
2b3e0 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e 74  ation data point
2b3f0 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  er..**.** ^The f
2b400 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
2b410 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  s the [database 
2b420 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20 77  connection] to w
2b430 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a 20  hich the SQL.** 
2b440 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20 62  function is to b
2b450 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61 6e  e added.  ^If an
2b460 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 65   application use
2b470 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65 20  s more than one 
2b480 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e 6e  database.** conn
2b490 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70 6c  ection then appl
2b4a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2b4b0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d 75  SQL functions mu
2b4c0 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20 74  st be added.** t
2b4d0 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65 20  o each database 
2b4e0 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61 72  connection separ
2b4f0 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ately..**.** ^Th
2b500 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2b510 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  er is the name o
2b520 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74 69  f the SQL functi
2b530 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65 64  on to be created
2b540 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65 64   or.** redefined
2b550 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20 6f  .  ^The length o
2b560 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c 69  f the name is li
2b570 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79 74  mited to 255 byt
2b580 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a 2a  es in a UTF-8.**
2b590 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e 2c   representation,
2b5a0 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74 68   exclusive of th
2b5b0 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f  e zero-terminato
2b5c0 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20 74  r.  ^Note that t
2b5d0 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67 74  he name.** lengt
2b5e0 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55 54  h limit is in UT
2b5f0 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20 63  F-8 bytes, not c
2b600 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55 54  haracters nor UT
2b610 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a 2a  F-16 bytes.  .**
2b620 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74 6f   ^Any attempt to
2b630 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74 69   create a functi
2b640 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65 72  on with a longer
2b650 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72 65   name.** will re
2b660 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45 5f  sult in [SQLITE_
2b670 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72 65  MISUSE] being re
2b680 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  turned..**.** ^T
2b690 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2b6a0 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73 20  er (nArg).** is 
2b6b0 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61 72  the number of ar
2b6c0 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68 65  guments that the
2b6d0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72   SQL function or
2b6e0 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74 61  .** aggregate ta
2b6f0 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70 61  kes. ^If this pa
2b700 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20 74  rameter is -1, t
2b710 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e 63  hen the SQL func
2b720 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72 65  tion or.** aggre
2b730 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61 6e  gate may take an
2b740 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75  y number of argu
2b750 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30 20  ments between 0 
2b760 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a 2a  and the limit.**
2b770 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65 33   set by [sqlite3
2b780 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45 5f  _limit]([SQLITE_
2b790 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f 41  LIMIT_FUNCTION_A
2b7a0 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74 68  RG]).  If the th
2b7b0 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  ird.** parameter
2b7c0 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d 31   is less than -1
2b7d0 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61 6e   or greater than
2b7e0 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62 65   127 then the be
2b7f0 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e 64  havior is.** und
2b800 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  efined..**.** ^T
2b810 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d 65  he fourth parame
2b820 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20 73  ter, eTextRep, s
2b830 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a 2a  pecifies what.**
2b840 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c 20   [SQLITE_UTF8 | 
2b850 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20 74  text encoding] t
2b860 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  his SQL function
2b870 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a 20   prefers for.** 
2b880 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e 20  its parameters. 
2b890 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63 74   Every SQL funct
2b8a0 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ion implementati
2b8b0 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65 20  on must be able 
2b8c0 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68 20  to work.** with 
2b8d0 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65 2c  UTF-8, UTF-16le,
2b8e0 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20 42   or UTF-16be.  B
2b8f0 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65 6e  ut some implemen
2b900 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a 2a  tations may be.*
2b910 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e 74  * more efficient
2b920 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64 69   with one encodi
2b930 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72 2e  ng than another.
2b940 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69 6f    ^An applicatio
2b950 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65 20  n may.** invoke 
2b960 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2b970 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71 6c  unction() or sql
2b980 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63  ite3_create_func
2b990 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70 6c  tion16() multipl
2b9a0 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68 20  e.** times with 
2b9b0 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f  the same functio
2b9c0 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66 65  n but with diffe
2b9d0 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20 65  rent values of e
2b9e0 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68 65  TextRep..** ^Whe
2b9f0 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c 65  n multiple imple
2ba00 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74 68  mentations of th
2ba10 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e 20  e same function 
2ba20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20 53  are available, S
2ba30 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70 69  QLite.** will pi
2ba40 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74 20  ck the one that 
2ba50 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65 61  involves the lea
2ba60 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61 74  st amount of dat
2ba70 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a 2a  a conversion..**
2ba80 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e 6c   If there is onl
2ba90 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c 65  y a single imple
2baa0 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68 20  mentation which 
2bab0 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77 68  does not care wh
2bac0 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f 64  at text.** encod
2bad0 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68 65  ing is used, the
2bae0 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72 67  n the fourth arg
2baf0 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20  ument should be 
2bb00 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a 2a  [SQLITE_ANY]..**
2bb10 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68 20  .** ^(The fifth 
2bb20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e 20  parameter is an 
2bb30 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74 65  arbitrary pointe
2bb40 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65 6e  r.  The implemen
2bb50 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a 2a  tation of the.**
2bb60 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67 61   function can ga
2bb70 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68 69  in access to thi
2bb80 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67 20  s pointer using 
2bb90 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64 61  [sqlite3_user_da
2bba0 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  ta()].)^.**.** ^
2bbb0 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65 6e  The sixth, seven
2bbc0 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70 61  th and eighth pa
2bbd0 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63 2c  rameters, xFunc,
2bbe0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2bbf0 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74 65  l, are.** pointe
2bc00 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67 65  rs to C-language
2bc10 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74 20   functions that 
2bc20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53 51  implement the SQ
2bc30 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a 2a  L function or.**
2bc40 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20 73   aggregate. ^A s
2bc50 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69  calar SQL functi
2bc60 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20 69  on requires an i
2bc70 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66  mplementation of
2bc80 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63 61   the xFunc.** ca
2bc90 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55 4c  llback only; NUL
2bca0 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74 20  L pointers must 
2bcb0 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65  be passed as the
2bcc0 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e 61   xStep and xFina
2bcd0 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 2e  l.** parameters.
2bce0 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20 53   ^An aggregate S
2bcf0 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  QL function requ
2bd00 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65 6e  ires an implemen
2bd10 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70 0a  tation of xStep.
2bd20 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61 6e  ** and xFinal an
2bd30 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6d  d NULL pointer m
2bd40 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66 6f  ust be passed fo
2bd50 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65 6c  r xFunc. ^To del
2bd60 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67 0a  ete an existing.
2bd70 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  ** SQL function 
2bd80 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70 61  or aggregate, pa
2bd90 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 73  ss NULL pointers
2bda0 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20 66   for all three f
2bdb0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c 62  unction.** callb
2bdc0 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66  acks..**.** ^(If
2bdd0 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61 6d   the ninth param
2bde0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
2bdf0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2be00 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c 4c  v2() is not NULL
2be10 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73 20  ,.** then it is 
2be20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20 74  destructor for t
2be30 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2be40 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a 2a  ata pointer. .**
2be50 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72 20   The destructor 
2be60 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e 20  is invoked when 
2be70 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73 20  the function is 
2be80 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72 20  deleted, either 
2be90 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65 72  by being.** over
2bea0 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20 74  loaded or when t
2beb0 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  he database conn
2bec0 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29 5e  ection closes.)^
2bed0 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75 63  .** ^The destruc
2bee0 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76 6f  tor is also invo
2bef0 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c 20  ked if the call 
2bf00 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  to.** sqlite3_cr
2bf10 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2bf20 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57 68  () fails..** ^Wh
2bf30 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74 6f  en the destructo
2bf40 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  r callback of th
2bf50 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74 65  e tenth paramete
2bf60 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69 74  r is invoked, it
2bf70 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61 20  .** is passed a 
2bf80 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
2bf90 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79 20  which is a copy 
2bfa0 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  of the applicati
2bfb0 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69 6e  on data .** poin
2bfc0 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74 68  ter which was th
2bfd0 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74 65  e fifth paramete
2bfe0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72 65  r to sqlite3_cre
2bff0 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32 28  ate_function_v2(
2c000 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20  )..**.** ^It is 
2c010 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65 67  permitted to reg
2c020 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20 69  ister multiple i
2c030 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f  mplementations o
2c040 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66 75  f the same.** fu
2c050 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68 65  nctions with the
2c060 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20 77   same name but w
2c070 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66 65  ith either diffe
2c080 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66 0a  ring numbers of.
2c090 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72 20  ** arguments or 
2c0a0 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65 72  differing prefer
2c0b0 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e  red text encodin
2c0c0 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  gs.  ^SQLite wil
2c0d0 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d 70  l use.** the imp
2c0e0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61 74  lementation that
2c0f0 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d 61   most closely ma
2c100 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69 6e  tches the way in
2c110 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53 51   which the.** SQ
2c120 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75 73  L function is us
2c130 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e  ed.  ^A function
2c140 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
2c150 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61 74  with a non-negat
2c160 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72 61  ive.** nArg para
2c170 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74 65  meter is a bette
2c180 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66  r match than a f
2c190 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e  unction implemen
2c1a0 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20 61  tation with.** a
2c1b0 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e 20   negative nArg. 
2c1c0 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68 65   ^A function whe
2c1d0 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65 64  re the preferred
2c1e0 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a 2a   text encoding.*
2c1f0 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64 61  * matches the da
2c200 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67 20  tabase encoding 
2c210 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20 6d  is a better.** m
2c220 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e 63  atch than a func
2c230 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20 65  tion where the e
2c240 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66 65  ncoding is diffe
2c250 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66 75  rent.  .** ^A fu
2c260 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65  nction where the
2c270 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65 72   encoding differ
2c280 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e 20  ence is between 
2c290 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46 31  UTF16le and UTF1
2c2a0 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f 73  6be.** is a clos
2c2b0 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2c2c0 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74  function where t
2c2d0 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66  he encoding diff
2c2e0 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65 74  erence is.** bet
2c2f0 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55 54  ween UTF8 and UT
2c300 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69 6c  F16..**.** ^Buil
2c310 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20 6d  t-in functions m
2c320 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65 64  ay be overloaded
2c330 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61 74   by new applicat
2c340 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2c350 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  tions..**.** ^An
2c360 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2c370 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69 73  ined function is
2c380 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63 61   permitted to ca
2c390 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c 69  ll other.** SQLi
2c3a0 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20 20  te interfaces.  
2c3b0 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63 61  However, such ca
2c3c0 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a 20  lls must not.** 
2c3d0 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62 61  close the databa
2c3e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e 6f  se connection no
2c3f0 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72 65  r finalize or re
2c400 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65 64  set the prepared
2c410 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69 6e  .** statement in
2c420 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63 74   which the funct
2c430 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e 0a  ion is running..
2c440 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
2c450 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28 0a  reate_function(.
2c460 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 20    sqlite3 *db,. 
2c470 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46 75   const char *zFu
2c480 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69 6e  nctionName,.  in
2c490 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65 54  t nArg,.  int eT
2c4a0 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20 2a  extRep,.  void *
2c4b0 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a 78  pApp,.  void (*x
2c4c0 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63 6f  Func)(sqlite3_co
2c4d0 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c4e0 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c4f0 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71 6c  oid (*xStep)(sql
2c500 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e  ite3_context*,in
2c510 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  t,sqlite3_value*
2c520 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46 69  *),.  void (*xFi
2c530 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f 6e  nal)(sqlite3_con
2c540 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73 71  text*).);.int sq
2c550 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2c560 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69 74  ction16(.  sqlit
2c570 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74 20  e3 *db,.  const 
2c580 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e 4e  void *zFunctionN
2c590 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67 2c  ame,.  int nArg,
2c5a0 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c  .  int eTextRep,
2c5b0 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a 20  .  void *pApp,. 
2c5c0 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28 73   void (*xFunc)(s
2c5d0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
2c5e0 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75  int,sqlite3_valu
2c5f0 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78  e**),.  void (*x
2c600 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63 6f  Step)(sqlite3_co
2c610 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69 74  ntext*,int,sqlit
2c620 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20 76  e3_value**),.  v
2c630 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73 71  oid (*xFinal)(sq
2c640 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 0a  lite3_context*).
2c650 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
2c660 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2c670 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  2(.  sqlite3 *db
2c680 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  ,.  const char *
2c690 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20  zFunctionName,. 
2c6a0 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74   int nArg,.  int
2c6b0 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69   eTextRep,.  voi
2c6c0 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20  d *pApp,.  void 
2c6d0 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33  (*xFunc)(sqlite3
2c6e0 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71  _context*,int,sq
2c6f0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a  lite3_value**),.
2c700 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28    void (*xStep)(
2c710 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2c720 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2c730 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2c740 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f  xFinal)(sqlite3_
2c750 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f 69  context*),.  voi
2c760 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f 69  d(*xDestroy)(voi
2c770 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  d*).);../*.** CA
2c780 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e 63  PI3REF: Text Enc
2c790 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68 65  odings.**.** The
2c7a0 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66 69  se constant defi
2c7b0 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65 73  ne integer codes
2c7c0 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74 20   that represent 
2c7d0 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20 74  the various.** t
2c7e0 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73 75  ext encodings su
2c7f0 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69 74  pported by SQLit
2c800 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  e..*/.#define SQ
2c810 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20 20  LITE_UTF8       
2c820 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53 51      1.#define SQ
2c830 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20 20  LITE_UTF16LE    
2c840 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51      2.#define SQ
2c850 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20 20  LITE_UTF16BE    
2c860 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51      3.#define SQ
2c870 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20 20  LITE_UTF16      
2c880 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65 20      4    /* Use 
2c890 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65  native byte orde
2c8a0 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  r */.#define SQL
2c8b0 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20 20  ITE_ANY         
2c8c0 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69 74     5    /* sqlit
2c8d0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2c8e0 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66 69  on only */.#defi
2c8f0 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36 5f  ne SQLITE_UTF16_
2c900 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f 2a  ALIGNED  8    /*
2c910 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2c920 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20 2a  collation only *
2c930 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  /../*.** CAPI3RE
2c940 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46 75  F: Deprecated Fu
2c950 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52 45  nctions.** DEPRE
2c960 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65 73  CATED.**.** Thes
2c970 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65 20  e functions are 
2c980 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20 49  [deprecated].  I
2c990 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e 74  n order to maint
2c9a0 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73  ain.** backwards
2c9b0 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20 77   compatibility w
2c9c0 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c 20  ith older code, 
2c9d0 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20  these functions 
2c9e0 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f 20  continue .** to 
2c9f0 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20 48  be supported.  H
2ca00 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70 6c  owever, new appl
2ca10 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64 20  ications should 
2ca20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73 65  avoid.** the use
2ca30 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74 69   of these functi
2ca40 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65 6e  ons.  To help en
2ca50 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20 74  courage people t
2ca60 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e 67  o avoid.** using
2ca70 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2ca80 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f 69  , we are not goi
2ca90 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20 77  ng to tell you w
2caa0 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f 0a  hat they do..*/.
2cab0 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f 4f  #ifndef SQLITE_O
2cac0 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a 53  MIT_DEPRECATED.S
2cad0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2cae0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67 67   int sqlite3_agg
2caf0 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71 6c  regate_count(sql
2cb00 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2cb10 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2cb20 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78  D int sqlite3_ex
2cb30 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73 74  pired(sqlite3_st
2cb40 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2cb50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2cb60 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69 6e  te3_transfer_bin
2cb70 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
2cb80 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74 6d  mt*, sqlite3_stm
2cb90 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50 52  t*);.SQLITE_DEPR
2cba0 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69 74  ECATED int sqlit
2cbb0 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76 65  e3_global_recove
2cbc0 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45 5f  r(void);.SQLITE_
2cbd0 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64 20  DEPRECATED void 
2cbe0 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f 63  sqlite3_thread_c
2cbf0 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53 51  leanup(void);.SQ
2cc00 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44 20  LITE_DEPRECATED 
2cc10 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  int sqlite3_memo
2cc20 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a 29  ry_alarm(void(*)
2cc30 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f 69  (void*,sqlite3_i
2cc40 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a 2c  nt64,int),void*,
2cc50 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a  sqlite3_int64);.
2cc60 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41  #endif../*.** CA
2cc70 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69 6e  PI3REF: Obtainin
2cc80 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 50  g SQL Function P
2cc90 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73 0a  arameter Values.
2cca0 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e 67  **.** The C-lang
2ccb0 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74  uage implementat
2ccc0 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63 74  ion of SQL funct
2ccd0 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61  ions and aggrega
2cce0 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69 73  tes uses.** this
2ccf0 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61 63   set of interfac
2cd00 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61 63  e routines to ac
2cd10 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65 74  cess the paramet
2cd20 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a 20  er values on.** 
2cd30 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72 20  the function or 
2cd40 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a 2a  aggregate..**.**
2cd50 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72 20   The xFunc (for 
2cd60 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e 73  scalar functions
2cd70 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72 20  ) or xStep (for 
2cd80 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72 61  aggregates) para
2cd90 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73 71  meters.** to [sq
2cda0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2cdb0 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71  ction()] and [sq
2cdc0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2cdd0 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64 65  ction16()].** de
2cde0 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20 74  fine callbacks t
2cdf0 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68  hat implement th
2ce00 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20  e SQL functions 
2ce10 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e 0a  and aggregates..
2ce20 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61 6d  ** The 3rd param
2ce30 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63 61  eter to these ca
2ce40 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61 72  llbacks is an ar
2ce50 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73 20  ray of pointers 
2ce60 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65 64  to.** [protected
2ce70 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20   sqlite3_value] 
2ce80 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65 20  objects.  There 
2ce90 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33 5f  is one [sqlite3_
2cea0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66 6f  value] object fo
2ceb0 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d 65  r.** each parame
2cec0 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20 66  ter to the SQL f
2ced0 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65 20  unction.  These 
2cee0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2cef0 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74 20  d to.** extract 
2cf00 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65 20  values from the 
2cf10 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20  [sqlite3_value] 
2cf20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20 54  objects..**.** T
2cf30 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77 6f  hese routines wo
2cf40 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70 72  rk only with [pr
2cf50 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2cf60 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e 0a  value] objects..
2cf70 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20 74  ** Any attempt t
2cf80 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75 74  o use these rout
2cf90 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70 72  ines on an [unpr
2cfa0 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
2cfb0 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63 74  value].** object
2cfc0 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64 65   results in unde
2cfd0 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e 0a  fined behavior..
2cfe0 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75  **.** ^These rou
2cff0 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74 20  tines work just 
2d000 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73 70  like the corresp
2d010 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20 61  onding [column a
2d020 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d  ccess functions]
2d030 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74 20  .** except that 
2d040 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   these routines 
2d050 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b 70  take a single [p
2d060 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2d070 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a 2a  _value] object.*
2d080 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65 61  * pointer instea
2d090 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33 5f  d of a [sqlite3_
2d0a0 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20 61  stmt*] pointer a
2d0b0 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f  nd an integer co
2d0c0 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a 0a  lumn number..**.
2d0d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
2d0e0 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20 69  value_text16() i
2d0f0 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63 74  nterface extract
2d100 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  s a UTF-16 strin
2d110 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74 69  g.** in the nati
2d120 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f 66  ve byte-order of
2d130 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69 6e   the host machin
2d140 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69  e.  ^The.** sqli
2d150 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2d160 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  be() and sqlite3
2d170 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65 28  _value_text16le(
2d180 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2d190 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20 73  extract UTF-16 s
2d1a0 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65 6e  trings as big-en
2d1b0 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65 2d  dian and little-
2d1c0 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69 76  endian respectiv
2d1d0 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ely..**.** ^(The
2d1e0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 6e   sqlite3_value_n
2d1f0 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69 6e  umeric_type() in
2d200 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74 73  terface attempts
2d210 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75 6d   to apply.** num
2d220 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74 6f  eric affinity to
2d230 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68 69   the value.  Thi
2d240 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e 20  s means that an 
2d250 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d 61  attempt is.** ma
2d260 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74 68  de to convert th
2d270 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69 6e  e value to an in
2d280 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69 6e  teger or floatin
2d290 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a 20  g point.  If.** 
2d2a0 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69 6f  such a conversio
2d2b0 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77 69  n is possible wi
2d2c0 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69 6e  thout loss of in
2d2d0 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f 74  formation (in ot
2d2e0 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69 66  her.** words, if
2d2f0 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61 20   the value is a 
2d300 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f 6b  string that look
2d310 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72 29  s like a number)
2d320 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f 6e  .** then the con
2d330 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66 6f  version is perfo
2d340 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73 65  rmed.  Otherwise
2d350 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20 6f   no conversion o
2d360 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b 53  ccurs..** The [S
2d370 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c 20  QLITE_INTEGER | 
2d380 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72 20  datatype] after 
2d390 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72 65  conversion is re
2d3a0 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20  turned.)^.**.** 
2d3b0 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74 69  Please pay parti
2d3c0 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e 20  cular attention 
2d3d0 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61 74  to the fact that
2d3e0 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65 74   the pointer ret
2d3f0 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b 73  urned.** from [s
2d400 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
2d410 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76  b()], [sqlite3_v
2d420 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f 72  alue_text()], or
2d430 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  .** [sqlite3_val
2d440 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61 6e  ue_text16()] can
2d450 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64 20   be invalidated 
2d460 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74 20  by a subsequent 
2d470 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69  call to.** [sqli
2d480 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73 28  te3_value_bytes(
2d490 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c  )], [sqlite3_val
2d4a0 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20 5b  ue_bytes16()], [
2d4b0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2d4c0 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73 71  xt()],.** or [sq
2d4d0 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74  lite3_value_text
2d4e0 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  16()]..**.** The
2d4f0 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73 74  se routines must
2d500 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2d510 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2d520 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66 75  as.** the SQL fu
2d530 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70 70  nction that supp
2d540 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74 65  lied the [sqlite
2d550 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d 65  3_value*] parame
2d560 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 76  ters..*/.const v
2d570 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61 6c  oid *sqlite3_val
2d580 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f  ue_blob(sqlite3_
2d590 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c  value*);.int sql
2d5a0 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2d5b0 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2d5c0 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61  ;.int sqlite3_va
2d5d0 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c 69  lue_bytes16(sqli
2d5e0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f 75  te3_value*);.dou
2d5f0 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ble sqlite3_valu
2d600 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65 33  e_double(sqlite3
2d610 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2d620 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74 28  lite3_value_int(
2d630 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b  sqlite3_value*);
2d640 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 73  .sqlite3_int64 s
2d650 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2d660 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  64(sqlite3_value
2d670 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67 6e  *);.const unsign
2d680 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  ed char *sqlite3
2d690 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c 69  _value_text(sqli
2d6a0 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f 6e  te3_value*);.con
2d6b0 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
2d6c0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73 71  _value_text16(sq
2d6d0 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63  lite3_value*);.c
2d6e0 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74  onst void *sqlit
2d6f0 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c  e3_value_text16l
2d700 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  e(sqlite3_value*
2d710 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73  );.const void *s
2d720 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2d730 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76 61  t16be(sqlite3_va
2d740 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69 74  lue*);.int sqlit
2d750 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73 71  e3_value_type(sq
2d760 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 69  lite3_value*);.i
2d770 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt sqlite3_value
2d780 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73 71  _numeric_type(sq
2d790 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 0a  lite3_value*);..
2d7a0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2d7b0 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74 65  Obtain Aggregate
2d7c0 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65 78   Function Contex
2d7d0 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65 6e  t.**.** Implemen
2d7e0 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72 65  tations of aggre
2d7f0 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69 6f  gate SQL functio
2d800 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20 72  ns use this.** r
2d810 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63 61  outine to alloca
2d820 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73 74  te memory for st
2d830 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61 74  oring their stat
2d840 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  e..**.** ^The fi
2d850 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71 6c  rst time the sql
2d860 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2d870 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75 74  ontext(C,N) rout
2d880 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a 2a  ine is called .*
2d890 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75 6c  * for a particul
2d8a0 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  ar aggregate fun
2d8b0 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a 2a  ction, SQLite.**
2d8c0 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66 20   allocates N of 
2d8d0 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20 6f  memory, zeroes o
2d8e0 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c 20  ut that memory, 
2d8f0 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70 6f  and returns a po
2d900 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
2d910 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e 20  new memory. ^On 
2d920 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73 65  second and subse
2d930 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a 2a  quent calls to.*
2d940 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67  * sqlite3_aggreg
2d950 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66 6f  ate_context() fo
2d960 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72 65  r the same aggre
2d970 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69 6e  gate function in
2d980 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 73  stance,.** the s
2d990 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72 65  ame buffer is re
2d9a0 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65 33  turned.  Sqlite3
2d9b0 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65  _aggregate_conte
2d9c0 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c 79  xt() is normally
2d9d0 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65 20  .** called once 
2d9e0 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61 74  for each invocat
2d9f0 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65 70  ion of the xStep
2da00 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74 68   callback and th
2da10 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20 74  en one.** last t
2da20 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46 69  ime when the xFi
2da30 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  nal callback is 
2da40 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65 6e  invoked.  ^(When
2da50 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a 2a   no rows match.*
2da60 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20 71  * an aggregate q
2da70 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70 28  uery, the xStep(
2da80 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74 68  ) callback of th
2da90 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e 63  e aggregate func
2daa0 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e  tion.** implemen
2dab0 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72 20  tation is never 
2dac0 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e 61  called and xFina
2dad0 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65 78  l() is called ex
2dae0 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20 49  actly once..** I
2daf0 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20 73  n those cases, s
2db00 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65  qlite3_aggregate
2db10 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68 74  _context() might
2db20 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20 74   be called for t
2db30 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d 65  he.** first time
2db40 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46 69   from within xFi
2db50 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  nal().)^.**.** ^
2db60 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67 72  The sqlite3_aggr
2db70 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43 2c  egate_context(C,
2db80 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  N) routine retur
2db90 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ns a NULL pointe
2dba0 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65 73  r if N is.** les
2dbb0 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
2dbc0 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61 20  to zero or if a 
2dbd0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65 20  memory allocate 
2dbe0 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a 2a  error occurs..**
2dbf0 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e 74  .** ^(The amount
2dc00 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63 61   of space alloca
2dc10 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 61  ted by sqlite3_a
2dc20 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2dc30 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74 65  (C,N) is.** dete
2dc40 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e 20  rmined by the N 
2dc50 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69 72  parameter on fir
2dc60 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63 61  st successful ca
2dc70 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74 68  ll.  Changing th
2dc80 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e 20  e.** value of N 
2dc90 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63 61  in subsequent ca
2dca0 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61 67  ll to sqlite3_ag
2dcb0 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28  gregate_context(
2dcc0 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65 20  ) within.** the 
2dcd0 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20 66  same aggregate f
2dce0 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63 65  unction instance
2dcf0 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a 65   will not resize
2dd00 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61   the memory.** a
2dd10 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a 0a  llocation.)^.**.
2dd20 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f 6d  ** ^SQLite autom
2dd30 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20 74  atically frees t
2dd40 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
2dd50 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69 74  ted by .** sqlit
2dd60 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e  e3_aggregate_con
2dd70 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65 20  text() when the 
2dd80 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79 20  aggregate query 
2dd90 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a 2a  concludes..**.**
2dda0 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   The first param
2ddb0 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20 63  eter must be a c
2ddc0 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b 73  opy of the.** [s
2ddd0 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 7c  qlite3_context |
2dde0 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63 6f   SQL function co
2ddf0 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20 74  ntext] that is t
2de00 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65 74  he first paramet
2de10 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53 74  er.** to the xSt
2de20 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61 6c  ep or xFinal cal
2de30 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74 68  lback routine th
2de40 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74 68  at implements th
2de50 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20 66  e aggregate.** f
2de60 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54  unction..**.** T
2de70 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73 74  his routine must
2de80 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20   be called from 
2de90 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64 20  the same thread 
2dea0 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65 20  in which.** the 
2deb0 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66 75  aggregate SQL fu
2dec0 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e  nction is runnin
2ded0 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69  g..*/.void *sqli
2dee0 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2def0 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63 6f  ntext(sqlite3_co
2df00 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79 74  ntext*, int nByt
2df10 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  es);../*.** CAPI
2df20 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61 20  3REF: User Data 
2df30 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a 2a  For Functions.**
2df40 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2df50 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e 74  _user_data() int
2df60 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 61  erface returns a
2df70 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20   copy of.** the 
2df80 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61 73  pointer that was
2df90 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20 70   the pUserData p
2dfa0 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35 74  arameter (the 5t
2dfb0 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a 20  h parameter).** 
2dfc0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
2dfd0 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2dfe0 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69 74  )].** and [sqlit
2dff0 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2e000 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65 73  on16()] routines
2e010 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c 79   that originally
2e020 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20 74  .** registered t
2e030 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 64  he application d
2e040 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 2e  efined function.
2e050 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75 74  .**.** This rout
2e060 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c 6c  ine must be call
2e070 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d 65  ed from the same
2e080 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63 68   thread in which
2e090 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2e0a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2e0b0 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2e0c0 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65  .*/.void *sqlite
2e0d0 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c 69  3_user_data(sqli
2e0e0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a 0a  te3_context*);..
2e0f0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
2e100 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
2e110 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e  ion For Function
2e120 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  s.**.** ^The sql
2e130 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62 5f  ite3_context_db_
2e140 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66 61  handle() interfa
2e150 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f 70  ce returns a cop
2e160 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69 6e  y of.** the poin
2e170 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74 61  ter to the [data
2e180 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
2e190 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d 65   (the 1st parame
2e1a0 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20 5b  ter).** of the [
2e1b0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66  sqlite3_create_f
2e1c0 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61 6e  unction()].** an
2e1d0 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74  d [sqlite3_creat
2e1e0 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d 20  e_function16()] 
2e1f0 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f 72  routines that or
2e200 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67 69  iginally.** regi
2e210 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c 69  stered the appli
2e220 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20 66  cation defined f
2e230 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c 69  unction..*/.sqli
2e240 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6e  te3 *sqlite3_con
2e250 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28 73  text_db_handle(s
2e260 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2e270 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
2e280 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78 69  F: Function Auxi
2e290 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a 2a  liary Data.**.**
2e2a0 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74   The following t
2e2b0 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61 79  wo functions may
2e2c0 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61 6c   be used by scal
2e2d0 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  ar SQL functions
2e2e0 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65   to.** associate
2e2f0 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20 61   metadata with a
2e300 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e 20  rgument values. 
2e310 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c 75  If the same valu
2e320 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a 2a  e is passed to.*
2e330 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f 63  * multiple invoc
2e340 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2e350 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20  me SQL function 
2e360 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78 65  during query exe
2e370 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a 2a  cution, under.**
2e380 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61 6e   some circumstan
2e390 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61 74  ces the associat
2e3a0 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79 20  ed metadata may 
2e3b0 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54 68  be preserved. Th
2e3c0 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73 65  is may.** be use
2e3d0 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c 20  d, for example, 
2e3e0 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61 72  to add a regular
2e3f0 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74 63  -expression matc
2e400 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20 66  hing scalar.** f
2e410 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f 6d  unction. The com
2e420 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f 66  piled version of
2e430 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78 70   the regular exp
2e440 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72 65  ression is store
2e450 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74 61  d as.** metadata
2e460 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74 68   associated with
2e470 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20 70   the SQL value p
2e480 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65 67  assed as the reg
2e490 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e 0a  ular expression.
2e4a0 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68 65  ** pattern.  The
2e4b0 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c 61   compiled regula
2e4c0 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61 6e  r expression can
2e4d0 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d 75   be reused on mu
2e4e0 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63 61  ltiple.** invoca
2e4f0 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61 6d  tions of the sam
2e500 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74 68  e function so th
2e510 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20  at the original 
2e520 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a 2a  pattern string.*
2e530 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64 20  * does not need 
2e540 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65 64  to be recompiled
2e550 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61 74   on each invocat
2e560 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ion..**.** ^The 
2e570 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64  sqlite3_get_auxd
2e580 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65 20  ata() interface 
2e590 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
2e5a0 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61 74  r to the metadat
2e5b0 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  a.** associated 
2e5c0 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 73  by the sqlite3_s
2e5d0 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75 6e  et_auxdata() fun
2e5e0 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20 4e  ction with the N
2e5f0 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 76  th argument.** v
2e600 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70 6c  alue to the appl
2e610 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e620 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e 6f  function. ^If no
2e630 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62 65   metadata has be
2e640 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e 20  en ever.** been 
2e650 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68 20  set for the Nth 
2e660 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65 20  argument of the 
2e670 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66 20  function, or if 
2e680 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e  the correspondin
2e690 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70 61  g.** function pa
2e6a0 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61 6e  rameter has chan
2e6b0 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d 65  ged since the me
2e6c0 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74 2c  ta-data was set,
2e6d0 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65 33  .** then sqlite3
2e6e0 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20 72  _get_auxdata() r
2e6f0 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f  eturns a NULL po
2e700 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
2e710 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  e sqlite3_set_au
2e720 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63  xdata() interfac
2e730 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74 61  e saves the meta
2e740 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64 20  data.** pointed 
2e750 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70 61  to by its 3rd pa
2e760 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20 6d  rameter as the m
2e770 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65 20  etadata for the 
2e780 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e 74  N-th.** argument
2e790 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2e7a0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2e7b0 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65 6e  tion.  Subsequen
2e7c0 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71  t.** calls to sq
2e7d0 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2e7e0 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72 6e  a() might return
2e7f0 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20 69   this data, if i
2e800 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65 65  t has.** not bee
2e810 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a 20  n destroyed..** 
2e820 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e 55  ^If it is not NU
2e830 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  LL, SQLite will 
2e840 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74 72  invoke the destr
2e850 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69 6f  uctor.** functio
2e860 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20 34  n given by the 4
2e870 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2e880 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78 64  sqlite3_set_auxd
2e890 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65 20  ata() on.** the 
2e8a0 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74 68  metadata when th
2e8b0 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20  e corresponding 
2e8c0 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65 74  function paramet
2e8d0 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f 72  er changes.** or
2e8e0 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73 74   when the SQL st
2e8f0 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74 65  atement complete
2e900 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f 6d  s, whichever com
2e910 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a 20  es first..**.** 
2e920 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20 74  SQLite is free t
2e930 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74 72  o call the destr
2e940 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20 6d  uctor and drop m
2e950 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a 2a  etadata on any.*
2e960 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20 61  * parameter of a
2e970 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20 61  ny function at a
2e980 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20 6f  ny time.  ^The o
2e990 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69 73  nly guarantee is
2e9a0 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65 73   that.** the des
2e9b0 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65 20  tructor will be 
2e9c0 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74 68  called before th
2e9d0 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64 72  e metadata is dr
2e9e0 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  opped..**.** ^(I
2e9f0 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74 61  n practice, meta
2ea00 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76 65  data is preserve
2ea10 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74 69  d between functi
2ea20 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a 20  on calls for.** 
2ea30 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61 74  expressions that
2ea40 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61 74   are constant at
2ea50 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20 54   compile time. T
2ea60 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69 74  his includes lit
2ea70 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20 61  eral.** values a
2ea80 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d 2e  nd [parameters].
2ea90 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  )^.**.** These r
2eaa0 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65 20  outines must be 
2eab0 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65 20  called from the 
2eac0 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20 77  same thread in w
2ead0 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c 20  hich.** the SQL 
2eae0 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e  function is runn
2eaf0 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71  ing..*/.void *sq
2eb00 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61 74  lite3_get_auxdat
2eb10 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  a(sqlite3_contex
2eb20 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69 64  t*, int N);.void
2eb30 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2eb40 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e  data(sqlite3_con
2eb50 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76 6f  text*, int N, vo
2eb60 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76 6f  id*, void (*)(vo
2eb70 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20 43  id*));.../*.** C
2eb80 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61 6e  API3REF: Constan
2eb90 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65 63  ts Defining Spec
2eba0 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20 42  ial Destructor B
2ebb0 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54 68  ehavior.**.** Th
2ebc0 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c 20  ese are special 
2ebd0 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20 64  values for the d
2ebe0 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20 69  estructor that i
2ebf0 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20 74  s passed in as t
2ec00 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67 75  he.** final argu
2ec10 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65 73  ment to routines
2ec20 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f 72   like [sqlite3_r
2ec30 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20 20  esult_blob()].  
2ec40 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63 74  ^If the destruct
2ec50 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20 69  or.** argument i
2ec60 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43 2c  s SQLITE_STATIC,
2ec70 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20 74   it means that t
2ec80 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e 74  he content point
2ec90 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a 2a  er is constant.*
2eca0 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65 72  * and will never
2ecb0 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f 65   change.  It doe
2ecc0 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
2ecd0 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54 68   destroyed.  ^Th
2ece0 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41 4e  e.** SQLITE_TRAN
2ecf0 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61 6e  SIENT value mean
2ed00 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74 65  s that the conte
2ed10 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20 63  nt will likely c
2ed20 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65 20  hange in.** the 
2ed30 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64 20  near future and 
2ed40 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f 75  that SQLite shou
2ed50 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e 20  ld make its own 
2ed60 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66 0a  private copy of.
2ed70 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 62  ** the content b
2ed80 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67 2e  efore returning.
2ed90 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65 64  .**.** The typed
2eda0 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79 20  ef is necessary 
2edb0 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20 70  to work around p
2edc0 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74 61  roblems in certa
2edd0 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69 6c  in.** C++ compil
2ede0 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65 74  ers.  See ticket
2edf0 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65 64   #2191..*/.typed
2ee00 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74 65  ef void (*sqlite
2ee10 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70  3_destructor_typ
2ee20 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66 69  e)(void*);.#defi
2ee30 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  ne SQLITE_STATIC
2ee40 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33 5f        ((sqlite3_
2ee50 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65 29  destructor_type)
2ee60 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  0).#define SQLIT
2ee70 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28 28  E_TRANSIENT   ((
2ee80 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63 74  sqlite3_destruct
2ee90 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a 0a  or_type)-1)../*.
2eea0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74  ** CAPI3REF: Set
2eeb0 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74 20  ting The Result 
2eec0 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74 69  Of An SQL Functi
2eed0 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72  on.**.** These r
2eee0 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65 64  outines are used
2eef0 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f 72   by the xFunc or
2ef00 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b   xFinal callback
2ef10 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65 6d  s that.** implem
2ef20 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ent SQL function
2ef30 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73  s and aggregates
2ef40 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69 74  .  See.** [sqlit
2ef50 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ef60 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74  on()] and [sqlit
2ef70 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69  e3_create_functi
2ef80 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20 61  on16()].** for a
2ef90 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
2efa0 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  ation..**.** The
2efb0 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f 72  se functions wor
2efc0 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b 65  k very much like
2efd0 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72 20   the [parameter 
2efe0 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79 20  binding] family 
2eff0 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73 20  of.** functions 
2f000 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61 6c  used to bind val
2f010 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72 61  ues to host para
2f020 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61 72  meters in prepar
2f030 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a  ed statements..*
2f040 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20 5b  * Refer to the [
2f050 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20 64  SQL parameter] d
2f060 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72  ocumentation for
2f070 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f   additional info
2f080 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rmation..**.** ^
2f090 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2f0a0 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72 66  lt_blob() interf
2f0b0 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73  ace sets the res
2f0c0 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20 61  ult from.** an a
2f0d0 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2f0e0 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62  ed function to b
2f0f0 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73 65  e the BLOB whose
2f100 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69 6e   content is poin
2f110 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68 65  ted.** to by the
2f120 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65   second paramete
2f130 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20 4e  r and which is N
2f140 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65 72   bytes long wher
2f150 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74 68  e N is the.** th
2f160 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  ird parameter..*
2f170 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f180 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f  3_result_zeroblo
2f190 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20 73  b() interfaces s
2f1a0 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66  et the result of
2f1b0 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61 74  .** the applicat
2f1c0 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2f1d0 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c 4f  tion to be a BLO
2f1e0 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c 6c  B containing all
2f1f0 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20 61   zero.** bytes a
2f200 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73 69  nd N bytes in si
2f210 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20 74  ze, where N is t
2f220 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  he value of the 
2f230 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a 2a  2nd parameter..*
2f240 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2f250 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65 28  3_result_double(
2f260 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2f270 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f 6d   the result from
2f280 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74 69  .** an applicati
2f290 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74  on-defined funct
2f2a0 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f 61  ion to be a floa
2f2b0 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65  ting point value
2f2c0 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62 79   specified.** by
2f2d0 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65 6e   its 2nd argumen
2f2e0 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  t..**.** ^The sq
2f2f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f300 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2f310 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f320 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 63  ) functions.** c
2f330 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d 65  ause the impleme
2f340 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  nted SQL functio
2f350 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 78  n to throw an ex
2f360 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51 4c  ception..** ^SQL
2f370 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74 72  ite uses the str
2f380 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20 62  ing pointed to b
2f390 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61 72  y the.** 2nd par
2f3a0 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74 65  ameter of sqlite
2f3b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28 29  3_result_error()
2f3c0 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75   or sqlite3_resu
2f3d0 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a 20  lt_error16().** 
2f3e0 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20 61  as the text of a
2f3f0 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65 2e  n error message.
2f400 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72 70    ^SQLite interp
2f410 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a 2a  rets the error.*
2f420 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e 67  * message string
2f430 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72 65   from sqlite3_re
2f440 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73 20  sult_error() as 
2f450 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a 2a  UTF-8. ^SQLite.*
2f460 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68 65  * interprets the
2f470 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71 6c   string from sql
2f480 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f490 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36 20  r16() as UTF-16 
2f4a0 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79 74  in native.** byt
2f4b0 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74 68  e order.  ^If th
2f4c0 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
2f4d0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65 73  r to sqlite3_res
2f4e0 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20 6f  ult_error().** o
2f4f0 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  r sqlite3_result
2f500 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e 65  _error16() is ne
2f510 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c 69  gative then SQLi
2f520 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65 20  te takes as the 
2f530 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67 65  error.** message
2f540 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68 72   all text up thr
2f550 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20 7a  ough the first z
2f560 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a 2a  ero character..*
2f570 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64 20  * ^If the third 
2f580 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c  parameter to sql
2f590 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f5a0 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  r() or.** sqlite
2f5b0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2f5c0 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69  () is non-negati
2f5d0 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20 74  ve then SQLite t
2f5e0 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a 2a  akes that many.*
2f5f0 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68 61  * bytes (not cha
2f600 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74 68  racters) from th
2f610 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20  e 2nd parameter 
2f620 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  as the error mes
2f630 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  sage..** ^The sq
2f640 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f650 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33  or() and sqlite3
2f660 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36 28  _result_error16(
2f670 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d 61  ).** routines ma
2f680 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f 70  ke a private cop
2f690 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 6d  y of the error m
2f6a0 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66 6f  essage text befo
2f6b0 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75 72  re.** they retur
2f6c0 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20 63  n.  Hence, the c
2f6d0 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  alling function 
2f6e0 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20 6f  can deallocate o
2f6f0 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65 20  r.** modify the 
2f700 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79 20  text after they 
2f710 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20 68  return without h
2f720 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  arm..** ^The sql
2f730 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f740 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69 6f  r_code() functio
2f750 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65 72  n changes the er
2f760 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74 75  ror code.** retu
2f770 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20 61  rned by SQLite a
2f780 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61 6e  s a result of an
2f790 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e 63   error in a func
2f7a0 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61 75  tion.  ^By defau
2f7b0 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f 72  lt,.** the error
2f7c0 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45 5f   code is SQLITE_
2f7d0 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73 65  ERROR.  ^A subse
2f7e0 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73 71  quent call to sq
2f7f0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2f800 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69 74  or().** or sqlit
2f810 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2f820 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20 65  6() resets the e
2f830 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51 4c  rror code to SQL
2f840 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a 2a  ITE_ERROR..**.**
2f850 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2f860 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69 6e  sult_toobig() in
2f870 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20 53  terface causes S
2f880 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20 61  QLite to throw a
2f890 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69 63  n error.** indic
2f8a0 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74 72  ating that a str
2f8b0 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20 74  ing or BLOB is t
2f8c0 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72 65  oo long to repre
2f8d0 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  sent..**.** ^The
2f8e0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2f8f0 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61 63  nomem() interfac
2f900 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65 20  e causes SQLite 
2f910 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72 6f  to throw an erro
2f920 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67 20  r.** indicating 
2f930 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61 6c  that a memory al
2f940 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64 2e  location failed.
2f950 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
2f960 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28 29  te3_result_int()
2f970 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73 20   interface sets 
2f980 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  the return value
2f990 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c 69  .** of the appli
2f9a0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2f9b0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74 68  unction to be th
2f9c0 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64 20  e 32-bit signed 
2f9d0 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75 65  integer.** value
2f9e0 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32 6e   given in the 2n
2f9f0 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e  d argument..** ^
2fa00 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  The sqlite3_resu
2fa10 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65 72  lt_int64() inter
2fa20 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2fa30 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66  turn value.** of
2fa40 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
2fa50 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f  -defined functio
2fa60 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d 62  n to be the 64-b
2fa70 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67 65  it signed intege
2fa80 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65 6e  r.** value given
2fa90 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67 75   in the 2nd argu
2faa0 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  ment..**.** ^The
2fab0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
2fac0 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63 65  null() interface
2fad0 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72 6e   sets the return
2fae0 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68 65   value.** of the
2faf0 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
2fb00 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f  ined function to
2fb10 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   be NULL..**.** 
2fb20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2fb30 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c 69  ult_text(), sqli
2fb40 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31  te3_result_text1
2fb50 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  6(),.** sqlite3_
2fb60 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65 28  result_text16le(
2fb70 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72  ), and sqlite3_r
2fb80 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28 29  esult_text16be()
2fb90 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 73   interfaces.** s
2fba0 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  et the return va
2fbb0 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c 69  lue of the appli
2fbc0 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66  cation-defined f
2fbd0 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a 2a  unction to be.**
2fbe0 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20 77   a text string w
2fbf0 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65 6e  hich is represen
2fc00 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55 54  ted as UTF-8, UT
2fc10 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74 65  F-16 native byte
2fc20 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d 31   order,.** UTF-1
2fc30 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e 2c  6 little endian,
2fc40 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20 65   or UTF-16 big e
2fc50 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69 76  ndian, respectiv
2fc60 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ely..** ^SQLite 
2fc70 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20 72  takes the text r
2fc80 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20 61  esult from the a
2fc90 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d 0a  pplication from.
2fca0 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d  ** the 2nd param
2fcb0 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c 69  eter of the sqli
2fcc0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 2a  te3_result_text*
2fcd0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
2fce0 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72 61  ^If the 3rd para
2fcf0 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71 6c  meter to the sql
2fd00 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2fd10 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  * interfaces.** 
2fd20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68 65  is negative, the
2fd30 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20 72  n SQLite takes r
2fd40 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d 20  esult text from 
2fd50 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65  the 2nd paramete
2fd60 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68 65  r.** through the
2fd70 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61 72   first zero char
2fd80 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74 68  acter..** ^If th
2fd90 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72 20  e 3rd parameter 
2fda0 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2fdb0 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2fdc0 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f 6e  rfaces.** is non
2fdd0 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e 20  -negative, then 
2fde0 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28 6e  as many bytes (n
2fdf0 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20 6f  ot characters) o
2fe00 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70 6f  f the text.** po
2fe10 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65 20  inted to by the 
2fe20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 72  2nd parameter ar
2fe30 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20 61  e taken as the a
2fe40 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e  pplication-defin
2fe50 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72  ed.** function r
2fe60 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68  esult..** ^If th
2fe70 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72 20  e 4th parameter 
2fe80 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f 72  to the sqlite3_r
2fe90 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65  esult_text* inte
2fea0 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71 6c  rfaces.** or sql
2feb0 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2fec0 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 70   is a non-NULL p
2fed0 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51 4c  ointer, then SQL
2fee0 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a 2a  ite calls that.*
2fef0 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74 68  * function as th
2ff00 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e 20  e destructor on 
2ff10 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f 42  the text or BLOB
2ff20 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74 20   result when it 
2ff30 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64 20  has.** finished 
2ff40 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2ff50 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2ff60 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2ff70 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ff80 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2ff90 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c 69  es or to.** sqli
2ffa0 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20  te3_result_blob 
2ffb0 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20 63  is the special c
2ffc0 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f 53  onstant SQLITE_S
2ffd0 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c 69  TATIC, then SQLi
2ffe0 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74 68  te.** assumes th
2fff0 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20 42  at the text or B
30000 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69 6e  LOB result is in
30010 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65 20   constant space 
30020 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a 20  and does not.** 
30030 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e 74  copy the content
30040 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74 65   of the paramete
30050 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65 73  r nor call a des
30060 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20 63  tructor on the c
30070 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20 69  ontent.** when i
30080 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 75  t has finished u
30090 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c 74  sing that result
300a0 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74 68  ..** ^If the 4th
300b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68   parameter to th
300c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
300d0 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63 65  _text* interface
300e0 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33 5f  s.** or sqlite3_
300f0 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20 74  result_blob is t
30100 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73 74  he special const
30110 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e 53  ant SQLITE_TRANS
30120 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51 4c  IENT.** then SQL
30130 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70 79  ite makes a copy
30140 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20 69   of the result i
30150 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69 6e  nto space obtain
30160 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d 20  ed from.** from 
30170 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28  [sqlite3_malloc(
30180 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65 74  )] before it ret
30190 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  urns..**.** ^The
301a0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
301b0 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61 63  value() interfac
301c0 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75 6c  e sets the resul
301d0 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c  t of.** the appl
301e0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
301f0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  function to be a
30200 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75 6e   copy the.** [un
30210 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
30220 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20  3_value] object 
30230 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
30240 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 20   2nd parameter. 
30250 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33   ^The.** sqlite3
30260 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29 20  _result_value() 
30270 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73 20  interface makes 
30280 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b 73  a copy of the [s
30290 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a 2a  qlite3_value].**
302a0 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73 71   so that the [sq
302b0 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70 65  lite3_value] spe
302c0 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70 61  cified in the pa
302d0 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61 6e  rameter may chan
302e0 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61 6c  ge or.** be deal
302f0 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73 71  located after sq
30300 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c  lite3_result_val
30310 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69 74  ue() returns wit
30320 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e 41  hout harm..** ^A
30330 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   [protected sqli
30340 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63  te3_value] objec
30350 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65 20  t may always be 
30360 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a 2a  used where an.**
30370 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73 71   [unprotected sq
30380 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a  lite3_value] obj
30390 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64 2c  ect is required,
303a0 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b 69   so either.** ki
303b0 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 76  nd of [sqlite3_v
303c0 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61 6e  alue] object can
303d0 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74 68   be used with th
303e0 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a  is interface..**
303f0 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f 75  .** If these rou
30400 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64  tines are called
30410 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68 65   from within the
30420 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65 61   different threa
30430 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f 6e  d.** than the on
30440 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65  e containing the
30450 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
30460 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 68  ined function th
30470 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20 74  at received.** t
30480 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 74  he [sqlite3_cont
30490 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74 68  ext] pointer, th
304a0 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e  e results are un
304b0 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69 64  defined..*/.void
304c0 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f   sqlite3_result_
304d0 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f 6e  blob(sqlite3_con
304e0 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69  text*, const voi
304f0 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a 29  d*, int, void(*)
30500 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73  (void*));.void s
30510 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64 6f  qlite3_result_do
30520 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e  uble(sqlite3_con
30530 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b 0a  text*, double);.
30540 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
30550 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74 65  ult_error(sqlite
30560 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e 73  3_context*, cons
30570 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a 76  t char*, int);.v
30580 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
30590 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69 74  lt_error16(sqlit
305a0 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
305b0 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a  st void*, int);.
305c0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
305d0 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69 67  ult_error_toobig
305e0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
305f0 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
30600 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e 6f  _result_error_no
30610 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  mem(sqlite3_cont
30620 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
30630 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
30640 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63 6f  _code(sqlite3_co
30650 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
30660 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
30670 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63 6f  t_int(sqlite3_co
30680 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76 6f  ntext*, int);.vo
30690 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  id sqlite3_resul
306a0 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33 5f  t_int64(sqlite3_
306b0 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74 65  context*, sqlite
306c0 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20 73  3_int64);.void s
306d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e 75  qlite3_result_nu
306e0 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ll(sqlite3_conte
306f0 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  xt*);.void sqlit
30700 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28 73  e3_result_text(s
30710 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30720 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69 6e   const char*, in
30730 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
30740 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
30750 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28 73  _result_text16(s
30760 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c  qlite3_context*,
30770 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e   const void*, in
30780 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 2a  t, void(*)(void*
30790 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  ));.void sqlite3
307a0 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
307b0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
307c0 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  *, const void*, 
307d0 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69 64  int,void(*)(void
307e0 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
307f0 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62  3_result_text16b
30800 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
30810 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
30820 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
30830 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
30840 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28  e3_result_value(
30850 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
30860 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  , sqlite3_value*
30870 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f  );.void sqlite3_
30880 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62 28  result_zeroblob(
30890 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
308a0 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a 2a  , int n);../*.**
308b0 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69 6e   CAPI3REF: Defin
308c0 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67 20  e New Collating 
308d0 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a 20  Sequences.**.** 
308e0 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73  ^These functions
308f0 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f 72   add, remove, or
30900 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c 61   modify a [colla
30910 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65 64  tion] associated
30920 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64 61  .** with the [da
30930 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
30940 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73 20  n] specified as 
30950 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
30960 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  nt..**.** ^The n
30970 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  ame of the colla
30980 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38 20  tion is a UTF-8 
30990 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73 71  string.** for sq
309a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
309b0 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71 6c  lation() and sql
309c0 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
309d0 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61 6e  ation_v2().** an
309e0 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69 6e  d a UTF-16 strin
309f0 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74 65  g in native byte
30a00 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69 74   order for sqlit
30a10 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
30a20 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f 6c  ion16()..** ^Col
30a30 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68 61  lation names tha
30a40 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c 20  t compare equal 
30a50 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73 71  according to [sq
30a60 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28 29  lite3_strnicmp()
30a70 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64 65  ] are.** conside
30a80 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73 61  red to be the sa
30a90 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20 5e  me name..**.** ^
30aa0 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75 6d  (The third argum
30ab0 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20 6d  ent (eTextRep) m
30ac0 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74 68  ust be one of th
30ad0 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a 20  e constants:.** 
30ae0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
30af0 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20 3c  LITE_UTF8],.** <
30b00 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
30b10 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b 53  6LE],.** <li> [S
30b20 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c 0a  QLITE_UTF16BE],.
30b30 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
30b40 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c 6c  UTF16], or.** <l
30b50 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31 36  i> [SQLITE_UTF16
30b60 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c 2f  _ALIGNED]..** </
30b70 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65 54  ul>)^.** ^The eT
30b80 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74 20  extRep argument 
30b90 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20 65  determines the e
30ba0 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69 6e  ncoding of strin
30bb0 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f 20  gs passed.** to 
30bc0 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75  the collating fu
30bd0 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 2c  nction callback,
30be0 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 5e   xCallback..** ^
30bf0 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  The [SQLITE_UTF1
30c00 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 55  6] and [SQLITE_U
30c10 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76 61  TF16_ALIGNED] va
30c20 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52 65  lues for eTextRe
30c30 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69 6e  p.** force strin
30c40 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20 77  gs to be UTF16 w
30c50 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65 20  ith native byte 
30c60 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20 5b  order..** ^The [
30c70 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c 49  SQLITE_UTF16_ALI
30c80 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72 20  GNED] value for 
30c90 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73 20  eTextRep forces 
30ca0 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69 6e  strings to begin
30cb0 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20 62  .** on an even b
30cc0 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a 0a  yte address..**.
30cd0 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20 61  ** ^The fourth a
30ce0 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20 69  rgument, pArg, i
30cf0 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  s an application
30d00 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74 68   data pointer th
30d10 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a 20  at is passed.** 
30d20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20 66  through as the f
30d30 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74 6f  irst argument to
30d40 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
30d50 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
30d60 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69 66  ..**.** ^The fif
30d70 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43 61  th argument, xCa
30d80 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f 69  llback, is a poi
30d90 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c 6c  nter to the coll
30da0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e 0a  ating function..
30db0 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f 6c  ** ^Multiple col
30dc0 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73  lating functions
30dd0 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65 72   can be register
30de0 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d  ed using the sam
30df0 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77 69  e name but.** wi
30e00 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54 65  th different eTe
30e10 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72 73  xtRep parameters
30e20 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c 6c   and SQLite will
30e30 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a 2a   use whichever.*
30e40 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  * function requi
30e50 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61 6d  res the least am
30e60 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72 61  ount of data tra
30e70 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 20  nsformation..** 
30e80 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61 63  ^If the xCallbac
30e90 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e 55  k argument is NU
30ea0 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c 6c  LL then the coll
30eb0 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69  ating function i
30ec0 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20 5e  s.** deleted.  ^
30ed0 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74 69  When all collati
30ee0 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61 76  ng functions hav
30ef0 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61 6d  ing the same nam
30f00 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a 2a  e are deleted,.*
30f10 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f 6e  * that collation
30f20 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75 73   is no longer us
30f30 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
30f40 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74   collating funct
30f50 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73 20  ion callback is 
30f60 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20 63  invoked with a c
30f70 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67 20  opy of the pArg 
30f80 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  .** application 
30f90 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e 64  data pointer and
30fa0 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e 67   with two string
30fb0 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69 6e  s in the encodin
30fc0 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  g specified.** b
30fd0 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20 61  y the eTextRep a
30fe0 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63 6f  rgument.  The co
30ff0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31000 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e 0a   must return an.
31010 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74 20  ** integer that 
31020 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65 72  is negative, zer
31030 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a 2a  o, or positive.*
31040 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20 73  * if the first s
31050 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74 68  tring is less th
31060 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f 72  an, equal to, or
31070 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74 68   greater than th
31080 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65 73  e second,.** res
31090 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63 6f  pectively.  A co
310a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
310b0 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65 74   must always ret
310c0 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e 73  urn the same ans
310d0 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68 65  wer.** given the
310e0 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20 49   same inputs.  I
310f0 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63 6f  f two or more co
31100 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
31110 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65 64  s are registered
31120 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65 20  .** to the same 
31130 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20 28  collation name (
31140 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74 20  using different 
31150 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73 29  eTextRep values)
31160 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75 73   then all.** mus
31170 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76 61  t give an equiva
31180 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65 6e  lent answer when
31190 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65 71   invoked with eq
311a0 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67 73  uivalent strings
311b0 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74 69  ..** The collati
311c0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74  ng function must
311d0 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f 77   obey the follow
311e0 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20 66  ing properties f
311f0 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e 67  or all.** string
31200 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a 2a  s A, B, and C:.*
31210 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ol>.** <li
31220 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20 42  > If A==B then B
31230 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66 20  ==A..** <li> If 
31240 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74 68  A==B and B==C th
31250 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69 3e  en A==C..** <li>
31260 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e 20   If A&lt;B THEN 
31270 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e 20  B&gt;A..** <li> 
31280 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42 26  If A&lt;B and B&
31290 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b 43  lt;C then A&lt;C
312a0 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ol>.**.**
312b0 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67 20   If a collating 
312c0 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20 61  function fails a
312d0 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65 20  ny of the above 
312e0 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64 20  constraints and 
312f0 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69 6e  that.** collatin
31300 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20 72  g function is  r
31310 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75 73  egistered and us
31320 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65 68  ed, then the beh
31330 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65 0a  avior of SQLite.
31340 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  ** is undefined.
31350 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
31360 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
31370 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73 20  tion_v2() works 
31380 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72 65  like sqlite3_cre
31390 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29 0a  ate_collation().
313a0 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64 69  ** with the addi
313b0 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78 44  tion that the xD
313c0 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b 20  estroy callback 
313d0 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70 41  is invoked on pA
313e0 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20 63  rg when.** the c
313f0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
31400 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  n is deleted..**
31410 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63   ^Collating func
31420 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74 65  tions are delete
31430 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65 20  d when they are 
31440 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c 61  overridden by la
31450 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20  ter.** calls to 
31460 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63 72  the collation cr
31470 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e 73  eation functions
31480 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a 20   or when the.** 
31490 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
314a0 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64 20  tion] is closed 
314b0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 63  using [sqlite3_c
314c0 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e  lose()]..**.** ^
314d0 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61 6c  The xDestroy cal
314e0 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74 3c  lback is <u>not<
314f0 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74 68  /u> called if th
31500 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 72  e .** sqlite3_cr
31510 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76  eate_collation_v
31520 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61 69  2() function fai
31530 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f 6e  ls.  Application
31540 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a 2a  s that invoke.**
31550 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31560 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20 77  collation_v2() w
31570 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20 78  ith a non-NULL x
31580 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e 74  Destroy argument
31590 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65 63   should .** chec
315a0 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f 64  k the return cod
315b0 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f 66  e and dispose of
315c0 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e   the application
315d0 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a 2a   data pointer.**
315e0 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74 68   themselves rath
315f0 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69 6e  er than expectin
31600 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61 6c  g SQLite to deal
31610 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68 65   with it for the
31620 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64 69  m..** This is di
31630 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76 65  fferent from eve
31640 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65 20  ry other SQLite 
31650 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
31660 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a 2a  inconsistency .*
31670 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74 65  * is unfortunate
31680 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20 63   but cannot be c
31690 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20 62  hanged without b
316a0 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72 64  reaking backward
316b0 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69 6c  s .** compatibil
316c0 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  ity..**.** See a
316d0 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f 63  lso:  [sqlite3_c
316e0 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
316f0 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
31700 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
31710 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  16()]..*/.int sq
31720 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
31730 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65  lation(.  sqlite
31740 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61  3*, .  const cha
31750 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74  r *zName, .  int
31760 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f   eTextRep, .  vo
31770 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28  id *pArg,.  int(
31780 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a  *xCompare)(void*
31790 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
317a0 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a  ,int,const void*
317b0 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33  ).);.int sqlite3
317c0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
317d0 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33 2a  n_v2(.  sqlite3*
317e0 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  , .  const char 
317f0 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20 65  *zName, .  int e
31800 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69 64  TextRep, .  void
31810 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a 78   *pArg,.  int(*x
31820 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c 69  Compare)(void*,i
31830 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 69  nt,const void*,i
31840 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29 2c  nt,const void*),
31850 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f  .  void(*xDestro
31860 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e 74  y)(void*).);.int
31870 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
31880 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20 73  collation16(.  s
31890 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e 73  qlite3*, .  cons
318a0 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a 20  t void *zName,. 
318b0 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20 0a   int eTextRep, .
318c0 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20    void *pArg,.  
318d0 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28 76  int(*xCompare)(v
318e0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
318f0 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76  oid*,int,const v
31900 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  oid*).);../*.** 
31910 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61 74  CAPI3REF: Collat
31920 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c 62  ion Needed Callb
31930 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20 61  acks.**.** ^To a
31940 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20 72  void having to r
31950 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c 6c  egister all coll
31960 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73 20  ation sequences 
31970 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61 73  before a databas
31980 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65 64  e.** can be used
31990 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c 62  , a single callb
319a0 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61 79  ack function may
319b0 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20 77   be registered w
319c0 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61  ith the.** [data
319d0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
319e0 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77   to be invoked w
319f0 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65 66  henever an undef
31a00 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a 2a  ined collation.*
31a10 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72 65  * sequence is re
31a20 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  quired..**.** ^I
31a30 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69  f the function i
31a40 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73 69  s registered usi
31a50 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f 63  ng the sqlite3_c
31a60 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
31a70 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20 69  ) API,.** then i
31a80 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65 20  t is passed the 
31a90 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69 6e  names of undefin
31aa0 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  ed collation seq
31ab0 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e 67  uences as string
31ac0 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e 20  s.** encoded in 
31ad0 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69 74  UTF-8. ^If sqlit
31ae0 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65  e3_collation_nee
31af0 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64 2c  ded16() is used,
31b00 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61 72  .** the names ar
31b10 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46 2d  e passed as UTF-
31b20 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e 61  16 in machine na
31b30 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72 2e  tive byte order.
31b40 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 65  .** ^A call to e
31b50 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20 72  ither function r
31b60 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69 73  eplaces the exis
31b70 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d 6e  ting collation-n
31b80 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e 0a  eeded callback..
31b90 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68 65  **.** ^(When the
31ba0 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
31bb0 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74 20  oked, the first 
31bc0 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64 20  argument passed 
31bd0 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66 20  is a copy.** of 
31be0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
31bf0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  ent to sqlite3_c
31c00 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
31c10 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  ) or.** sqlite3_
31c20 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
31c30 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f 6e  16().  The secon
31c40 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68  d argument is th
31c50 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f  e database.** co
31c60 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20 74  nnection.  The t
31c70 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69 73  hird argument is
31c80 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   one of [SQLITE_
31c90 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f 55  UTF8], [SQLITE_U
31ca0 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  TF16BE],.** or [
31cb0 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d 2c  SQLITE_UTF16LE],
31cc0 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65 20   indicating the 
31cd0 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20 66  most desirable f
31ce0 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c 61  orm of the colla
31cf0 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63 65  tion.** sequence
31d00 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69 72   function requir
31d10 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68 20  ed.  The fourth 
31d20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68 65  parameter is the
31d30 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
31d40 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74 69  required collati
31d50 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a 2a  on sequence.)^.*
31d60 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61 63  *.** The callbac
31d70 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75 6c  k function shoul
31d80 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20 64  d register the d
31d90 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f 6e  esired collation
31da0 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69 74   using.** [sqlit
31db0 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74  e3_create_collat
31dc0 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  ion()], [sqlite3
31dd0 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f  _create_collatio
31de0 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b 73  n16()], or.** [s
31df0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
31e00 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a 2a  llation_v2()]..*
31e10 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f  /.int sqlite3_co
31e20 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28 0a  llation_needed(.
31e30 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76    sqlite3*, .  v
31e40 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a 29  oid*, .  void(*)
31e50 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c  (void*,sqlite3*,
31e60 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f 6e  int eTextRep,con
31e70 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e 74  st char*).);.int
31e80 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74 69   sqlite3_collati
31e90 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20 73  on_needed16(.  s
31ea0 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64  qlite3*, .  void
31eb0 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f 69  *,.  void(*)(voi
31ec0 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74 20  d*,sqlite3*,int 
31ed0 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20 76  eTextRep,const v
31ee0 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65 66  oid*).);..#ifdef
31ef0 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44 45   SQLITE_HAS_CODE
31f00 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  C./*.** Specify 
31f10 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20 65  the key for an e
31f20 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61 73  ncrypted databas
31f30 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e 65  e.  This routine
31f40 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63 61   should be.** ca
31f50 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65 72  lled right after
31f60 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 2e   sqlite3_open().
31f70 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65 20  .**.** The code 
31f80 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 69  to implement thi
31f90 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76 61  s API is not ava
31fa0 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70 75  ilable in the pu
31fb0 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a 20  blic release.** 
31fc0 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e  of SQLite..*/.in
31fd0 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a 20  t sqlite3_key(. 
31fe0 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20   sqlite3 *db,   
31ff0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
32000 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20 62  /* Database to b
32010 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63  e rekeyed */.  c
32020 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c  onst void *pKey,
32030 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a   int nKey     /*
32040 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a 0a   The key */.);..
32050 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68 65  /*.** Change the
32060 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e 20   key on an open 
32070 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74 68  database.  If th
32080 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62 61  e current databa
32090 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e 63  se is not.** enc
320a0 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f 75  rypted, this rou
320b0 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79 70  tine will encryp
320c0 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d 3d  t it.  If pNew==
320d0 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74 68  0 or nNew==0, th
320e0 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69 73  e.** database is
320f0 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a 2a   decrypted..**.*
32100 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69 6d  * The code to im
32110 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50 49  plement this API
32120 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62 6c   is not availabl
32130 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63 20  e in the public 
32140 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53 51  release.** of SQ
32150 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  Lite..*/.int sql
32160 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73 71  ite3_rekey(.  sq
32170 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
32180 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20               /* 
32190 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20 72  Database to be r
321a0 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e 73  ekeyed */.  cons
321b0 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69 6e  t void *pKey, in
321c0 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54 68  t nKey     /* Th
321d0 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b 0a  e new key */.);.
321e0 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74  ./*.** Specify t
321f0 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65  he activation ke
32200 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74 61  y for a SEE data
32210 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
32220 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
32230 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f 75  e of the SEE rou
32240 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b 2e  tines will work.
32250 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .*/.void sqlite3
32260 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a 20  _activate_see(. 
32270 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50 61   const char *zPa
32280 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20 20  ssPhrase        
32290 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70 68  /* Activation ph
322a0 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64 69  rase */.);.#endi
322b0 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54 45  f..#ifdef SQLITE
322c0 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f 2a  _ENABLE_CEROD./*
322d0 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65 20  .** Specify the 
322e0 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20 66  activation key f
322f0 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61 62  or a CEROD datab
32300 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a 2a  ase.  Unless .**
32310 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e 65   activated, none
32320 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72 6f   of the CEROD ro
32330 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
32340 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
32350 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f 64  3_activate_cerod
32360 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  (.  const char *
32370 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20 20  zPassPhrase     
32380 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e     /* Activation
32390 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65   phrase */.);.#e
323a0 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ndif../*.** CAPI
323b0 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45 78  3REF: Suspend Ex
323c0 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53 68  ecution For A Sh
323d0 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20 54  ort Time.**.** T
323e0 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65 70  he sqlite3_sleep
323f0 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  () function caus
32400 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20 74  es the current t
32410 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e 64  hread to suspend
32420 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66 6f   execution.** fo
32430 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75 6d  r at least a num
32440 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
32450 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69 6e  nds specified in
32460 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e 0a   its parameter..
32470 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70 65  **.** If the ope
32480 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64 6f  rating system do
32490 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20 73  es not support s
324a0 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77 69  leep requests wi
324b0 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f 6e  th.** millisecon
324c0 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69 6f  d time resolutio
324d0 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d 65  n, then the time
324e0 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65 64   will be rounded
324f0 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e 65   up to.** the ne
32500 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54 68  arest second. Th
32510 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c 6c  e number of mill
32520 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65  iseconds of slee
32530 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72 65  p actually.** re
32540 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68 65  quested from the
32550 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74 65   operating syste
32560 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a  m is returned..*
32570 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d 70  *.** ^SQLite imp
32580 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e 74  lements this int
32590 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69 6e  erface by callin
325a0 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a 2a  g the xSleep().*
325b0 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65 20  * method of the 
325c0 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65 33  default [sqlite3
325d0 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20 49  _vfs] object.  I
325e0 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20 6d  f the xSleep() m
325f0 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65 20  ethod.** of the 
32600 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20 6e  default VFS is n
32610 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 63  ot implemented c
32620 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f 74  orrectly, or not
32630 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74 0a   implemented at.
32640 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68 65  ** all, then the
32650 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71 6c   behavior of sql
32660 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61 79  ite3_sleep() may
32670 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74 68   deviate from th
32680 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a  e description.**
32690 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75 73   in the previous
326a0 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f 0a   paragraphs..*/.
326b0 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  int sqlite3_slee
326c0 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  p(int);../*.** C
326d0 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66  API3REF: Name Of
326e0 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c 64   The Folder Hold
326f0 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46 69  ing Temporary Fi
32700 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20 74  les.**.** ^(If t
32710 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69 61  his global varia
32720 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ble is made to p
32730 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e 67  oint to a string
32740 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68 65   which is.** the
32750 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64 65   name of a folde
32760 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63 74  r (a.k.a. direct
32770 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20 74  ory), then all t
32780 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a 2a  emporary files.*
32790 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51 4c  * created by SQL
327a0 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20 61  ite when using a
327b0 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69 74   built-in [sqlit
327c0 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a 2a  e3_vfs | VFS].**
327d0 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64 20   will be placed 
327e0 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f 72  in that director
327f0 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20 76  y.)^  ^If this v
32800 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61 20  ariable.** is a 
32810 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68  NULL pointer, th
32820 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f 72  en SQLite perfor
32830 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72 20  ms a search for 
32840 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a 2a  an appropriate.*
32850 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65  * temporary file
32860 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a 2a   directory..**.*
32870 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66 65  * It is not safe
32880 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64 69   to read or modi
32890 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c 65  fy this variable
328a0 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e   in more than on
328b0 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20 61  e.** thread at a
328c0 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e 6f   time.  It is no
328d0 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20 6f  t safe to read o
328e0 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76 61  r modify this va
328f0 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20 5b  riable.** if a [
32900 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
32910 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75 73  ion] is being us
32920 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20 74  ed at the same t
32930 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61 74  ime in a separat
32940 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a 20  e.** thread..** 
32950 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20 74  It is intended t
32960 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62 6c  hat this variabl
32970 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a 2a  e be set once.**
32980 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f 63   as part of proc
32990 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  ess initializati
329a0 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61 6e  on and before an
329b0 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  y SQLite interfa
329c0 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 68  ce.** routines h
329d0 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ave been called 
329e0 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76 61  and that this va
329f0 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75 6e  riable remain un
32a00 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72 65  changed.** there
32a10 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  after..**.** ^Th
32a20 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
32a30 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
32a40 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73 20  may modify this 
32a50 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61 75  variable and cau
32a60 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69 6e  se.** it to poin
32a70 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  t to memory obta
32a80 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
32a90 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46 75  e3_malloc].  ^Fu
32aa0 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74 68  rthermore,.** th
32ab0 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
32ac0 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
32ad0 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20 74  always assumes t
32ae0 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a 2a  hat any string.*
32af0 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72 69  * that this vari
32b00 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20 69  able points to i
32b10 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72 79  s held in memory
32b20 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 0a   obtained from .
32b30 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  ** [sqlite3_mall
32b40 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61 67  oc] and the prag
32b50 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20 74  ma may attempt t
32b60 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d 6f  o free that memo
32b70 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71 6c  ry.** using [sql
32b80 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20 48  ite3_free]..** H
32b90 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76 61  ence, if this va
32ba0 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66 69  riable is modifi
32bb0 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69 74  ed directly, eit
32bc0 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62 65  her it should be
32bd0 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f 72  .** made NULL or
32be0 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20 74   made to point t
32bf0 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e 65  o memory obtaine
32c00 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f  d from [sqlite3_
32c10 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65 6c  malloc].** or el
32c20 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74 68  se the use of th
32c30 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64 69  e [temp_store_di
32c40 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d 20  rectory pragma] 
32c50 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64 65  should be avoide
32c60 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58 54  d..*/.SQLITE_EXT
32c70 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ERN char *sqlite
32c80 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72 79  3_temp_directory
32c90 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
32ca0 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74 6f  F: Test For Auto
32cb0 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a 20  -Commit Mode.** 
32cc0 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f 63  KEYWORDS: {autoc
32cd0 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a 2a  ommit mode}.**.*
32ce0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 67  * ^The sqlite3_g
32cf0 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29 20  et_autocommit() 
32d00 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e  interface return
32d10 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a 2a  s non-zero or.**
32d20 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69 76   zero if the giv
32d30 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  en database conn
32d40 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73 20  ection is or is 
32d50 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d 69  not in autocommi
32d60 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70 65  t mode,.** respe
32d70 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f 63  ctively.  ^Autoc
32d80 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f 6e  ommit mode is on
32d90 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20   by default..** 
32da0 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64 65  ^Autocommit mode
32db0 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79 20   is disabled by 
32dc0 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65 6d  a [BEGIN] statem
32dd0 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f 6d  ent..** ^Autocom
32de0 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d 65  mit mode is re-e
32df0 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f 4d  nabled by a [COM
32e00 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41 43  MIT] or [ROLLBAC
32e10 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65 72  K]..**.** If cer
32e20 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65 72  tain kinds of er
32e30 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61 20  rors occur on a 
32e40 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69 6e  statement within
32e50 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d 65   a multi-stateme
32e60 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69 6f  nt.** transactio
32e70 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75 64  n (errors includ
32e80 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c 4c  ing [SQLITE_FULL
32e90 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ], [SQLITE_IOERR
32ea0 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e 4f  ],.** [SQLITE_NO
32eb0 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42 55  MEM], [SQLITE_BU
32ec0 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54 45  SY], and [SQLITE
32ed0 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68 65  _INTERRUPT]) the
32ee0 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61 63  n the.** transac
32ef0 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72 6f  tion might be ro
32f00 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d 61  lled back automa
32f10 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f 6e  tically.  The on
32f20 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69 6e  ly way to.** fin
32f30 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53 51  d out whether SQ
32f40 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61 6c  Lite automatical
32f50 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 74  ly rolled back t
32f60 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 61  he transaction a
32f70 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  fter.** an error
32f80 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73 20   is to use this 
32f90 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
32fa0 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65 61  If another threa
32fb0 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61 75  d changes the au
32fc0 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73 20  tocommit status 
32fd0 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65 0a  of the database.
32fe0 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77 68  ** connection wh
32ff0 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65  ile this routine
33000 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68 65   is running, the
33010 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
33020 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e  ue.** is undefin
33030 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  ed..*/.int sqlit
33040 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69  e3_get_autocommi
33050 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a  t(sqlite3*);../*
33060 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
33070 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65 20  nd The Database 
33080 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65 70  Handle Of A Prep
33090 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a 2a  ared Statement.*
330a0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
330b0 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74 65  3_db_handle inte
330c0 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68  rface returns th
330d0 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
330e0 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a 2a  ection] handle.*
330f0 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70 72  * to which a [pr
33100 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33110 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68 65  ] belongs.  ^The
33120 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
33130 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72 6e  ction].** return
33140 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64 62  ed by sqlite3_db
33150 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20 73  _handle is the s
33160 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ame [database co
33170 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68 61  nnection].** tha
33180 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74 20  t was the first 
33190 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20 74  argument.** to t
331a0 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70  he [sqlite3_prep
331b0 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20 28  are_v2()] call (
331c0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 29  or its variants)
331d0 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20 74   that was used t
331e0 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65 20  o.** create the 
331f0 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68 65  statement in the
33200 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a 2f   first place..*/
33210 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74 65  .sqlite3 *sqlite
33220 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c 69  3_db_handle(sqli
33230 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a  te3_stmt*);../*.
33240 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6e  ** CAPI3REF: Fin
33250 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70 61  d the next prepa
33260 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  red statement.**
33270 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66  .** ^This interf
33280 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70 6f  ace returns a po
33290 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65 78  inter to the nex
332a0 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  t [prepared stat
332b0 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a 20  ement] after.** 
332c0 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65 64  pStmt associated
332d0 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62   with the [datab
332e0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
332f0 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74 20  pDb.  ^If pStmt 
33300 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e 20  is NULL.** then 
33310 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 72  this interface r
33320 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65 72  eturns a pointer
33330 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70 72   to the first pr
33340 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
33350 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20 77  .** associated w
33360 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73 65  ith the database
33370 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62 2e   connection pDb.
33380 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72 65    ^If no prepare
33390 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 73  d statement.** s
333a0 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f 6e  atisfies the con
333b0 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73 20  ditions of this 
333c0 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74 75  routine, it retu
333d0 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20  rns NULL..**.** 
333e0 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f  The [database co
333f0 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74 65  nnection] pointe
33400 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74 6f  r D in a call to
33410 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65 78  .** [sqlite3_nex
33420 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75 73  t_stmt(D,S)] mus
33430 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f 70  t refer to an op
33440 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  en database.** c
33450 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69 6e  onnection and in
33460 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73 74   particular must
33470 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20 70   not be a NULL p
33480 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69 74  ointer..*/.sqlit
33490 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65 33  e3_stmt *sqlite3
334a0 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69 74  _next_stmt(sqlit
334b0 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65 33  e3 *pDb, sqlite3
334c0 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a  _stmt *pStmt);..
334d0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
334e0 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c 62  Commit And Rollb
334f0 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f 6e  ack Notification
33500 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a   Callbacks.**.**
33510 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
33520 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74 65  mmit_hook() inte
33530 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73 20  rface registers 
33540 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75  a callback.** fu
33550 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76  nction to be inv
33560 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61 20  oked whenever a 
33570 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b  transaction is [
33580 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74 74  COMMIT | committ
33590 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61 6c  ed]..** ^Any cal
335a0 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20 70  lback set by a p
335b0 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f 20  revious call to 
335c0 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f 68  sqlite3_commit_h
335d0 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68 65  ook().** for the
335e0 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
335f0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
33600 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68 65  rridden..** ^The
33610 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
33620 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66 61  k_hook() interfa
33630 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20 63  ce registers a c
33640 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
33650 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
33660 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72 61  d whenever a tra
33670 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f 4c  nsaction is [ROL
33680 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20 62  LBACK | rolled b
33690 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ack]..** ^Any ca
336a0 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
336b0 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
336c0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
336d0 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20  k_hook().** for 
336e0 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
336f0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
33700 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e  overridden..** ^
33710 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65 6e  The pArg argumen
33720 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72 6f  t is passed thro
33730 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c 62  ugh to the callb
33740 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ack..** ^If the 
33750 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63 6f  callback on a co
33760 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74 69  mmit hook functi
33770 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  on returns non-z
33780 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68 65  ero,.** then the
33790 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76 65   commit is conve
337a0 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c 6c  rted into a roll
337b0 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  back..**.** ^The
337c0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
337d0 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64 20  hook(D,C,P) and 
337e0 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63 6b  sqlite3_rollback
337f0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75 6e  _hook(D,C,P) fun
33800 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72 6e  ctions.** return
33810 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74 20   the P argument 
33820 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f 75  from the previou
33830 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73 61  s call of the sa
33840 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6f  me function.** o
33850 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61  n the same [data
33860 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
33870 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a   D, or NULL for.
33880 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61 6c  ** the first cal
33890 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63 74  l for each funct
338a0 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20  ion on D..**.** 
338b0 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d 70  The callback imp
338c0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74  lementation must
338d0 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67   not do anything
338e0 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66   that will modif
338f0 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  y.** the databas
33900 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61  e connection tha
33910 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63 61  t invoked the ca
33920 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63 74  llback.  Any act
33930 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69 66  ions.** to modif
33940 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  y the database c
33950 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20 62  onnection must b
33960 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69 6c  e deferred until
33970 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63 6f   after the.** co
33980 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65 20  mpletion of the 
33990 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
339a0 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67 67   call that trigg
339b0 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74 0a  ered the commit.
339c0 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 68  ** or rollback h
339d0 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73 74  ook in the first
339e0 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65 20   place..** Note 
339f0 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
33a00 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
33a10 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33a20 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
33a30 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
33a40 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
33a50 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
33a60 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
33a70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
33a80 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20 4e  ^Registering a N
33a90 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69 73  ULL function dis
33aa0 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62 61  ables the callba
33ab0 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e 20  ck..**.** ^When 
33ac0 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 20  the commit hook 
33ad0 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65  callback routine
33ae0 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20 74   returns zero, t
33af0 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f  he [COMMIT].** o
33b00 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c 6f  peration is allo
33b10 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65 20  wed to continue 
33b20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20 74  normally.  ^If t
33b30 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a 2a  he commit hook.*
33b40 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a 65  * returns non-ze
33b50 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43 4f  ro, then the [CO
33b60 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72 74  MMIT] is convert
33b70 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c 42  ed into a [ROLLB
33b80 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f  ACK]..** ^The ro
33b90 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20 69  llback hook is i
33ba0 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c 6c  nvoked on a roll
33bb0 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c 74  back that result
33bc0 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74 0a  s from a commit.
33bd0 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69 6e  ** hook returnin
33be0 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73 74  g non-zero, just
33bf0 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65 20   as it would be 
33c00 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20 72  with any other r
33c10 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e  ollback..**.** ^
33c20 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65 73  For the purposes
33c30 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61 20   of this API, a 
33c40 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 73  transaction is s
33c50 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65 6e  aid to have been
33c60 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  .** rolled back 
33c70 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20 22  if an explicit "
33c80 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65 6d  ROLLBACK" statem
33c90 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64 2c  ent is executed,
33ca0 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72 20   or.** an error 
33cb0 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63 61  or constraint ca
33cc0 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69 74  uses an implicit
33cd0 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63 63   rollback to occ
33ce0 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c 6c  ur..** ^The roll
33cf0 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69 73  back callback is
33d00 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66 20   not invoked if 
33d10 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73  a transaction is
33d20 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
33d30 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62 65  y rolled back be
33d40 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62 61  cause the databa
33d50 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
33d60 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 53   closed..**.** S
33d70 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c  ee also the [sql
33d80 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b  ite3_update_hook
33d90 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ()] interface..*
33da0 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  /.void *sqlite3_
33db0 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c 69  commit_hook(sqli
33dc0 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f 69  te3*, int(*)(voi
33dd0 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f 69  d*), void*);.voi
33de0 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62  d *sqlite3_rollb
33df0 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65 33  ack_hook(sqlite3
33e00 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64 20  *, void(*)(void 
33e10 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a  *), void*);../*.
33e20 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61 74  ** CAPI3REF: Dat
33e30 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69 63  a Change Notific
33e40 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73 0a  ation Callbacks.
33e50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
33e60 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29  e3_update_hook()
33e70 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
33e80 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
33e90 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74 68  function.** with
33ea0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
33eb0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e 74  onnection] ident
33ec0 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69 72  ified by the fir
33ed0 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74  st argument.** t
33ee0 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68 65  o be invoked whe
33ef0 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20 75  never a row is u
33f00 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64  pdated, inserted
33f10 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20   or deleted..** 
33f20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73 65  ^Any callback se
33f30 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73 20  t by a previous 
33f40 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75 6e  call to this fun
33f50 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68 65  ction.** for the
33f60 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20 63   same database c
33f70 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76 65  onnection is ove
33f80 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20 5e  rridden..**.** ^
33f90 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  The second argum
33fa0 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65 72  ent is a pointer
33fb0 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f 6e   to the function
33fc0 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e 20   to invoke when 
33fd0 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64 61  a.** row is upda
33fe0 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f 72  ted, inserted or
33ff0 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54 68   deleted..** ^Th
34000 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
34010 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
34020 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68   is a copy of th
34030 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74  e third argument
34040 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 75  .** to sqlite3_u
34050 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a 2a  pdate_hook()..**
34060 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61 6c   ^The second cal
34070 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20 69  lback argument i
34080 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
34090 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49 54  _INSERT], [SQLIT
340a0 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f 72  E_DELETE],.** or
340b0 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45 5d   [SQLITE_UPDATE]
340c0 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74  , depending on t
340d0 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68 61  he operation tha
340e0 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61 6c  t caused the cal
340f0 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20 69  lback.** to be i
34100 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65 20  nvoked..** ^The 
34110 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
34120 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
34130 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74 61  e callback conta
34140 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  in pointers to t
34150 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 61  he.** database a
34160 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63 6f  nd table name co
34170 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66 66  ntaining the aff
34180 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e 54  ected row..** ^T
34190 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61 63  he final callbac
341a0 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  k parameter is t
341b0 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
341c0 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74 68  e row..** ^In th
341d0 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70 64  e case of an upd
341e0 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68 65  ate, this is the
341f0 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20 74   [rowid] after t
34200 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73 20  he update takes 
34210 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  place..**.** ^(T
34220 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20 69  he update hook i
34230 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
34240 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73 74  en internal syst
34250 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a 2a  em tables are.**
34260 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e 20   modified (i.e. 
34270 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61 6e  sqlite_master an
34280 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e 63  d sqlite_sequenc
34290 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20  e).)^.**.** ^In 
342a0 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70 6c  the current impl
342b0 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65 20  ementation, the 
342c0 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20 69  update hook.** i
342d0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77 68  s not invoked wh
342e0 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20 72  en duplication r
342f0 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64 20  ows are deleted 
34300 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a 2a  because of an.**
34310 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c 20   [ON CONFLICT | 
34320 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50 4c  ON CONFLICT REPL
34330 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e 4e  ACE] clause.  ^N
34340 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74 65  or is the update
34350 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65 64   hook.** invoked
34360 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20 64   when rows are d
34370 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68 65  eleted using the
34380 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69 6d   [truncate optim
34390 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68 65  ization]..** The
343a0 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66 69   exceptions defi
343b0 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72 61  ned in this para
343c0 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61 6e  graph might chan
343d0 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a  ge in a future.*
343e0 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c  * release of SQL
343f0 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 75  ite..**.** The u
34400 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c 65  pdate hook imple
34410 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20 6e  mentation must n
34420 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20 74  ot do anything t
34430 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79 0a  hat will modify.
34440 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20  ** the database 
34450 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74 20  connection that 
34460 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64 61  invoked the upda
34470 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61 63  te hook.  Any ac
34480 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
34490 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
344a0 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
344b0 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
344c0 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
344d0 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
344e0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
344f0 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
34500 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74 65  gered the update
34510 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74   hook..** Note t
34520 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
34530 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
34540 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
34550 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
34560 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
34570 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
34580 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
34590 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
345a0 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
345b0 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64 61  The sqlite3_upda
345c0 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66  te_hook(D,C,P) f
345d0 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75 72  unction.** retur
345e0 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e  ns the P argumen
345f0 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69  t from the previ
34600 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20 74  ous call.** on t
34610 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61 73  he same [databas
34620 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 2c  e connection] D,
34630 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a 20   or NULL for.** 
34640 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20 6f  the first call o
34650 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  n D..**.** See a
34660 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65 33  lso the [sqlite3
34670 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d 20  _commit_hook()] 
34680 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f 6c  and [sqlite3_rol
34690 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a 2a  lback_hook()].**
346a0 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f 0a   interfaces..*/.
346b0 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75 70  void *sqlite3_up
346c0 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71 6c  date_hook(.  sql
346d0 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  ite3*, .  void(*
346e0 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63 68  )(void *,int ,ch
346f0 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72 20  ar const *,char 
34700 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33 5f  const *,sqlite3_
34710 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a 0a  int64),.  void*.
34720 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
34730 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44 69  EF: Enable Or Di
34740 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61 67  sable Shared Pag
34750 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59 57  er Cache.** KEYW
34760 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63 61  ORDS: {shared ca
34770 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69  che}.**.** ^(Thi
34780 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c 65  s routine enable
34790 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74 68  s or disables th
347a0 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68 65  e sharing of the
347b0 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65 0a   database cache.
347c0 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64 61  ** and schema da
347d0 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62 65  ta structures be
347e0 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65 20  tween [database 
347f0 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f 6e  connection | con
34800 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f 20  nections].** to 
34810 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61 73  the same databas
34820 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65 6e  e. Sharing is en
34830 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72 67  abled if the arg
34840 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a 2a  ument is true.**
34850 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69 66   and disabled if
34860 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69 73   the argument is
34870 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a 20   false.)^.**.** 
34880 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20 69  ^Cache sharing i
34890 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64 69  s enabled and di
348a0 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65 6e  sabled for an en
348b0 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a 2a  tire process..**
348c0 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e 67   This is a chang
348d0 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20 76  e as of SQLite v
348e0 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49 6e  ersion 3.5.0. In
348f0 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73 20   prior versions 
34900 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73 68  of SQLite,.** sh
34910 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c 65  aring was enable
34920 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66 6f  d or disabled fo
34930 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73 65  r each thread se
34940 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20  parately..**.** 
34950 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61 72  ^(The cache shar
34960 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79 20  ing mode set by 
34970 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 65  this interface e
34980 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73 65  ffects all subse
34990 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74  quent.** calls t
349a0 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28  o [sqlite3_open(
349b0 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65  )], [sqlite3_ope
349c0 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73 71  n_v2()], and [sq
349d0 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2e  lite3_open16()].
349e0 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61 74  .** Existing dat
349f0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
34a00 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20 74  s continue use t
34a10 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65 0a  he sharing mode.
34a20 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20 65  ** that was in e
34a30 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69 6d  ffect at the tim
34a40 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65 6e  e they were open
34a50 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ed.)^.**.** ^(Th
34a60 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72  is routine retur
34a70 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 69  ns [SQLITE_OK] i
34a80 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20 77  f shared cache w
34a90 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64 69  as enabled or di
34aa0 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65 73  sabled.** succes
34ab0 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72 72  sfully.  An [err
34ac0 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74 75  or code] is retu
34ad0 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e 29  rned otherwise.)
34ae0 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64 20  ^.**.** ^Shared 
34af0 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c 65  cache is disable
34b00 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42 75  d by default. Bu
34b10 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68 61  t this might cha
34b20 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72 65  nge in.** future
34b30 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
34b40 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ite.  Applicatio
34b50 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62 6f  ns that care abo
34b60 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61 63  ut shared.** cac
34b70 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75 6c  he setting shoul
34b80 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63 69  d set it explici
34b90 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 41  tly..**.** See A
34ba0 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53 68  lso:  [SQLite Sh
34bb0 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65 5d  ared-Cache Mode]
34bc0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
34bd0 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63 61  enable_shared_ca
34be0 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  che(int);../*.**
34bf0 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65 6d   CAPI3REF: Attem
34c00 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70 20  pt To Free Heap 
34c10 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68  Memory.**.** ^Th
34c20 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61 73  e sqlite3_releas
34c30 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65 72  e_memory() inter
34c40 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
34c50 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a 2a   free N bytes.**
34c60 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79 20   of heap memory 
34c70 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67 20  by deallocating 
34c80 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d 65  non-essential me
34c90 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 73  mory allocations
34ca0 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65 20  .** held by the 
34cb0 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72 79  database library
34cc0 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64 20  .   Memory used 
34cd0 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61 73  to cache databas
34ce0 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69 6d  e.** pages to im
34cf0 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e 63  prove performanc
34d00 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65 20  e is an example 
34d10 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c  of non-essential
34d20 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71 6c   memory..** ^sql
34d30 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d  ite3_release_mem
34d40 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74 68  ory() returns th
34d50 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
34d60 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65 64  s actually freed
34d70 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68 74  ,.** which might
34d80 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73 73   be more or less
34d90 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e 74   than the amount
34da0 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20 5e   requested..** ^
34db0 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65  The sqlite3_rele
34dc0 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f 75  ase_memory() rou
34dd0 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70 20  tine is a no-op 
34de0 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a 2a  returning zero.*
34df0 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20 6e  * if SQLite is n
34e00 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68  ot compiled with
34e10 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
34e20 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
34e30 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  T]..*/.int sqlit
34e40 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f 72  e3_release_memor
34e50 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  y(int);../*.** C
34e60 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65 20  API3REF: Impose 
34e70 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70 20  A Limit On Heap 
34e80 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  Size.**.** ^The 
34e90 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
34ea0 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74 65  p_limit64() inte
34eb0 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f 6f  rface sets and/o
34ec0 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a 2a  r queries the.**
34ed0 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20 74   soft limit on t
34ee0 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65 61  he amount of hea
34ef0 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d 61  p memory that ma
34f00 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20 62  y be allocated b
34f10 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53 51  y SQLite..** ^SQ
34f20 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f 20  Lite strives to 
34f30 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72 79  keep heap memory
34f40 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65 6c   utilization bel
34f50 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ow the soft heap
34f60 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65 64  .** limit by red
34f70 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65 72  ucing the number
34f80 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20 69   of pages held i
34f90 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  n the page cache
34fa0 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d 6f  .** as heap memo
34fb0 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f 61  ry usages approa
34fc0 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e 0a  ches the limit..
34fd0 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65 61  ** ^The soft hea
34fe0 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66 74  p limit is "soft
34ff0 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20 74  " because even t
35000 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74 72  hough SQLite str
35010 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a 20  ives to stay.** 
35020 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74 2c  below the limit,
35030 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64 20   it will exceed 
35040 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65 72  the limit rather
35050 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a 2a   than generate.*
35060 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f 4d  * an [SQLITE_NOM
35070 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20 6f  EM] error.  In o
35080 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65 20  ther words, the 
35090 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
350a0 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79 20  .** is advisory 
350b0 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  only..**.** ^The
350c0 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66 72   return value fr
350d0 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f  om sqlite3_soft_
350e0 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69  heap_limit64() i
350f0 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a 2a  s the size of.**
35100 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
35110 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74 68  imit prior to th
35120 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68 65  e call.  ^If the
35130 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20 6e   argument N is n
35140 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e 20  egative.** then 
35150 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61 64  no change is mad
35160 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68 65  e to the soft he
35170 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63 65  ap limit.  Hence
35180 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a 2a  , the current.**
35190 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f 66   size of the sof
351a0 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61 6e  t heap limit can
351b0 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20 62   be determined b
351c0 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73 71  y invoking.** sq
351d0 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f  lite3_soft_heap_
351e0 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20 61  limit64() with a
351f0 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d 65   negative argume
35200 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  nt..**.** ^If th
35210 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
35220 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73 6f  zero then the so
35230 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69 73  ft heap limit is
35240 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a   disabled..**.**
35250 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61 70   ^(The soft heap
35260 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65 6e   limit is not en
35270 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63 75  forced in the cu
35280 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61  rrent implementa
35290 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20 6f  tion.** if one o
352a0 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f 77  r more of follow
352b0 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20 61  ing conditions a
352c0 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20 3c  re true:.**.** <
352d0 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20  ul>.** <li> The 
352e0 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
352f0 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e 0a  is set to zero..
35300 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20 61  ** <li> Memory a
35310 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69 73  ccounting is dis
35320 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63 6f  abled using a co
35330 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68 65  mbination of the
35340 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65  .**      [sqlite
35350 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54  3_config]([SQLIT
35360 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54  E_CONFIG_MEMSTAT
35370 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d 74  US],...) start-t
35380 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a 2a  ime option and.*
35390 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c 49  *      the [SQLI
353a0 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53 54  TE_DEFAULT_MEMST
353b0 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  ATUS] compile-ti
353c0 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c 6c  me option..** <l
353d0 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69 76  i> An alternativ
353e0 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  e page cache imp
353f0 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20 73  lementation is s
35400 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a 2a  pecified using.*
35410 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33 5f  *      [sqlite3_
35420 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f  config]([SQLITE_
35430 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c 2e  CONFIG_PCACHE],.
35440 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  ..)..** <li> The
35450 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c 6f   page cache allo
35460 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20 6f  cates from its o
35470 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20 73  wn memory pool s
35480 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20 20  upplied.**      
35490 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  by [sqlite3_conf
354a0 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46  ig]([SQLITE_CONF
354b0 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e 2e  IG_PAGECACHE],..
354c0 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a 2a  .) rather than.*
354d0 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65 20  *      from the 
354e0 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e  heap..** </ul>)^
354f0 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e 67  .**.** Beginning
35500 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65 72   with SQLite ver
35510 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65 20  sion 3.7.3, the 
35520 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35530 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20 72  is enforced.** r
35540 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65  egardless of whe
35550 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65 20  ther or not the 
35560 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d  [SQLITE_ENABLE_M
35570 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e 54  EMORY_MANAGEMENT
35580 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  ].** compile-tim
35590 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76 6f  e option is invo
355a0 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c 49  ked.  With [SQLI
355b0 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59  TE_ENABLE_MEMORY
355c0 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a 2a  _MANAGEMENT],.**
355d0 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20 6c   the soft heap l
355e0 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65 64  imit is enforced
355f0 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72 79   on every memory
35600 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57 69   allocation.  Wi
35610 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54 45  thout.** [SQLITE
35620 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
35630 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65 20  ANAGEMENT], the 
35640 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20  soft heap limit 
35650 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65 64  is only enforced
35660 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79 20  .** when memory 
35670 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79 20  is allocated by 
35680 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e 20  the page cache. 
35690 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73 74   Testing suggest
356a0 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a 2a  s that because.*
356b0 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65  * the page cache
356c0 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69 6e   is the predomin
356d0 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72 20  ate memory user 
356e0 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74 0a  in SQLite, most.
356f0 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
35700 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64 65  will achieve ade
35710 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70 20  quate soft heap 
35720 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65 6e  limit enforcemen
35730 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68 65  t without.** the
35740 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45 5f   use of [SQLITE_
35750 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d 41  ENABLE_MEMORY_MA
35760 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a 2a  NAGEMENT]..**.**
35770 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e 63   The circumstanc
35780 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20 53  es under which S
35790 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f 72  QLite will enfor
357a0 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61 70  ce the soft heap
357b0 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63 68   limit may.** ch
357c0 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65 20  anges in future 
357d0 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c 69  releases of SQLi
357e0 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69  te..*/.sqlite3_i
357f0 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f 66  nt64 sqlite3_sof
35800 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 73  t_heap_limit64(s
35810 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29 3b  qlite3_int64 N);
35820 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
35830 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f 66  : Deprecated Sof
35840 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e 74  t Heap Limit Int
35850 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45 43  erface.** DEPREC
35860 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ATED.**.** This 
35870 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64 20  is a deprecated 
35880 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 5b  version of the [
35890 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61  sqlite3_soft_hea
358a0 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a 20  p_limit64()].** 
358b0 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69 73  interface.  This
358c0 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f 76   routine is prov
358d0 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72 69  ided for histori
358e0 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  cal compatibilit
358f0 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c 20  y.** only.  All 
35900 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  new applications
35910 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 0a   should use the.
35920 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74  ** [sqlite3_soft
35930 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d  _heap_limit64()]
35940 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68 65   interface rathe
35950 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65 2e  r than this one.
35960 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52 45  .*/.SQLITE_DEPRE
35970 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69 74  CATED void sqlit
35980 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69 6d  e3_soft_heap_lim
35990 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a 0a  it(int N);.../*.
359a0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78 74  ** CAPI3REF: Ext
359b0 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41 62  ract Metadata Ab
359c0 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66 20  out A Column Of 
359d0 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e 54  A Table.**.** ^T
359e0 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
359f0 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62 6f  rns metadata abo
35a00 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63 6f  ut a specific co
35a10 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69 66  lumn of a specif
35a20 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 74  ic.** database t
35a30 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65 20  able accessible 
35a40 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61 62  using the [datab
35a50 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
35a60 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65 64  handle.** passed
35a70 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66 75   as the first fu
35a80 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74 2e  nction argument.
35a90 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c 75  .**.** ^The colu
35aa0 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65 64  mn is identified
35ab0 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c 20   by the second, 
35ac0 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68  third and fourth
35ad0 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a 2a   parameters to.*
35ae0 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e 2e  * this function.
35af0 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72   ^The second par
35b00 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65 72  ameter is either
35b10 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
35b20 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69 2e   database.** (i.
35b30 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d 70  e. "main", "temp
35b40 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68 65  ", or an attache
35b50 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e 74  d database) cont
35b60 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63 69  aining the speci
35b70 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f 72  fied.** table or
35b80 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69 73   NULL. ^If it is
35b90 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c 20   NULL, then all 
35ba0 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61 73  attached databas
35bb0 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64 0a  es are searched.
35bc0 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c 65  ** for the table
35bd0 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65 20   using the same 
35be0 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20 62  algorithm used b
35bf0 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20 65  y the database e
35c00 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73 6f  ngine to.** reso
35c10 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64 20  lve unqualified 
35c20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65 73  table references
35c30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68 69  ..**.** ^The thi
35c40 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70 61  rd and fourth pa
35c50 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69 73  rameters to this
35c60 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74 68   function are th
35c70 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c 75  e table and colu
35c80 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74 68  mn.** name of th
35c90 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d 6e  e desired column
35ca0 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e 20  , respectively. 
35cb0 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73 65  Neither of these
35cc0 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20 6d   parameters.** m
35cd0 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a  ay be NULL..**.*
35ce0 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20 72  * ^Metadata is r
35cf0 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74 69  eturned by writi
35d00 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72 79  ng to the memory
35d10 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73 65   locations passe
35d20 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a 20  d as the 5th.** 
35d30 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20 70  and subsequent p
35d40 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
35d50 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e 79  s function. ^Any
35d60 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d 65   of these argume
35d70 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e 55  nts may be.** NU
35d80 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73  LL, in which cas
35d90 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  e the correspond
35da0 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20 6d  ing element of m
35db0 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74 74  etadata is omitt
35dc0 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c 6f  ed..**.** ^(<blo
35dd0 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61 62  ckquote>.** <tab
35de0 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a 2a  le border="1">.*
35df0 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61 6d  * <tr><th> Param
35e00 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75 74  eter <th> Output
35e10 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20 44  <br>Type <th>  D
35e20 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a 2a  escription.**.**
35e30 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c 74   <tr><td> 5th <t
35e40 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
35e50 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a 2a  td> Data type.**
35e60 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c 74   <tr><td> 6th <t
35e70 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20 3c  d> const char* <
35e80 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66 61  td> Name of defa
35e90 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ult collation se
35ea0 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c 74  quence.** <tr><t
35eb0 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 7th <td> int 
35ec0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
35ed0 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73 20  e if column has 
35ee0 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74  a NOT NULL const
35ef0 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74 64  raint.** <tr><td
35f00 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 8th <td> int  
35f10 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
35f20 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70 61   if column is pa
35f30 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41 52  rt of the PRIMAR
35f40 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74 64  Y KEY.** <tr><td
35f50 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20 20  > 9th <td> int  
35f60 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75 65         <td> True
35f70 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b 41   if column is [A
35f80 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a 2a  UTOINCREMENT].**
35f90 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f 62   </table>.** </b
35fa0 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
35fb0 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20 70  ** ^The memory p
35fc0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
35fd0 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e 74   character point
35fe0 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f 72  ers returned for
35ff0 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61 74   the.** declarat
36000 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f 6c  ion type and col
36010 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 20  lation sequence 
36020 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75 6e  is valid only un
36030 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a 20  til the next.** 
36040 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c 69  call to any SQLi
36050 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e 2e  te API function.
36060 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
36070 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20 69  pecified table i
36080 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69 65  s actually a vie
36090 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64  w, an [error cod
360a0 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  e] is returned..
360b0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73 70  **.** ^If the sp
360c0 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20 69  ecified column i
360d0 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64 22  s "rowid", "oid"
360e0 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61 6e   or "_rowid_" an
360f0 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45 52  d an.** [INTEGER
36100 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f   PRIMARY KEY] co
36110 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65 78  lumn has been ex
36120 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
36130 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  d, then the outp
36140 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
36150 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68 65   are set for the
36160 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
36170 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28 49  ared column. ^(I
36180 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a 2a  f there is no.**
36190 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c   explicitly decl
361a0 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50 52  ared [INTEGER PR
361b0 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75 6d  IMARY KEY] colum
361c0 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74 70  n, then the outp
361d0 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  ut.** parameters
361e0 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c 6c   are set as foll
361f0 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65 3e  ows:.**.** <pre>
36200 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79 70  .**     data typ
36210 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a 20  e: "INTEGER".** 
36220 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65      collation se
36230 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59 22  quence: "BINARY"
36240 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c 6c  .**     not null
36250 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d 61  : 0.**     prima
36260 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20 20  ry key: 1.**    
36270 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74 3a   auto increment:
36280 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a 2a   0.** </pre>)^.*
36290 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e 63  *.** ^(This func
362a0 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f 6e  tion may load on
362b0 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d 61  e or more schema
362c0 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65 20  s from database 
362d0 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a 20  files. If an.** 
362e0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75 72  error occurs dur
362f0 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73 73  ing this process
36300 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71 75  , or if the requ
36310 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20 63  ested table or c
36320 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74 20  olumn.** cannot 
36330 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65 72  be found, an [er
36340 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
36350 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72 72  urned and an err
36360 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74 0a  or message left.
36370 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61 62  ** in the [datab
36380 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
36390 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65 64  (to be retrieved
363a0 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 65   using sqlite3_e
363b0 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a 2a  rrmsg()).)^.**.*
363c0 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20 6f  * ^This API is o
363d0 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69 66  nly available if
363e0 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61 73   the library was
363f0 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20 74   compiled with t
36400 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e  he.** [SQLITE_EN
36410 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41  ABLE_COLUMN_META
36420 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63 65  DATA] C-preproce
36430 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66 69  ssor symbol defi
36440 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
36450 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d 6e  te3_table_column
36460 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71 6c  _metadata(.  sql
36470 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
36480 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e 6e           /* Conn
36490 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a 2f  ection handle */
364a0 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  .  const char *z
364b0 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20 2f  DbName,        /
364c0 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65 20  * Database name 
364d0 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f 6e  or NULL */.  con
364e0 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65 4e  st char *zTableN
364f0 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62 6c  ame,     /* Tabl
36500 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e 73  e name */.  cons
36510 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e 4e  t char *zColumnN
36520 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75 6d  ame,    /* Colum
36530 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61 72  n name */.  char
36540 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61 54   const **pzDataT
36550 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50 55  ype,    /* OUTPU
36560 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74 61  T: Declared data
36570 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72 20   type */.  char 
36580 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53 65  const **pzCollSe
36590 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55 54  q,     /* OUTPUT
365a0 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71 75  : Collation sequ
365b0 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 69  ence name */.  i
365c0 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20 20  nt *pNotNull,   
365d0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
365e0 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e 4f  TPUT: True if NO
365f0 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69 6e  T NULL constrain
36600 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69 6e  t exists */.  in
36610 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c 20  t *pPrimaryKey, 
36620 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54            /* OUT
36630 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f 6c  PUT: True if col
36640 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20 2a  umn part of PK *
36650 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69 6e  /.  int *pAutoin
36660 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  c               
36670 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65 20  /* OUTPUT: True 
36680 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75 74  if column is aut
36690 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a 29  o-increment */.)
366a0 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
366b0 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65 6e  F: Load An Exten
366c0 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73  sion.**.** ^This
366d0 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64 73   interface loads
366e0 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65 6e   an SQLite exten
366f0 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72 6f  sion library fro
36700 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c 65  m the named file
36710 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
36720 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
36730 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
36740 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61 64  attempts to load
36750 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65 78   an.** SQLite ex
36760 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20  tension library 
36770 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68 65  contained in the
36780 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a 0a   file zFile..**.
36790 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70 6f  ** ^The entry po
367a0 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a 2a  int is zProc..**
367b0 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20 30   ^zProc may be 0
367c0 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65 20  , in which case 
367d0 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
367e0 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20 64  entry point.** d
367f0 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c 69  efaults to "sqli
36800 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69 6e  te3_extension_in
36810 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  it"..** ^The sql
36820 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
36830 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20  ion() interface 
36840 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c 49  returns.** [SQLI
36850 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65 73  TE_OK] on succes
36860 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45 52  s and [SQLITE_ER
36870 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69 6e  ROR] if somethin
36880 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a 2a  g goes wrong..**
36890 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f 63   ^If an error oc
368a0 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d 73  curs and pzErrMs
368b0 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65 6e  g is not 0, then
368c0 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
368d0 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28  _load_extension(
368e0 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68 61  )] interface sha
368f0 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a 2a  ll attempt to.**
36900 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67 20   fill *pzErrMsg 
36910 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73 61  with error messa
36920 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20 69  ge text stored i
36930 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74 61  n memory.** obta
36940 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
36950 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54 68  e3_malloc()]. Th
36960 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69  e calling functi
36970 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72 65  on.** should fre
36980 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62 79  e this memory by
36990 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
369a0 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a  3_free()]..**.**
369b0 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64   ^Extension load
369c0 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61 62  ing must be enab
369d0 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  led using.** [sq
369e0 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
369f0 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 70  d_extension()] p
36a00 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67 20  rior to calling 
36a10 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74 68  this API,.** oth
36a20 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20  erwise an error 
36a30 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65 64  will be returned
36a40 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36a50 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65 6e   the [load_exten
36a60 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63 74  sion() SQL funct
36a70 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ion]..*/.int sql
36a80 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73  ite3_load_extens
36a90 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  ion(.  sqlite3 *
36aa0 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20  db,          /* 
36ab0 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73 69  Load the extensi
36ac0 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61 74  on into this dat
36ad0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
36ae0 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72   */.  const char
36af0 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20 4e   *zFile,    /* N
36b00 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72 65  ame of the share
36b10 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61 69  d library contai
36b20 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20 2a  ning extension *
36b30 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
36b40 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e 74  zProc,    /* Ent
36b50 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69 76  ry point.  Deriv
36b60 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69 66  ed from zFile if
36b70 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 70   0 */.  char **p
36b80 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f 2a  zErrMsg       /*
36b90 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73 61   Put error messa
36ba0 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20 30  ge here if not 0
36bb0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
36bc0 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
36bd0 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 73  r Disable Extens
36be0 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a 2a  ion Loading.**.*
36bf0 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f 20  * ^So as not to 
36c00 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68 6f  open security ho
36c10 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70 70  les in older app
36c20 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 61  lications that a
36c30 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65 64  re.** unprepared
36c40 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65 78   to deal with ex
36c50 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 2c  tension loading,
36c60 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73 20   and as a means 
36c70 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a 20  of disabling.** 
36c80 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
36c90 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74 69  g while evaluati
36ca0 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64 20  ng user-entered 
36cb0 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77 69  SQL, the followi
36cc0 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72 6f  ng API.** is pro
36cd0 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74 68  vided to turn th
36ce0 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64 5f  e [sqlite3_load_
36cf0 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65 63  extension()] mec
36d00 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f 66  hanism on and of
36d10 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e 73  f..**.** ^Extens
36d20 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20 6f  ion loading is o
36d30 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20 53  ff by default. S
36d40 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33 2e  ee ticket #1863.
36d50 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73 71  .** ^Call the sq
36d60 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f 61  lite3_enable_loa
36d70 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72 6f  d_extension() ro
36d80 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66 66  utine with onoff
36d90 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20 65  ==1.** to turn e
36da0 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
36db0 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74 20   on and call it 
36dc0 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74 6f  with onoff==0 to
36dd0 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63 6b   turn.** it back
36de0 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a 69   off again..*/.i
36df0 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62 6c  nt sqlite3_enabl
36e00 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  e_load_extension
36e10 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69 6e  (sqlite3 *db, in
36e20 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a  t onoff);../*.**
36e30 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f 6d   CAPI3REF: Autom
36e40 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53 74  atically Load St
36e50 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64 20  atically Linked 
36e60 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a 2a  Extensions.**.**
36e70 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63 65   ^This interface
36e80 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e 74   causes the xEnt
36e90 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74 69  ryPoint() functi
36ea0 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64  on to be invoked
36eb0 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65 77   for.** each new
36ec0 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
36ed0 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20 63  ction] that is c
36ee0 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64 65  reated.  The ide
36ef0 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a 2a  a here is that.*
36f00 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  * xEntryPoint() 
36f10 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f 69  is the entry poi
36f20 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63 61  nt for a statica
36f30 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69 74  lly linked SQLit
36f40 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20 74  e extension.** t
36f50 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75 74  hat is to be aut
36f60 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64 65  omatically loade
36f70 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20 64  d into all new d
36f80 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
36f90 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  ons..**.** ^(Eve
36fa0 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75 6e  n though the fun
36fb0 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65 20  ction prototype 
36fc0 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74 72  shows that xEntr
36fd0 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a 2a  yPoint() takes.*
36fe0 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20 61  * no arguments a
36ff0 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64 2c  nd returns void,
37000 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73 20   SQLite invokes 
37010 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
37020 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67 75  th three.** argu
37030 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63 74  ments and expect
37040 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72 65  s and integer re
37050 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20 73  sult as if the s
37060 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65 0a  ignature of the.
37070 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20 77  ** entry point w
37080 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73 3a  here as follows:
37090 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
370a0 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62 73  te><pre>.** &nbs
370b0 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50 6f  p;  int xEntryPo
370c0 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20 20  int(.** &nbsp;  
370d0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a 2a    sqlite3 *db,.*
370e0 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e 73  * &nbsp;    cons
370f0 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d 73  t char **pzErrMs
37100 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20  g,.** &nbsp;    
37110 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
37120 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e 65  ite3_api_routine
37130 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e 62  s *pThunk.** &nb
37140 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72 65  sp;  );.** </pre
37150 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e  ></blockquote>)^
37160 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 45  .**.** If the xE
37170 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69 6e  ntryPoint routin
37180 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e 20  e encounters an 
37190 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c 64  error, it should
371a0 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67 0a   make *pzErrMsg.
371b0 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 61  ** point to an a
371c0 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f 72  ppropriate error
371d0 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69 6e   message (obtain
371e0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
371f0 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a 20  _mprintf()]).** 
37200 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61 70  and return an ap
37210 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f 72  propriate [error
37220 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74 65   code].  ^SQLite
37230 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a 70   ensures that *p
37240 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e 55  zErrMsg.** is NU
37250 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69 6e  LL before callin
37260 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69 6e  g the xEntryPoin
37270 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  t().  ^SQLite wi
37280 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73 71  ll invoke.** [sq
37290 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f 6e  lite3_free()] on
372a0 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65 72   *pzErrMsg after
372b0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 72   xEntryPoint() r
372c0 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e 79  eturns.  ^If any
372d0 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28  .** xEntryPoint(
372e0 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72 72  ) returns an err
372f0 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  or, the [sqlite3
37300 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74  _open()], [sqlit
37310 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a 2a  e3_open16()],.**
37320 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65   or [sqlite3_ope
37330 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68 61  n_v2()] call tha
37340 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20 78  t provoked the x
37350 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69 6c  EntryPoint() wil
37360 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 43  l fail..**.** ^C
37370 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f 61  alling sqlite3_a
37380 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58 29  uto_extension(X)
37390 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20 70   with an entry p
373a0 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20 61  oint X that is a
373b0 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68 65  lready.** on the
373c0 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61 74   list of automat
373d0 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69 73  ic extensions is
373e0 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f   a harmless no-o
373f0 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f 69  p. ^No entry poi
37400 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63 61  nt.** will be ca
37410 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20 6f  lled more than o
37420 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61 74  nce for each dat
37430 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
37440 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64 2e   that is opened.
37450 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a  .**.** See also:
37460 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 5f   [sqlite3_reset_
37470 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37480 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  ]..*/.int sqlite
37490 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e  3_auto_extension
374a0 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50 6f  (void (*xEntryPo
374b0 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f 2a  int)(void));../*
374c0 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65  .** CAPI3REF: Re
374d0 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45 78  set Automatic Ex
374e0 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a  tension Loading.
374f0 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65  **.** ^This inte
37500 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20 61  rface disables a
37510 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78 74  ll automatic ext
37520 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75 73  ensions previous
37530 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64  ly.** registered
37540 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
37550 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 29  auto_extension()
37560 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  ]..*/.void sqlit
37570 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65 78  e3_reset_auto_ex
37580 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a 0a  tension(void);..
37590 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72 66  /*.** The interf
375a0 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74 75  ace to the virtu
375b0 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
375c0 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79 20  sm is currently 
375d0 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74 6f  considered.** to
375e0 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61 6c   be experimental
375f0 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63 65  .  The interface
37600 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69 6e   might change in
37610 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77 61   incompatible wa
37620 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20 69  ys..** If this i
37630 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72 20  s a problem for 
37640 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65 20  you, do not use 
37650 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61 74  the interface at
37660 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a 2a   this time..**.*
37670 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74 75  * When the virtu
37680 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e 69  al-table mechani
37690 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20 77  sm stabilizes, w
376a0 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20 74  e will declare t
376b0 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20  he.** interface 
376c0 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20 69  fixed, support i
376d0 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c 20  t indefinitely, 
376e0 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73 20  and remove this 
376f0 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a 0a  comment..*/../*.
37700 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75 73  ** Structures us
37710 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75 61  ed by the virtua
37720 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61 63  l table interfac
37730 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72  e.*/.typedef str
37740 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
37750 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a 74   sqlite3_vtab;.t
37760 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71  ypedef struct sq
37770 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
37780 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69   sqlite3_index_i
37790 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74 72  nfo;.typedef str
377a0 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61 62  uct sqlite3_vtab
377b0 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33 5f  _cursor sqlite3_
377c0 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79 70  vtab_cursor;.typ
377d0 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69  edef struct sqli
377e0 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69 74  te3_module sqlit
377f0 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a 2a  e3_module;../*.*
37800 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72 74  * CAPI3REF: Virt
37810 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63 74  ual Table Object
37820 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71  .** KEYWORDS: sq
37830 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76 69  lite3_module {vi
37840 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
37850 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 73  le}.**.** This s
37860 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74 69  tructure, someti
37870 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 22 76 69  mes called a "vi
37880 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75  rtual table modu
37890 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65 73  le", .** defines
378a0 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74   the implementat
378b0 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75 61  ion of a [virtua
378c0 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a 20  l tables].  .** 
378d0 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20 63  This structure c
378e0 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20 6f  onsists mostly o
378f0 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74 68  f methods for th
37900 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a 20  e module..**.** 
37910 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c 65  ^A virtual table
37920 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61 74   module is creat
37930 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69 6e  ed by filling in
37940 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a 2a   a persistent.**
37950 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
37960 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64 20  s structure and 
37970 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74 65  passing a pointe
37980 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61 6e  r to that instan
37990 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65  ce.** to [sqlite
379a0 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 28  3_create_module(
379b0 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 63  )] or [sqlite3_c
379c0 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28  reate_module_v2(
379d0 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67 69  )]..** ^The regi
379e0 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e 73  stration remains
379f0 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74 20   valid until it 
37a00 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20 61  is replaced by a
37a10 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d 6f   different.** mo
37a20 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74 68  dule or until th
37a30 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
37a40 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e 20  ection] closes. 
37a50 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a 20   The content.** 
37a60 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75 72  of this structur
37a70 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e 67  e must not chang
37a80 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72 65  e while it is re
37a90 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a 2a  gistered with.**
37aa0 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63 6f   any database co
37ab0 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74 72  nnection..*/.str
37ac0 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64 75  uct sqlite3_modu
37ad0 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72 73  le {.  int iVers
37ae0 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43 72  ion;.  int (*xCr
37af0 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c 20  eate)(sqlite3*, 
37b00 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20 20  void *pAux,.    
37b10 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61             int a
37b20 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  rgc, const char 
37b30 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20 20  *const*argv,.   
37b40 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c 69              sqli
37b50 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54 61  te3_vtab **ppVTa
37b60 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69 6e  b, char**);.  in
37b70 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73 71  t (*xConnect)(sq
37b80 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70 41  lite3*, void *pA
37b90 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20 20  ux,.            
37ba0 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f 6e     int argc, con
37bb0 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a 61  st char *const*a
37bc0 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20 20  rgv,.           
37bd0 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61 62      sqlite3_vtab
37be0 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72 2a   **ppVTab, char*
37bf0 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65 73  *);.  int (*xBes
37c00 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33 5f  tIndex)(sqlite3_
37c10 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c  vtab *pVTab, sql
37c20 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 2a  ite3_index_info*
37c30 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73 63  );.  int (*xDisc
37c40 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33 5f  onnect)(sqlite3_
37c50 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37c60 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29 28  int (*xDestroy)(
37c70 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56  sqlite3_vtab *pV
37c80 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4f  Tab);.  int (*xO
37c90 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74 61  pen)(sqlite3_vta
37ca0 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74 65  b *pVTab, sqlite
37cb0 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a 2a  3_vtab_cursor **
37cc0 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e 74  ppCursor);.  int
37cd0 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69 74   (*xClose)(sqlit
37ce0 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29  e3_vtab_cursor*)
37cf0 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74 65  ;.  int (*xFilte
37d00 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  r)(sqlite3_vtab_
37d10 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64 78  cursor*, int idx
37d20 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72 20  Num, const char 
37d30 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20 20  *idxStr,.       
37d40 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72 67           int arg
37d50 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  c, sqlite3_value
37d60 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74 20   **argv);.  int 
37d70 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65 33  (*xNext)(sqlite3
37d80 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b 0a  _vtab_cursor*);.
37d90 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73 71    int (*xEof)(sq
37da0 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f  lite3_vtab_curso
37db0 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 6f  r*);.  int (*xCo
37dc0 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  lumn)(sqlite3_vt
37dd0 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69  ab_cursor*, sqli
37de0 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69 6e  te3_context*, in
37df0 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 77  t);.  int (*xRow
37e00 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  id)(sqlite3_vtab
37e10 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74 65  _cursor*, sqlite
37e20 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64 29  3_int64 *pRowid)
37e30 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61 74  ;.  int (*xUpdat
37e40 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20  e)(sqlite3_vtab 
37e50 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33 5f  *, int, sqlite3_
37e60 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74 65  value **, sqlite
37e70 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69 6e  3_int64 *);.  in
37e80 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c 69  t (*xBegin)(sqli
37e90 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 29  te3_vtab *pVTab)
37ea0 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29  ;.  int (*xSync)
37eb0 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37ec0 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
37ed0 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33 5f  Commit)(sqlite3_
37ee0 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20 20  vtab *pVTab);.  
37ef0 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b 29  int (*xRollback)
37f00 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
37f10 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
37f20 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73 71  FindFunction)(sq
37f30 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74 61  lite3_vtab *pVta
37f40 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f 6e  b, int nArg, con
37f50 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 0a  st char *zName,.
37f60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37f70 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a 70         void (**p
37f80 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
37f90 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
37fa0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
37fb0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
37fc0 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41 72       void **ppAr
37fd0 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65 6e  g);.  int (*xRen
37fe0 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61  ame)(sqlite3_vta
37ff0 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74 20  b *pVtab, const 
38000 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 20 20 2f  char *zNew);.  /
38010 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62  * The methods ab
38020 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73 69  ove are in versi
38030 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69  on 1 of the sqli
38040 74 65 5f 6d 6f 64 75 6c 65 20 6f 62 6a 65 63 74  te_module object
38050 2e 20 54 68 6f 73 65 20 0a 20 20 2a 2a 20 62 65  . Those .  ** be
38060 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72 73  low are for vers
38070 69 6f 6e 20 32 20 61 6e 64 20 67 72 65 61 74 65  ion 2 and greate
38080 72 2e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53  r. */.  int (*xS
38090 61 76 65 70 6f 69 6e 74 29 28 73 71 6c 69 74 65  avepoint)(sqlite
380a0 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 69  3_vtab *pVTab, i
380b0 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  nt);.  int (*xRe
380c0 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f 76  lease)(sqlite3_v
380d0 74 61 62 20 2a 70 56 54 61 62 2c 20 69 6e 74 29  tab *pVTab, int)
380e0 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62  ;.  int (*xRollb
380f0 61 63 6b 54 6f 29 28 73 71 6c 69 74 65 33 5f 76  ackTo)(sqlite3_v
38100 74 61 62 20 2a 70 56 54 61 62 2c 20 69 6e 74 29  tab *pVTab, int)
38110 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ;.};../*.** CAPI
38120 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54 61  3REF: Virtual Ta
38130 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e 66  ble Indexing Inf
38140 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59 57  ormation.** KEYW
38150 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69 6e  ORDS: sqlite3_in
38160 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20 54  dex_info.**.** T
38170 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78  he sqlite3_index
38180 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65 20  _info structure 
38190 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75 63  and its substruc
381a0 74 75 72 65 73 20 69 73 20 75 73 65 64 20 61 73  tures is used as
381b0 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65 20   part.** of the 
381c0 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20  [virtual table] 
381d0 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a 20  interface to.** 
381e0 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  pass information
381f0 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69 76   into and receiv
38200 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f 6d  e the reply from
38210 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65 78   the [xBestIndex
38220 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 61  ].** method of a
38230 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 20   [virtual table 
38240 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66 69  module].  The fi
38250 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e 70  elds under **Inp
38260 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a 2a  uts** are the.**
38270 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73 74   inputs to xBest
38280 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72 65  Index and are re
38290 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74 49  ad-only.  xBestI
382a0 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74 73  ndex inserts its
382b0 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74 6f  .** results into
382c0 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a 2a   the **Outputs**
382d0 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20 5e   fields..**.** ^
382e0 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e 74  (The aConstraint
382f0 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64 73  [] array records
38300 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63 6f   WHERE clause co
38310 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68 65  nstraints of the
38320 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c   form:.**.** <bl
38330 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e 20  ockquote>column 
38340 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71 75  OP expr</blockqu
38350 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72 65  ote>.**.** where
38360 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c 20   OP is =, &lt;, 
38370 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72 20  &lt;=, &gt;, or 
38380 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65 20  &gt;=.)^  ^(The 
38390 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72 61  particular opera
383a0 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65 64  tor is.** stored
383b0 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b   in aConstraint[
383c0 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20 6f  ].op using one o
383d0 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45  f the.** [SQLITE
383e0 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e  _INDEX_CONSTRAIN
383f0 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49 4e  T_EQ | SQLITE_IN
38400 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 20  DEX_CONSTRAINT_ 
38410 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e 28  values].)^.** ^(
38420 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65  The index of the
38430 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72 65   column is store
38440 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72 61  d in.** aConstra
38450 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29 5e  int[].iColumn.)^
38460 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74 5b    ^(aConstraint[
38470 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55 45  ].usable is TRUE
38480 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72 20   if the.** expr 
38490 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  on the right-han
384a0 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65 76  d side can be ev
384b0 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68 75  aluated (and thu
384c0 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e 74  s the constraint
384d0 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20 61  .** is usable) a
384e0 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20 63  nd false if it c
384f0 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e  annot.)^.**.** ^
38500 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61 75  The optimizer au
38510 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76 65  tomatically inve
38520 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68 65  rts terms of the
38530 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20 63   form "expr OP c
38540 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d 61  olumn".** and ma
38550 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c 69  kes other simpli
38560 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68 65  fications to the
38570 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69 6e   WHERE clause in
38580 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a   an attempt to.*
38590 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57 48  * get as many WH
385a0 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d 73  ERE clause terms
385b0 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20 73   into the form s
385c0 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70 6f  hown above as po
385d0 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65 20  ssible..** ^The 
385e0 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61 72  aConstraint[] ar
385f0 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74 73  ray only reports
38600 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74 65   WHERE clause te
38610 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a 20  rms that are.** 
38620 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65 20  relevant to the 
38630 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74 75  particular virtu
38640 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20 71  al table being q
38650 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  ueried..**.** ^I
38660 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
38670 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63 6c   the ORDER BY cl
38680 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20 69  ause is stored i
38690 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a 2a  n aOrderBy[]..**
386a0 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20 61   ^Each term of a
386b0 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73 20  OrderBy records 
386c0 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20  a column of the 
386d0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 2e  ORDER BY clause.
386e0 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65 73  .**.** The [xBes
386f0 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20 6d  tIndex] method m
38700 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74 72  ust fill aConstr
38710 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74 68  aintUsage[] with
38720 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20   information.** 
38730 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61 6d  about what param
38740 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74 6f  eters to pass to
38750 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20 61   xFilter.  ^If a
38760 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e 0a  rgvIndex>0 then.
38770 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61 6e  ** the right-han
38780 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63 6f  d side of the co
38790 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f 6e  rresponding aCon
387a0 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76 61  straint[] is eva
387b0 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62 65  luated.** and be
387c0 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49 6e  comes the argvIn
387d0 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e 20  dex-th entry in 
387e0 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f 6e  argv.  ^(If aCon
387f0 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e 6f  straintUsage[].o
38800 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c 20  mit.** is true, 
38810 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72 61  then the constra
38820 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20 74  int is assumed t
38830 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64 6c  o be fully handl
38840 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69 72  ed