/ Hex Artifact Content
Login

Artifact e7bbcb330ced6b5e25c9db8089c2c77aaefadf7d:


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: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5160: 52 45 41 44 4f 4e 4c 59 5f 52 45 43 4f 56 45 52  READONLY_RECOVER
5170: 59 20 20 20 20 20 20 20 28 53 51 4c 49 54 45 5f  Y       (SQLITE_
5180: 52 45 41 44 4f 4e 4c 59 20 7c 20 28 31 3c 3c 38  READONLY | (1<<8
5190: 29 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  )).#define SQLIT
51a0: 45 5f 52 45 41 44 4f 4e 4c 59 5f 43 41 4e 54 4c  E_READONLY_CANTL
51b0: 4f 43 4b 20 20 20 20 20 20 20 28 53 51 4c 49 54  OCK       (SQLIT
51c0: 45 5f 52 45 41 44 4f 4e 4c 59 20 7c 20 28 32 3c  E_READONLY | (2<
51d0: 3c 38 29 29 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  <8))../*.** CAPI
51e0: 33 52 45 46 3a 20 46 6c 61 67 73 20 46 6f 72 20  3REF: Flags For 
51f0: 46 69 6c 65 20 4f 70 65 6e 20 4f 70 65 72 61 74  File Open Operat
5200: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
5210: 20 62 69 74 20 76 61 6c 75 65 73 20 61 72 65 20   bit values are 
5220: 69 6e 74 65 6e 64 65 64 20 66 6f 72 20 75 73 65  intended for use
5230: 20 69 6e 20 74 68 65 0a 2a 2a 20 33 72 64 20 70   in the.** 3rd p
5240: 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20  arameter to the 
5250: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32  [sqlite3_open_v2
5260: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 61 6e  ()] interface an
5270: 64 0a 2a 2a 20 69 6e 20 74 68 65 20 34 74 68 20  d.** in the 4th 
5280: 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65  parameter to the
5290: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 6f 66   xOpen method of
52a0: 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
52b0: 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2f  _vfs] object..*/
52c0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
52d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 20 20 20  OPEN_READONLY   
52e0: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 31        0x00000001
52f0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5300: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5310: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5320: 4f 50 45 4e 5f 52 45 41 44 57 52 49 54 45 20 20  OPEN_READWRITE  
5330: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 32        0x00000002
5340: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5350: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5360: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5370: 4f 50 45 4e 5f 43 52 45 41 54 45 20 20 20 20 20  OPEN_CREATE     
5380: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 30 34        0x00000004
5390: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
53a0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
53b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
53c0: 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43 4c 4f  OPEN_DELETEONCLO
53d0: 53 45 20 20 20 20 30 78 30 30 30 30 30 30 30 38  SE    0x00000008
53e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
53f0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5400: 4f 50 45 4e 5f 45 58 43 4c 55 53 49 56 45 20 20  OPEN_EXCLUSIVE  
5410: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 31 30        0x00000010
5420: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5430: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5440: 4f 50 45 4e 5f 41 55 54 4f 50 52 4f 58 59 20 20  OPEN_AUTOPROXY  
5450: 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32 30        0x00000020
5460: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
5470: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5480: 4f 50 45 4e 5f 4d 41 49 4e 5f 44 42 20 20 20 20  OPEN_MAIN_DB    
5490: 20 20 20 20 20 20 30 78 30 30 30 30 30 31 30 30        0x00000100
54a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
54b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
54c0: 4f 50 45 4e 5f 54 45 4d 50 5f 44 42 20 20 20 20  OPEN_TEMP_DB    
54d0: 20 20 20 20 20 20 30 78 30 30 30 30 30 32 30 30        0x00000200
54e0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
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 54 52 41 4e 53 49 45 4e 54 5f 44  OPEN_TRANSIENT_D
5510: 42 20 20 20 20 20 30 78 30 30 30 30 30 34 30 30  B     0x00000400
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 4d 41 49 4e 5f 4a 4f 55 52 4e 41  OPEN_MAIN_JOURNA
5550: 4c 20 20 20 20 20 30 78 30 30 30 30 30 38 30 30  L     0x00000800
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 45 4d 50 5f 4a 4f 55 52 4e 41  OPEN_TEMP_JOURNA
5590: 4c 20 20 20 20 20 30 78 30 30 30 30 31 30 30 30  L     0x00001000
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 53 55 42 4a 4f 55 52 4e 41 4c 20  OPEN_SUBJOURNAL 
55d0: 20 20 20 20 20 20 30 78 30 30 30 30 32 30 30 30        0x00002000
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 4d 41 53 54 45 52 5f 4a 4f 55 52  OPEN_MASTER_JOUR
5610: 4e 41 4c 20 20 20 30 78 30 30 30 30 34 30 30 30  NAL   0x00004000
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 4e 4f 4d 55 54 45 58 20 20 20 20  OPEN_NOMUTEX    
5650: 20 20 20 20 20 20 30 78 30 30 30 30 38 30 30 30        0x00008000
5660: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5670: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5680: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5690: 4f 50 45 4e 5f 46 55 4c 4c 4d 55 54 45 58 20 20  OPEN_FULLMUTEX  
56a0: 20 20 20 20 20 20 30 78 30 30 30 31 30 30 30 30        0x00010000
56b0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
56c0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
56d0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
56e0: 4f 50 45 4e 5f 53 48 41 52 45 44 43 41 43 48 45  OPEN_SHAREDCACHE
56f0: 20 20 20 20 20 20 30 78 30 30 30 32 30 30 30 30        0x00020000
5700: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5710: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5720: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5730: 4f 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48  OPEN_PRIVATECACH
5740: 45 20 20 20 20 20 30 78 30 30 30 34 30 30 30 30  E     0x00040000
5750: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
5760: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5770: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5780: 4f 50 45 4e 5f 57 41 4c 20 20 20 20 20 20 20 20  OPEN_WAL        
5790: 20 20 20 20 20 20 30 78 30 30 30 38 30 30 30 30        0x00080000
57a0: 20 20 2f 2a 20 56 46 53 20 6f 6e 6c 79 20 2a 2f    /* VFS only */
57b0: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
57c0: 4f 50 45 4e 5f 55 52 49 20 20 20 20 20 20 20 20  OPEN_URI        
57d0: 20 20 20 20 20 20 30 78 30 30 31 30 30 30 30 30        0x00100000
57e0: 20 20 2f 2a 20 4f 6b 20 66 6f 72 20 73 71 6c 69    /* Ok for sqli
57f0: 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 2a 2f  te3_open_v2() */
5800: 0a 0a 2f 2a 20 52 65 73 65 72 76 65 64 3a 20 20  ../* Reserved:  
5810: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
5820: 20 20 20 20 20 20 20 30 78 30 30 46 30 30 30 30         0x00F0000
5830: 30 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  0 */../*.** CAPI
5840: 33 52 45 46 3a 20 44 65 76 69 63 65 20 43 68 61  3REF: Device Cha
5850: 72 61 63 74 65 72 69 73 74 69 63 73 0a 2a 2a 0a  racteristics.**.
5860: 2a 2a 20 54 68 65 20 78 44 65 76 69 63 65 43 68  ** The xDeviceCh
5870: 61 72 61 63 74 65 72 69 73 74 69 63 73 20 6d 65  aracteristics me
5880: 74 68 6f 64 20 6f 66 20 74 68 65 20 5b 73 71 6c  thod of the [sql
5890: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
58a0: 0a 2a 2a 20 6f 62 6a 65 63 74 20 72 65 74 75 72  .** object retur
58b0: 6e 73 20 61 6e 20 69 6e 74 65 67 65 72 20 77 68  ns an integer wh
58c0: 69 63 68 20 69 73 20 61 20 76 65 63 74 6f 72 20  ich is a vector 
58d0: 6f 66 20 74 68 65 20 74 68 65 73 65 0a 2a 2a 20  of the these.** 
58e0: 62 69 74 20 76 61 6c 75 65 73 20 65 78 70 72 65  bit values expre
58f0: 73 73 69 6e 67 20 49 2f 4f 20 63 68 61 72 61 63  ssing I/O charac
5900: 74 65 72 69 73 74 69 63 73 20 6f 66 20 74 68 65  teristics of the
5910: 20 6d 61 73 73 20 73 74 6f 72 61 67 65 0a 2a 2a   mass storage.**
5920: 20 64 65 76 69 63 65 20 74 68 61 74 20 68 6f 6c   device that hol
5930: 64 73 20 74 68 65 20 66 69 6c 65 20 74 68 61 74  ds the file that
5940: 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f   the [sqlite3_io
5950: 5f 6d 65 74 68 6f 64 73 5d 0a 2a 2a 20 72 65 66  _methods].** ref
5960: 65 72 73 20 74 6f 2e 0a 2a 2a 0a 2a 2a 20 54 68  ers to..**.** Th
5970: 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41  e SQLITE_IOCAP_A
5980: 54 4f 4d 49 43 20 70 72 6f 70 65 72 74 79 20 6d  TOMIC property m
5990: 65 61 6e 73 20 74 68 61 74 20 61 6c 6c 20 77 72  eans that all wr
59a0: 69 74 65 73 20 6f 66 0a 2a 2a 20 61 6e 79 20 73  ites of.** any s
59b0: 69 7a 65 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  ize are atomic. 
59c0: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
59d0: 50 5f 41 54 4f 4d 49 43 6e 6e 6e 20 76 61 6c 75  P_ATOMICnnn valu
59e0: 65 73 0a 2a 2a 20 6d 65 61 6e 20 74 68 61 74 20  es.** mean that 
59f0: 77 72 69 74 65 73 20 6f 66 20 62 6c 6f 63 6b 73  writes of blocks
5a00: 20 74 68 61 74 20 61 72 65 20 6e 6e 6e 20 62 79   that are nnn by
5a10: 74 65 73 20 69 6e 20 73 69 7a 65 20 61 6e 64 0a  tes in size and.
5a20: 2a 2a 20 61 72 65 20 61 6c 69 67 6e 65 64 20 74  ** are aligned t
5a30: 6f 20 61 6e 20 61 64 64 72 65 73 73 20 77 68 69  o an address whi
5a40: 63 68 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72  ch is an integer
5a50: 20 6d 75 6c 74 69 70 6c 65 20 6f 66 0a 2a 2a 20   multiple of.** 
5a60: 6e 6e 6e 20 61 72 65 20 61 74 6f 6d 69 63 2e 20  nnn are atomic. 
5a70: 20 54 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41   The SQLITE_IOCA
5a80: 50 5f 53 41 46 45 5f 41 50 50 45 4e 44 20 76 61  P_SAFE_APPEND va
5a90: 6c 75 65 20 6d 65 61 6e 73 0a 2a 2a 20 74 68 61  lue means.** tha
5aa0: 74 20 77 68 65 6e 20 64 61 74 61 20 69 73 20 61  t when data is a
5ab0: 70 70 65 6e 64 65 64 20 74 6f 20 61 20 66 69 6c  ppended to a fil
5ac0: 65 2c 20 74 68 65 20 64 61 74 61 20 69 73 20 61  e, the data is a
5ad0: 70 70 65 6e 64 65 64 0a 2a 2a 20 66 69 72 73 74  ppended.** first
5ae0: 20 74 68 65 6e 20 74 68 65 20 73 69 7a 65 20 6f   then the size o
5af0: 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 65 78  f the file is ex
5b00: 74 65 6e 64 65 64 2c 20 6e 65 76 65 72 20 74 68  tended, never th
5b10: 65 20 6f 74 68 65 72 0a 2a 2a 20 77 61 79 20 61  e other.** way a
5b20: 72 6f 75 6e 64 2e 20 20 54 68 65 20 53 51 4c 49  round.  The SQLI
5b30: 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e 54  TE_IOCAP_SEQUENT
5b40: 49 41 4c 20 70 72 6f 70 65 72 74 79 20 6d 65 61  IAL property mea
5b50: 6e 73 20 74 68 61 74 0a 2a 2a 20 69 6e 66 6f 72  ns that.** infor
5b60: 6d 61 74 69 6f 6e 20 69 73 20 77 72 69 74 74 65  mation is writte
5b70: 6e 20 74 6f 20 64 69 73 6b 20 69 6e 20 74 68 65  n to disk in the
5b80: 20 73 61 6d 65 20 6f 72 64 65 72 20 61 73 20 63   same order as c
5b90: 61 6c 6c 73 0a 2a 2a 20 74 6f 20 78 57 72 69 74  alls.** to xWrit
5ba0: 65 28 29 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20  e()..*/.#define 
5bb0: 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f  SQLITE_IOCAP_ATO
5bc0: 4d 49 43 20 20 20 20 20 20 20 20 20 20 20 20 20  MIC             
5bd0: 20 20 20 20 30 78 30 30 30 30 30 30 30 31 0a 23      0x00000001.#
5be0: 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f  define SQLITE_IO
5bf0: 43 41 50 5f 41 54 4f 4d 49 43 35 31 32 20 20 20  CAP_ATOMIC512   
5c00: 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30             0x000
5c10: 30 30 30 30 32 0a 23 64 65 66 69 6e 65 20 53 51  00002.#define SQ
5c20: 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49  LITE_IOCAP_ATOMI
5c30: 43 31 4b 20 20 20 20 20 20 20 20 20 20 20 20 20  C1K             
5c40: 20 20 30 78 30 30 30 30 30 30 30 34 0a 23 64 65    0x00000004.#de
5c50: 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41  fine SQLITE_IOCA
5c60: 50 5f 41 54 4f 4d 49 43 32 4b 20 20 20 20 20 20  P_ATOMIC2K      
5c70: 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30 30           0x00000
5c80: 30 30 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  008.#define SQLI
5c90: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 34  TE_IOCAP_ATOMIC4
5ca0: 4b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  K               
5cb0: 30 78 30 30 30 30 30 30 31 30 0a 23 64 65 66 69  0x00000010.#defi
5cc0: 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  ne SQLITE_IOCAP_
5cd0: 41 54 4f 4d 49 43 38 4b 20 20 20 20 20 20 20 20  ATOMIC8K        
5ce0: 20 20 20 20 20 20 20 30 78 30 30 30 30 30 30 32         0x0000002
5cf0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
5d00: 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b  _IOCAP_ATOMIC16K
5d10: 20 20 20 20 20 20 20 20 20 20 20 20 20 20 30 78                0x
5d20: 30 30 30 30 30 30 34 30 0a 23 64 65 66 69 6e 65  00000040.#define
5d30: 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f 41 54   SQLITE_IOCAP_AT
5d40: 4f 4d 49 43 33 32 4b 20 20 20 20 20 20 20 20 20  OMIC32K         
5d50: 20 20 20 20 20 30 78 30 30 30 30 30 30 38 30 0a       0x00000080.
5d60: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49  #define SQLITE_I
5d70: 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 20 20  OCAP_ATOMIC64K  
5d80: 20 20 20 20 20 20 20 20 20 20 20 20 30 78 30 30              0x00
5d90: 30 30 30 31 30 30 0a 23 64 65 66 69 6e 65 20 53  000100.#define S
5da0: 51 4c 49 54 45 5f 49 4f 43 41 50 5f 53 41 46 45  QLITE_IOCAP_SAFE
5db0: 5f 41 50 50 45 4e 44 20 20 20 20 20 20 20 20 20  _APPEND         
5dc0: 20 20 20 30 78 30 30 30 30 30 32 30 30 0a 23 64     0x00000200.#d
5dd0: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4f 43  efine SQLITE_IOC
5de0: 41 50 5f 53 45 51 55 45 4e 54 49 41 4c 20 20 20  AP_SEQUENTIAL   
5df0: 20 20 20 20 20 20 20 20 20 20 30 78 30 30 30 30            0x0000
5e00: 30 34 30 30 0a 23 64 65 66 69 6e 65 20 53 51 4c  0400.#define SQL
5e10: 49 54 45 5f 49 4f 43 41 50 5f 55 4e 44 45 4c 45  ITE_IOCAP_UNDELE
5e20: 54 41 42 4c 45 5f 57 48 45 4e 5f 4f 50 45 4e 20  TABLE_WHEN_OPEN 
5e30: 20 30 78 30 30 30 30 30 38 30 30 0a 0a 2f 2a 0a   0x00000800../*.
5e40: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69 6c  ** CAPI3REF: Fil
5e50: 65 20 4c 6f 63 6b 69 6e 67 20 4c 65 76 65 6c 73  e Locking Levels
5e60: 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20 75 73  .**.** SQLite us
5e70: 65 73 20 6f 6e 65 20 6f 66 20 74 68 65 73 65 20  es one of these 
5e80: 69 6e 74 65 67 65 72 20 76 61 6c 75 65 73 20 61  integer values a
5e90: 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a 20  s the second.** 
5ea0: 61 72 67 75 6d 65 6e 74 20 74 6f 20 63 61 6c 6c  argument to call
5eb0: 73 20 69 74 20 6d 61 6b 65 73 20 74 6f 20 74 68  s it makes to th
5ec0: 65 20 78 4c 6f 63 6b 28 29 20 61 6e 64 20 78 55  e xLock() and xU
5ed0: 6e 6c 6f 63 6b 28 29 20 6d 65 74 68 6f 64 73 0a  nlock() methods.
5ee0: 2a 2a 20 6f 66 20 61 6e 20 5b 73 71 6c 69 74 65  ** of an [sqlite
5ef0: 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62  3_io_methods] ob
5f00: 6a 65 63 74 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65  ject..*/.#define
5f10: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e   SQLITE_LOCK_NON
5f20: 45 20 20 20 20 20 20 20 20 20 20 30 0a 23 64 65  E          0.#de
5f30: 66 69 6e 65 20 53 51 4c 49 54 45 5f 4c 4f 43 4b  fine SQLITE_LOCK
5f40: 5f 53 48 41 52 45 44 20 20 20 20 20 20 20 20 31  _SHARED        1
5f50: 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
5f60: 4c 4f 43 4b 5f 52 45 53 45 52 56 45 44 20 20 20  LOCK_RESERVED   
5f70: 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c     2.#define SQL
5f80: 49 54 45 5f 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47  ITE_LOCK_PENDING
5f90: 20 20 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65         3.#define
5fa0: 20 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45 58 43   SQLITE_LOCK_EXC
5fb0: 4c 55 53 49 56 45 20 20 20 20 20 34 0a 0a 2f 2a  LUSIVE     4../*
5fc0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 79  .** CAPI3REF: Sy
5fd0: 6e 63 68 72 6f 6e 69 7a 61 74 69 6f 6e 20 54 79  nchronization Ty
5fe0: 70 65 20 46 6c 61 67 73 0a 2a 2a 0a 2a 2a 20 57  pe Flags.**.** W
5ff0: 68 65 6e 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b  hen SQLite invok
6000: 65 73 20 74 68 65 20 78 53 79 6e 63 28 29 20 6d  es the xSync() m
6010: 65 74 68 6f 64 20 6f 66 20 61 6e 0a 2a 2a 20 5b  ethod of an.** [
6020: 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f  sqlite3_io_metho
6030: 64 73 5d 20 6f 62 6a 65 63 74 20 69 74 20 75 73  ds] object it us
6040: 65 73 20 61 20 63 6f 6d 62 69 6e 61 74 69 6f 6e  es a combination
6050: 20 6f 66 0a 2a 2a 20 74 68 65 73 65 20 69 6e 74   of.** these int
6060: 65 67 65 72 20 76 61 6c 75 65 73 20 61 73 20 74  eger values as t
6070: 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d 65  he second argume
6080: 6e 74 2e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  nt..**.** When t
6090: 68 65 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44  he SQLITE_SYNC_D
60a0: 41 54 41 4f 4e 4c 59 20 66 6c 61 67 20 69 73 20  ATAONLY flag is 
60b0: 75 73 65 64 2c 20 69 74 20 6d 65 61 6e 73 20 74  used, it means t
60c0: 68 61 74 20 74 68 65 0a 2a 2a 20 73 79 6e 63 20  hat the.** sync 
60d0: 6f 70 65 72 61 74 69 6f 6e 20 6f 6e 6c 79 20 6e  operation only n
60e0: 65 65 64 73 20 74 6f 20 66 6c 75 73 68 20 64 61  eeds to flush da
60f0: 74 61 20 74 6f 20 6d 61 73 73 20 73 74 6f 72 61  ta to mass stora
6100: 67 65 2e 20 20 49 6e 6f 64 65 0a 2a 2a 20 69 6e  ge.  Inode.** in
6110: 66 6f 72 6d 61 74 69 6f 6e 20 6e 65 65 64 20 6e  formation need n
6120: 6f 74 20 62 65 20 66 6c 75 73 68 65 64 2e 20 49  ot be flushed. I
6130: 66 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72  f the lower four
6140: 20 62 69 74 73 20 6f 66 20 74 68 65 20 66 6c 61   bits of the fla
6150: 67 0a 2a 2a 20 65 71 75 61 6c 20 53 51 4c 49 54  g.** equal SQLIT
6160: 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 2c 20 74  E_SYNC_NORMAL, t
6170: 68 61 74 20 6d 65 61 6e 73 20 74 6f 20 75 73 65  hat means to use
6180: 20 6e 6f 72 6d 61 6c 20 66 73 79 6e 63 28 29 20   normal fsync() 
6190: 73 65 6d 61 6e 74 69 63 73 2e 0a 2a 2a 20 49 66  semantics..** If
61a0: 20 74 68 65 20 6c 6f 77 65 72 20 66 6f 75 72 20   the lower four 
61b0: 62 69 74 73 20 65 71 75 61 6c 20 53 51 4c 49 54  bits equal SQLIT
61c0: 45 5f 53 59 4e 43 5f 46 55 4c 4c 2c 20 74 68 61  E_SYNC_FULL, tha
61d0: 74 20 6d 65 61 6e 73 0a 2a 2a 20 74 6f 20 75 73  t means.** to us
61e0: 65 20 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65  e Mac OS X style
61f0: 20 66 75 6c 6c 73 79 6e 63 20 69 6e 73 74 65 61   fullsync instea
6200: 64 20 6f 66 20 66 73 79 6e 63 28 29 2e 0a 2a 2a  d of fsync()..**
6210: 0a 2a 2a 20 44 6f 20 6e 6f 74 20 63 6f 6e 66 75  .** Do not confu
6220: 73 65 20 74 68 65 20 53 51 4c 49 54 45 5f 53 59  se the SQLITE_SY
6230: 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64 20 53 51  NC_NORMAL and SQ
6240: 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c 4c 20 66  LITE_SYNC_FULL f
6250: 6c 61 67 73 0a 2a 2a 20 77 69 74 68 20 74 68 65  lags.** with the
6260: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6270: 6e 6f 75 73 5d 3d 4e 4f 52 4d 41 4c 20 61 6e 64  nous]=NORMAL and
6280: 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f   [PRAGMA synchro
6290: 6e 6f 75 73 5d 3d 46 55 4c 4c 0a 2a 2a 20 73 65  nous]=FULL.** se
62a0: 74 74 69 6e 67 73 2e 20 20 54 68 65 20 5b 73 79  ttings.  The [sy
62b0: 6e 63 68 72 6f 6e 6f 75 73 20 70 72 61 67 6d 61  nchronous pragma
62c0: 5d 20 64 65 74 65 72 6d 69 6e 65 73 20 77 68 65  ] determines whe
62d0: 6e 20 63 61 6c 6c 73 20 74 6f 20 74 68 65 0a 2a  n calls to the.*
62e0: 2a 20 78 53 79 6e 63 20 56 46 53 20 6d 65 74 68  * xSync VFS meth
62f0: 6f 64 20 6f 63 63 75 72 20 61 6e 64 20 61 70 70  od occur and app
6300: 6c 69 65 73 20 75 6e 69 66 6f 72 6d 6c 79 20 61  lies uniformly a
6310: 63 72 6f 73 73 20 61 6c 6c 20 70 6c 61 74 66 6f  cross all platfo
6320: 72 6d 73 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 49  rms..** The SQLI
6330: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61  TE_SYNC_NORMAL a
6340: 6e 64 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46  nd SQLITE_SYNC_F
6350: 55 4c 4c 20 66 6c 61 67 73 20 64 65 74 65 72 6d  ULL flags determ
6360: 69 6e 65 20 68 6f 77 0a 2a 2a 20 65 6e 65 72 67  ine how.** energ
6370: 65 74 69 63 20 6f 72 20 72 69 67 6f 72 6f 75 73  etic or rigorous
6380: 20 6f 72 20 66 6f 72 63 65 66 75 6c 20 74 68 65   or forceful the
6390: 20 73 79 6e 63 20 6f 70 65 72 61 74 69 6f 6e 73   sync operations
63a0: 20 61 72 65 20 61 6e 64 0a 2a 2a 20 6f 6e 6c 79   are and.** only
63b0: 20 6d 61 6b 65 20 61 20 64 69 66 66 65 72 65 6e   make a differen
63c0: 63 65 20 6f 6e 20 4d 61 63 20 4f 53 58 20 66 6f  ce on Mac OSX fo
63d0: 72 20 74 68 65 20 64 65 66 61 75 6c 74 20 53 51  r the default SQ
63e0: 4c 69 74 65 20 63 6f 64 65 2e 0a 2a 2a 20 28 54  Lite code..** (T
63f0: 68 69 72 64 2d 70 61 72 74 79 20 56 46 53 20 69  hird-party VFS i
6400: 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6d  mplementations m
6410: 69 67 68 74 20 61 6c 73 6f 20 6d 61 6b 65 20 74  ight also make t
6420: 68 65 20 64 69 73 74 69 6e 63 74 69 6f 6e 0a 2a  he distinction.*
6430: 2a 20 62 65 74 77 65 65 6e 20 53 51 4c 49 54 45  * between SQLITE
6440: 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 61 6e 64  _SYNC_NORMAL and
6450: 20 53 51 4c 49 54 45 5f 53 59 4e 43 5f 46 55 4c   SQLITE_SYNC_FUL
6460: 4c 2c 20 62 75 74 20 61 6d 6f 6e 67 20 74 68 65  L, but among the
6470: 0a 2a 2a 20 6f 70 65 72 61 74 69 6e 67 20 73 79  .** operating sy
6480: 73 74 65 6d 73 20 6e 61 74 69 76 65 6c 79 20 73  stems natively s
6490: 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
64a0: 74 65 2c 20 6f 6e 6c 79 20 4d 61 63 20 4f 53 58  te, only Mac OSX
64b0: 0a 2a 2a 20 63 61 72 65 73 20 61 62 6f 75 74 20  .** cares about 
64c0: 74 68 65 20 64 69 66 66 65 72 65 6e 63 65 2e 29  the difference.)
64d0: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
64e0: 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41 4c 20 20  TE_SYNC_NORMAL  
64f0: 20 20 20 20 20 20 30 78 30 30 30 30 32 0a 23 64        0x00002.#d
6500: 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 53 59 4e  efine SQLITE_SYN
6510: 43 5f 46 55 4c 4c 20 20 20 20 20 20 20 20 20 20  C_FULL          
6520: 30 78 30 30 30 30 33 0a 23 64 65 66 69 6e 65 20  0x00003.#define 
6530: 53 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41  SQLITE_SYNC_DATA
6540: 4f 4e 4c 59 20 20 20 20 20 20 30 78 30 30 30 31  ONLY      0x0001
6550: 30 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  0../*.** CAPI3RE
6560: 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65 20  F: OS Interface 
6570: 4f 70 65 6e 20 46 69 6c 65 20 48 61 6e 64 6c 65  Open File Handle
6580: 0a 2a 2a 0a 2a 2a 20 41 6e 20 5b 73 71 6c 69 74  .**.** An [sqlit
6590: 65 33 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 20  e3_file] object 
65a0: 72 65 70 72 65 73 65 6e 74 73 20 61 6e 20 6f 70  represents an op
65b0: 65 6e 20 66 69 6c 65 20 69 6e 20 74 68 65 20 0a  en file in the .
65c0: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 20  ** [sqlite3_vfs 
65d0: 7c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  | OS interface l
65e0: 61 79 65 72 5d 2e 20 20 49 6e 64 69 76 69 64 75  ayer].  Individu
65f0: 61 6c 20 4f 53 20 69 6e 74 65 72 66 61 63 65 0a  al OS interface.
6600: 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  ** implementatio
6610: 6e 73 20 77 69 6c 6c 0a 2a 2a 20 77 61 6e 74 20  ns will.** want 
6620: 74 6f 20 73 75 62 63 6c 61 73 73 20 74 68 69 73  to subclass this
6630: 20 6f 62 6a 65 63 74 20 62 79 20 61 70 70 65 6e   object by appen
6640: 64 69 6e 67 20 61 64 64 69 74 69 6f 6e 61 6c 20  ding additional 
6650: 66 69 65 6c 64 73 0a 2a 2a 20 66 6f 72 20 74 68  fields.** for th
6660: 65 69 72 20 6f 77 6e 20 75 73 65 2e 20 20 54 68  eir own use.  Th
6670: 65 20 70 4d 65 74 68 6f 64 73 20 65 6e 74 72 79  e pMethods entry
6680: 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   is a pointer to
6690: 20 61 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f   an.** [sqlite3_
66a0: 69 6f 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a 65  io_methods] obje
66b0: 63 74 20 74 68 61 74 20 64 65 66 69 6e 65 73 20  ct that defines 
66c0: 6d 65 74 68 6f 64 73 20 66 6f 72 20 70 65 72 66  methods for perf
66d0: 6f 72 6d 69 6e 67 0a 2a 2a 20 49 2f 4f 20 6f 70  orming.** I/O op
66e0: 65 72 61 74 69 6f 6e 73 20 6f 6e 20 74 68 65 20  erations on the 
66f0: 6f 70 65 6e 20 66 69 6c 65 2e 0a 2a 2f 0a 74 79  open file..*/.ty
6700: 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
6710: 69 74 65 33 5f 66 69 6c 65 20 73 71 6c 69 74 65  ite3_file sqlite
6720: 33 5f 66 69 6c 65 3b 0a 73 74 72 75 63 74 20 73  3_file;.struct s
6730: 71 6c 69 74 65 33 5f 66 69 6c 65 20 7b 0a 20 20  qlite3_file {.  
6740: 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71 6c  const struct sql
6750: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 20  ite3_io_methods 
6760: 2a 70 4d 65 74 68 6f 64 73 3b 20 20 2f 2a 20 4d  *pMethods;  /* M
6770: 65 74 68 6f 64 73 20 66 6f 72 20 61 6e 20 6f 70  ethods for an op
6780: 65 6e 20 66 69 6c 65 20 2a 2f 0a 7d 3b 0a 0a 2f  en file */.};../
6790: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4f  *.** CAPI3REF: O
67a0: 53 20 49 6e 74 65 72 66 61 63 65 20 46 69 6c 65  S Interface File
67b0: 20 56 69 72 74 75 61 6c 20 4d 65 74 68 6f 64 73   Virtual Methods
67c0: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 45 76   Object.**.** Ev
67d0: 65 72 79 20 66 69 6c 65 20 6f 70 65 6e 65 64 20  ery file opened 
67e0: 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  by the [sqlite3_
67f0: 76 66 73 5d 20 78 4f 70 65 6e 20 6d 65 74 68 6f  vfs] xOpen metho
6800: 64 20 70 6f 70 75 6c 61 74 65 73 20 61 6e 0a 2a  d populates an.*
6810: 2a 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d  * [sqlite3_file]
6820: 20 6f 62 6a 65 63 74 20 28 6f 72 2c 20 6d 6f 72   object (or, mor
6830: 65 20 63 6f 6d 6d 6f 6e 6c 79 2c 20 61 20 73 75  e commonly, a su
6840: 62 63 6c 61 73 73 20 6f 66 20 74 68 65 0a 2a 2a  bclass of the.**
6850: 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20   [sqlite3_file] 
6860: 6f 62 6a 65 63 74 29 20 77 69 74 68 20 61 20 70  object) with a p
6870: 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69 6e 73  ointer to an ins
6880: 74 61 6e 63 65 20 6f 66 20 74 68 69 73 20 6f 62  tance of this ob
6890: 6a 65 63 74 2e 0a 2a 2a 20 54 68 69 73 20 6f 62  ject..** This ob
68a0: 6a 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65  ject defines the
68b0: 20 6d 65 74 68 6f 64 73 20 75 73 65 64 20 74 6f   methods used to
68c0: 20 70 65 72 66 6f 72 6d 20 76 61 72 69 6f 75 73   perform various
68d0: 20 6f 70 65 72 61 74 69 6f 6e 73 0a 2a 2a 20 61   operations.** a
68e0: 67 61 69 6e 73 74 20 74 68 65 20 6f 70 65 6e 20  gainst the open 
68f0: 66 69 6c 65 20 72 65 70 72 65 73 65 6e 74 65 64  file represented
6900: 20 62 79 20 74 68 65 20 5b 73 71 6c 69 74 65 33   by the [sqlite3
6910: 5f 66 69 6c 65 5d 20 6f 62 6a 65 63 74 2e 0a 2a  _file] object..*
6920: 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78 4f 70 65  *.** If the xOpe
6930: 6e 20 6d 65 74 68 6f 64 20 73 65 74 73 20 74 68  n method sets th
6940: 65 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70  e sqlite3_file.p
6950: 4d 65 74 68 6f 64 73 20 65 6c 65 6d 65 6e 74 20  Methods element 
6960: 0a 2a 2a 20 74 6f 20 61 20 6e 6f 6e 2d 4e 55 4c  .** to a non-NUL
6970: 4c 20 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20  L pointer, then 
6980: 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  the sqlite3_io_m
6990: 65 74 68 6f 64 73 2e 78 43 6c 6f 73 65 20 6d 65  ethods.xClose me
69a0: 74 68 6f 64 0a 2a 2a 20 6d 61 79 20 62 65 20 69  thod.** may be i
69b0: 6e 76 6f 6b 65 64 20 65 76 65 6e 20 69 66 20 74  nvoked even if t
69c0: 68 65 20 78 4f 70 65 6e 20 72 65 70 6f 72 74 65  he xOpen reporte
69d0: 64 20 74 68 61 74 20 69 74 20 66 61 69 6c 65 64  d that it failed
69e0: 2e 20 20 54 68 65 0a 2a 2a 20 6f 6e 6c 79 20 77  .  The.** only w
69f0: 61 79 20 74 6f 20 70 72 65 76 65 6e 74 20 61 20  ay to prevent a 
6a00: 63 61 6c 6c 20 74 6f 20 78 43 6c 6f 73 65 20 66  call to xClose f
6a10: 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 65  ollowing a faile
6a20: 64 20 78 4f 70 65 6e 0a 2a 2a 20 69 73 20 66 6f  d xOpen.** is fo
6a30: 72 20 74 68 65 20 78 4f 70 65 6e 20 74 6f 20 73  r the xOpen to s
6a40: 65 74 20 74 68 65 20 73 71 6c 69 74 65 33 5f 66  et the sqlite3_f
6a50: 69 6c 65 2e 70 4d 65 74 68 6f 64 73 20 65 6c 65  ile.pMethods ele
6a60: 6d 65 6e 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a  ment to NULL..**
6a70: 0a 2a 2a 20 54 68 65 20 66 6c 61 67 73 20 61 72  .** The flags ar
6a80: 67 75 6d 65 6e 74 20 74 6f 20 78 53 79 6e 63 20  gument to xSync 
6a90: 6d 61 79 20 62 65 20 6f 6e 65 20 6f 66 20 5b 53  may be one of [S
6aa0: 51 4c 49 54 45 5f 53 59 4e 43 5f 4e 4f 52 4d 41  QLITE_SYNC_NORMA
6ab0: 4c 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c 49 54 45  L] or.** [SQLITE
6ac0: 5f 53 59 4e 43 5f 46 55 4c 4c 5d 2e 20 20 54 68  _SYNC_FULL].  Th
6ad0: 65 20 66 69 72 73 74 20 63 68 6f 69 63 65 20 69  e first choice i
6ae0: 73 20 74 68 65 20 6e 6f 72 6d 61 6c 20 66 73 79  s the normal fsy
6af0: 6e 63 28 29 2e 0a 2a 2a 20 54 68 65 20 73 65 63  nc()..** The sec
6b00: 6f 6e 64 20 63 68 6f 69 63 65 20 69 73 20 61 20  ond choice is a 
6b10: 4d 61 63 20 4f 53 20 58 20 73 74 79 6c 65 20 66  Mac OS X style f
6b20: 75 6c 6c 73 79 6e 63 2e 20 20 54 68 65 20 5b 53  ullsync.  The [S
6b30: 51 4c 49 54 45 5f 53 59 4e 43 5f 44 41 54 41 4f  QLITE_SYNC_DATAO
6b40: 4e 4c 59 5d 0a 2a 2a 20 66 6c 61 67 20 6d 61 79  NLY].** flag may
6b50: 20 62 65 20 4f 52 65 64 20 69 6e 20 74 6f 20 69   be ORed in to i
6b60: 6e 64 69 63 61 74 65 20 74 68 61 74 20 6f 6e 6c  ndicate that onl
6b70: 79 20 74 68 65 20 64 61 74 61 20 6f 66 20 74 68  y the data of th
6b80: 65 20 66 69 6c 65 0a 2a 2a 20 61 6e 64 20 6e 6f  e file.** and no
6b90: 74 20 69 74 73 20 69 6e 6f 64 65 20 6e 65 65 64  t its inode need
6ba0: 73 20 74 6f 20 62 65 20 73 79 6e 63 65 64 2e 0a  s to be synced..
6bb0: 2a 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 67 65  **.** The intege
6bc0: 72 20 76 61 6c 75 65 73 20 74 6f 20 78 4c 6f 63  r values to xLoc
6bd0: 6b 28 29 20 61 6e 64 20 78 55 6e 6c 6f 63 6b 28  k() and xUnlock(
6be0: 29 20 61 72 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20  ) are one of.** 
6bf0: 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51  <ul>.** <li> [SQ
6c00: 4c 49 54 45 5f 4c 4f 43 4b 5f 4e 4f 4e 45 5d 2c  LITE_LOCK_NONE],
6c10: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6c20: 5f 4c 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a  _LOCK_SHARED],.*
6c30: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6c40: 4f 43 4b 5f 52 45 53 45 52 56 45 44 5d 2c 0a 2a  OCK_RESERVED],.*
6c50: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4c  * <li> [SQLITE_L
6c60: 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f 72  OCK_PENDING], or
6c70: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
6c80: 5f 4c 4f 43 4b 5f 45 58 43 4c 55 53 49 56 45 5d  _LOCK_EXCLUSIVE]
6c90: 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 20 78 4c  ..** </ul>.** xL
6ca0: 6f 63 6b 28 29 20 69 6e 63 72 65 61 73 65 73 20  ock() increases 
6cb0: 74 68 65 20 6c 6f 63 6b 2e 20 78 55 6e 6c 6f 63  the lock. xUnloc
6cc0: 6b 28 29 20 64 65 63 72 65 61 73 65 73 20 74 68  k() decreases th
6cd0: 65 20 6c 6f 63 6b 2e 0a 2a 2a 20 54 68 65 20 78  e lock..** The x
6ce0: 43 68 65 63 6b 52 65 73 65 72 76 65 64 4c 6f 63  CheckReservedLoc
6cf0: 6b 28 29 20 6d 65 74 68 6f 64 20 63 68 65 63 6b  k() method check
6d00: 73 20 77 68 65 74 68 65 72 20 61 6e 79 20 64 61  s whether any da
6d10: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
6d20: 6e 2c 0a 2a 2a 20 65 69 74 68 65 72 20 69 6e 20  n,.** either in 
6d30: 74 68 69 73 20 70 72 6f 63 65 73 73 20 6f 72 20  this process or 
6d40: 69 6e 20 73 6f 6d 65 20 6f 74 68 65 72 20 70 72  in some other pr
6d50: 6f 63 65 73 73 2c 20 69 73 20 68 6f 6c 64 69 6e  ocess, is holdin
6d60: 67 20 61 20 52 45 53 45 52 56 45 44 2c 0a 2a 2a  g a RESERVED,.**
6d70: 20 50 45 4e 44 49 4e 47 2c 20 6f 72 20 45 58 43   PENDING, or EXC
6d80: 4c 55 53 49 56 45 20 6c 6f 63 6b 20 6f 6e 20 74  LUSIVE lock on t
6d90: 68 65 20 66 69 6c 65 2e 20 20 49 74 20 72 65 74  he file.  It ret
6da0: 75 72 6e 73 20 74 72 75 65 0a 2a 2a 20 69 66 20  urns true.** if 
6db0: 73 75 63 68 20 61 20 6c 6f 63 6b 20 65 78 69 73  such a lock exis
6dc0: 74 73 20 61 6e 64 20 66 61 6c 73 65 20 6f 74 68  ts and false oth
6dd0: 65 72 77 69 73 65 2e 0a 2a 2a 0a 2a 2a 20 54 68  erwise..**.** Th
6de0: 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c 28 29  e xFileControl()
6df0: 20 6d 65 74 68 6f 64 20 69 73 20 61 20 67 65 6e   method is a gen
6e00: 65 72 69 63 20 69 6e 74 65 72 66 61 63 65 20 74  eric interface t
6e10: 68 61 74 20 61 6c 6c 6f 77 73 20 63 75 73 74 6f  hat allows custo
6e20: 6d 0a 2a 2a 20 56 46 53 20 69 6d 70 6c 65 6d 65  m.** VFS impleme
6e30: 6e 74 61 74 69 6f 6e 73 20 74 6f 20 64 69 72 65  ntations to dire
6e40: 63 74 6c 79 20 63 6f 6e 74 72 6f 6c 20 61 6e 20  ctly control an 
6e50: 6f 70 65 6e 20 66 69 6c 65 20 75 73 69 6e 67 20  open file using 
6e60: 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  the.** [sqlite3_
6e70: 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20  file_control()] 
6e80: 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65 20  interface.  The 
6e90: 73 65 63 6f 6e 64 20 22 6f 70 22 20 61 72 67 75  second "op" argu
6ea0: 6d 65 6e 74 20 69 73 20 61 6e 0a 2a 2a 20 69 6e  ment is an.** in
6eb0: 74 65 67 65 72 20 6f 70 63 6f 64 65 2e 20 20 54  teger opcode.  T
6ec0: 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
6ed0: 74 20 69 73 20 61 20 67 65 6e 65 72 69 63 20 70  t is a generic p
6ee0: 6f 69 6e 74 65 72 20 69 6e 74 65 6e 64 65 64 20  ointer intended 
6ef0: 74 6f 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61  to.** point to a
6f00: 20 73 74 72 75 63 74 75 72 65 20 74 68 61 74 20   structure that 
6f10: 6d 61 79 20 63 6f 6e 74 61 69 6e 20 61 72 67 75  may contain argu
6f20: 6d 65 6e 74 73 20 6f 72 20 73 70 61 63 65 20 69  ments or space i
6f30: 6e 20 77 68 69 63 68 20 74 6f 0a 2a 2a 20 77 72  n which to.** wr
6f40: 69 74 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65  ite return value
6f50: 73 2e 20 20 50 6f 74 65 6e 74 69 61 6c 20 75 73  s.  Potential us
6f60: 65 73 20 66 6f 72 20 78 46 69 6c 65 43 6f 6e 74  es for xFileCont
6f70: 72 6f 6c 28 29 20 6d 69 67 68 74 20 62 65 0a 2a  rol() might be.*
6f80: 2a 20 66 75 6e 63 74 69 6f 6e 73 20 74 6f 20 65  * functions to e
6f90: 6e 61 62 6c 65 20 62 6c 6f 63 6b 69 6e 67 20 6c  nable blocking l
6fa0: 6f 63 6b 73 20 77 69 74 68 20 74 69 6d 65 6f 75  ocks with timeou
6fb0: 74 73 2c 20 74 6f 20 63 68 61 6e 67 65 20 74 68  ts, to change th
6fc0: 65 0a 2a 2a 20 6c 6f 63 6b 69 6e 67 20 73 74 72  e.** locking str
6fd0: 61 74 65 67 79 20 28 66 6f 72 20 65 78 61 6d 70  ategy (for examp
6fe0: 6c 65 20 74 6f 20 75 73 65 20 64 6f 74 2d 66 69  le to use dot-fi
6ff0: 6c 65 20 6c 6f 63 6b 73 29 2c 20 74 6f 20 69 6e  le locks), to in
7000: 71 75 69 72 65 0a 2a 2a 20 61 62 6f 75 74 20 74  quire.** about t
7010: 68 65 20 73 74 61 74 75 73 20 6f 66 20 61 20 6c  he status of a l
7020: 6f 63 6b 2c 20 6f 72 20 74 6f 20 62 72 65 61 6b  ock, or to break
7030: 20 73 74 61 6c 65 20 6c 6f 63 6b 73 2e 20 20 54   stale locks.  T
7040: 68 65 20 53 51 4c 69 74 65 0a 2a 2a 20 63 6f 72  he SQLite.** cor
7050: 65 20 72 65 73 65 72 76 65 73 20 61 6c 6c 20 6f  e reserves all o
7060: 70 63 6f 64 65 73 20 6c 65 73 73 20 74 68 61 6e  pcodes less than
7070: 20 31 30 30 20 66 6f 72 20 69 74 73 20 6f 77 6e   100 for its own
7080: 20 75 73 65 2e 0a 2a 2a 20 41 20 5b 53 51 4c 49   use..** A [SQLI
7090: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
70a0: 54 45 20 7c 20 6c 69 73 74 20 6f 66 20 6f 70 63  TE | list of opc
70b0: 6f 64 65 73 5d 20 6c 65 73 73 20 74 68 61 6e 20  odes] less than 
70c0: 31 30 30 20 69 73 20 61 76 61 69 6c 61 62 6c 65  100 is available
70d0: 2e 0a 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e  ..** Application
70e0: 73 20 74 68 61 74 20 64 65 66 69 6e 65 20 61 20  s that define a 
70f0: 63 75 73 74 6f 6d 20 78 46 69 6c 65 43 6f 6e 74  custom xFileCont
7100: 72 6f 6c 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  rol method shoul
7110: 64 20 75 73 65 20 6f 70 63 6f 64 65 73 0a 2a 2a  d use opcodes.**
7120: 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 31 30   greater than 10
7130: 30 20 74 6f 20 61 76 6f 69 64 20 63 6f 6e 66 6c  0 to avoid confl
7140: 69 63 74 73 2e 20 20 56 46 53 20 69 6d 70 6c 65  icts.  VFS imple
7150: 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f 75 6c  mentations shoul
7160: 64 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  d.** return [SQL
7170: 49 54 45 5f 4e 4f 54 46 4f 55 4e 44 5d 20 66 6f  ITE_NOTFOUND] fo
7180: 72 20 66 69 6c 65 20 63 6f 6e 74 72 6f 6c 20 6f  r file control o
7190: 70 63 6f 64 65 73 20 74 68 61 74 20 74 68 65 79  pcodes that they
71a0: 20 64 6f 20 6e 6f 74 0a 2a 2a 20 72 65 63 6f 67   do not.** recog
71b0: 6e 69 7a 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  nize..**.** The 
71c0: 78 53 65 63 74 6f 72 53 69 7a 65 28 29 20 6d 65  xSectorSize() me
71d0: 74 68 6f 64 20 72 65 74 75 72 6e 73 20 74 68 65  thod returns the
71e0: 20 73 65 63 74 6f 72 20 73 69 7a 65 20 6f 66 20   sector size of 
71f0: 74 68 65 0a 2a 2a 20 64 65 76 69 63 65 20 74 68  the.** device th
7200: 61 74 20 75 6e 64 65 72 6c 69 65 73 20 74 68 65  at underlies the
7210: 20 66 69 6c 65 2e 20 20 54 68 65 20 73 65 63 74   file.  The sect
7220: 6f 72 20 73 69 7a 65 20 69 73 20 74 68 65 0a 2a  or size is the.*
7230: 2a 20 6d 69 6e 69 6d 75 6d 20 77 72 69 74 65 20  * minimum write 
7240: 74 68 61 74 20 63 61 6e 20 62 65 20 70 65 72 66  that can be perf
7250: 6f 72 6d 65 64 20 77 69 74 68 6f 75 74 20 64 69  ormed without di
7260: 73 74 75 72 62 69 6e 67 0a 2a 2a 20 6f 74 68 65  sturbing.** othe
7270: 72 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 66  r bytes in the f
7280: 69 6c 65 2e 20 20 54 68 65 20 78 44 65 76 69 63  ile.  The xDevic
7290: 65 43 68 61 72 61 63 74 65 72 69 73 74 69 63 73  eCharacteristics
72a0: 28 29 0a 2a 2a 20 6d 65 74 68 6f 64 20 72 65 74  ().** method ret
72b0: 75 72 6e 73 20 61 20 62 69 74 20 76 65 63 74 6f  urns a bit vecto
72c0: 72 20 64 65 73 63 72 69 62 69 6e 67 20 62 65 68  r describing beh
72d0: 61 76 69 6f 72 73 20 6f 66 20 74 68 65 0a 2a 2a  aviors of the.**
72e0: 20 75 6e 64 65 72 6c 79 69 6e 67 20 64 65 76 69   underlying devi
72f0: 63 65 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  ce:.**.** <ul>.*
7300: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
7310: 4f 43 41 50 5f 41 54 4f 4d 49 43 5d 0a 2a 2a 20  OCAP_ATOMIC].** 
7320: 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f 43  <li> [SQLITE_IOC
7330: 41 50 5f 41 54 4f 4d 49 43 35 31 32 5d 0a 2a 2a  AP_ATOMIC512].**
7340: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7350: 43 41 50 5f 41 54 4f 4d 49 43 31 4b 5d 0a 2a 2a  CAP_ATOMIC1K].**
7360: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7370: 43 41 50 5f 41 54 4f 4d 49 43 32 4b 5d 0a 2a 2a  CAP_ATOMIC2K].**
7380: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
7390: 43 41 50 5f 41 54 4f 4d 49 43 34 4b 5d 0a 2a 2a  CAP_ATOMIC4K].**
73a0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
73b0: 43 41 50 5f 41 54 4f 4d 49 43 38 4b 5d 0a 2a 2a  CAP_ATOMIC8K].**
73c0: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49 4f   <li> [SQLITE_IO
73d0: 43 41 50 5f 41 54 4f 4d 49 43 31 36 4b 5d 0a 2a  CAP_ATOMIC16K].*
73e0: 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 49  * <li> [SQLITE_I
73f0: 4f 43 41 50 5f 41 54 4f 4d 49 43 33 32 4b 5d 0a  OCAP_ATOMIC32K].
7400: 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f  ** <li> [SQLITE_
7410: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 36 34 4b 5d  IOCAP_ATOMIC64K]
7420: 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
7430: 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50 50 45  _IOCAP_SAFE_APPE
7440: 4e 44 5d 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c  ND].** <li> [SQL
7450: 49 54 45 5f 49 4f 43 41 50 5f 53 45 51 55 45 4e  ITE_IOCAP_SEQUEN
7460: 54 49 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a  TIAL].** </ul>.*
7470: 2a 0a 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f  *.** The SQLITE_
7480: 49 4f 43 41 50 5f 41 54 4f 4d 49 43 20 70 72 6f  IOCAP_ATOMIC pro
7490: 70 65 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74  perty means that
74a0: 20 61 6c 6c 20 77 72 69 74 65 73 20 6f 66 0a 2a   all writes of.*
74b0: 2a 20 61 6e 79 20 73 69 7a 65 20 61 72 65 20 61  * any size are a
74c0: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
74d0: 54 45 5f 49 4f 43 41 50 5f 41 54 4f 4d 49 43 6e  TE_IOCAP_ATOMICn
74e0: 6e 6e 20 76 61 6c 75 65 73 0a 2a 2a 20 6d 65 61  nn values.** mea
74f0: 6e 20 74 68 61 74 20 77 72 69 74 65 73 20 6f 66  n that writes of
7500: 20 62 6c 6f 63 6b 73 20 74 68 61 74 20 61 72 65   blocks that are
7510: 20 6e 6e 6e 20 62 79 74 65 73 20 69 6e 20 73 69   nnn bytes in si
7520: 7a 65 20 61 6e 64 0a 2a 2a 20 61 72 65 20 61 6c  ze and.** are al
7530: 69 67 6e 65 64 20 74 6f 20 61 6e 20 61 64 64 72  igned to an addr
7540: 65 73 73 20 77 68 69 63 68 20 69 73 20 61 6e 20  ess which is an 
7550: 69 6e 74 65 67 65 72 20 6d 75 6c 74 69 70 6c 65  integer multiple
7560: 20 6f 66 0a 2a 2a 20 6e 6e 6e 20 61 72 65 20 61   of.** nnn are a
7570: 74 6f 6d 69 63 2e 20 20 54 68 65 20 53 51 4c 49  tomic.  The SQLI
7580: 54 45 5f 49 4f 43 41 50 5f 53 41 46 45 5f 41 50  TE_IOCAP_SAFE_AP
7590: 50 45 4e 44 20 76 61 6c 75 65 20 6d 65 61 6e 73  PEND value means
75a0: 0a 2a 2a 20 74 68 61 74 20 77 68 65 6e 20 64 61  .** that when da
75b0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 20 74  ta is appended t
75c0: 6f 20 61 20 66 69 6c 65 2c 20 74 68 65 20 64 61  o a file, the da
75d0: 74 61 20 69 73 20 61 70 70 65 6e 64 65 64 0a 2a  ta is appended.*
75e0: 2a 20 66 69 72 73 74 20 74 68 65 6e 20 74 68 65  * first then the
75f0: 20 73 69 7a 65 20 6f 66 20 74 68 65 20 66 69 6c   size of the fil
7600: 65 20 69 73 20 65 78 74 65 6e 64 65 64 2c 20 6e  e is extended, n
7610: 65 76 65 72 20 74 68 65 20 6f 74 68 65 72 0a 2a  ever the other.*
7620: 2a 20 77 61 79 20 61 72 6f 75 6e 64 2e 20 20 54  * way around.  T
7630: 68 65 20 53 51 4c 49 54 45 5f 49 4f 43 41 50 5f  he SQLITE_IOCAP_
7640: 53 45 51 55 45 4e 54 49 41 4c 20 70 72 6f 70 65  SEQUENTIAL prope
7650: 72 74 79 20 6d 65 61 6e 73 20 74 68 61 74 0a 2a  rty means that.*
7660: 2a 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73  * information is
7670: 20 77 72 69 74 74 65 6e 20 74 6f 20 64 69 73 6b   written to disk
7680: 20 69 6e 20 74 68 65 20 73 61 6d 65 20 6f 72 64   in the same ord
7690: 65 72 20 61 73 20 63 61 6c 6c 73 0a 2a 2a 20 74  er as calls.** t
76a0: 6f 20 78 57 72 69 74 65 28 29 2e 0a 2a 2a 0a 2a  o xWrite()..**.*
76b0: 2a 20 49 66 20 78 52 65 61 64 28 29 20 72 65 74  * If xRead() ret
76c0: 75 72 6e 73 20 53 51 4c 49 54 45 5f 49 4f 45 52  urns SQLITE_IOER
76d0: 52 5f 53 48 4f 52 54 5f 52 45 41 44 20 69 74 20  R_SHORT_READ it 
76e0: 6d 75 73 74 20 61 6c 73 6f 20 66 69 6c 6c 0a 2a  must also fill.*
76f0: 2a 20 69 6e 20 74 68 65 20 75 6e 72 65 61 64 20  * in the unread 
7700: 70 6f 72 74 69 6f 6e 73 20 6f 66 20 74 68 65 20  portions of the 
7710: 62 75 66 66 65 72 20 77 69 74 68 20 7a 65 72 6f  buffer with zero
7720: 73 2e 20 20 41 20 56 46 53 20 74 68 61 74 0a 2a  s.  A VFS that.*
7730: 2a 20 66 61 69 6c 73 20 74 6f 20 7a 65 72 6f 2d  * fails to zero-
7740: 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61 64 73  fill short reads
7750: 20 6d 69 67 68 74 20 73 65 65 6d 20 74 6f 20 77   might seem to w
7760: 6f 72 6b 2e 20 20 48 6f 77 65 76 65 72 2c 0a 2a  ork.  However,.*
7770: 2a 20 66 61 69 6c 75 72 65 20 74 6f 20 7a 65 72  * failure to zer
7780: 6f 2d 66 69 6c 6c 20 73 68 6f 72 74 20 72 65 61  o-fill short rea
7790: 64 73 20 77 69 6c 6c 20 65 76 65 6e 74 75 61 6c  ds will eventual
77a0: 6c 79 20 6c 65 61 64 20 74 6f 0a 2a 2a 20 64 61  ly lead to.** da
77b0: 74 61 62 61 73 65 20 63 6f 72 72 75 70 74 69 6f  tabase corruptio
77c0: 6e 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  n..*/.typedef st
77d0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f  ruct sqlite3_io_
77e0: 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33 5f  methods sqlite3_
77f0: 69 6f 5f 6d 65 74 68 6f 64 73 3b 0a 73 74 72 75  io_methods;.stru
7800: 63 74 20 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  ct sqlite3_io_me
7810: 74 68 6f 64 73 20 7b 0a 20 20 69 6e 74 20 69 56  thods {.  int iV
7820: 65 72 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a  ersion;.  int (*
7830: 78 43 6c 6f 73 65 29 28 73 71 6c 69 74 65 33 5f  xClose)(sqlite3_
7840: 66 69 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a  file*);.  int (*
7850: 78 52 65 61 64 29 28 73 71 6c 69 74 65 33 5f 66  xRead)(sqlite3_f
7860: 69 6c 65 2a 2c 20 76 6f 69 64 2a 2c 20 69 6e 74  ile*, void*, int
7870: 20 69 41 6d 74 2c 20 73 71 6c 69 74 65 33 5f 69   iAmt, sqlite3_i
7880: 6e 74 36 34 20 69 4f 66 73 74 29 3b 0a 20 20 69  nt64 iOfst);.  i
7890: 6e 74 20 28 2a 78 57 72 69 74 65 29 28 73 71 6c  nt (*xWrite)(sql
78a0: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 63 6f 6e 73  ite3_file*, cons
78b0: 74 20 76 6f 69 64 2a 2c 20 69 6e 74 20 69 41 6d  t void*, int iAm
78c0: 74 2c 20 73 71 6c 69 74 65 33 5f 69 6e 74 36 34  t, sqlite3_int64
78d0: 20 69 4f 66 73 74 29 3b 0a 20 20 69 6e 74 20 28   iOfst);.  int (
78e0: 2a 78 54 72 75 6e 63 61 74 65 29 28 73 71 6c 69  *xTruncate)(sqli
78f0: 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69 74  te3_file*, sqlit
7900: 65 33 5f 69 6e 74 36 34 20 73 69 7a 65 29 3b 0a  e3_int64 size);.
7910: 20 20 69 6e 74 20 28 2a 78 53 79 6e 63 29 28 73    int (*xSync)(s
7920: 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e  qlite3_file*, in
7930: 74 20 66 6c 61 67 73 29 3b 0a 20 20 69 6e 74 20  t flags);.  int 
7940: 28 2a 78 46 69 6c 65 53 69 7a 65 29 28 73 71 6c  (*xFileSize)(sql
7950: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 73 71 6c 69  ite3_file*, sqli
7960: 74 65 33 5f 69 6e 74 36 34 20 2a 70 53 69 7a 65  te3_int64 *pSize
7970: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 4c 6f 63 6b  );.  int (*xLock
7980: 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  )(sqlite3_file*,
7990: 20 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78   int);.  int (*x
79a0: 55 6e 6c 6f 63 6b 29 28 73 71 6c 69 74 65 33 5f  Unlock)(sqlite3_
79b0: 66 69 6c 65 2a 2c 20 69 6e 74 29 3b 0a 20 20 69  file*, int);.  i
79c0: 6e 74 20 28 2a 78 43 68 65 63 6b 52 65 73 65 72  nt (*xCheckReser
79d0: 76 65 64 4c 6f 63 6b 29 28 73 71 6c 69 74 65 33  vedLock)(sqlite3
79e0: 5f 66 69 6c 65 2a 2c 20 69 6e 74 20 2a 70 52 65  _file*, int *pRe
79f0: 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78  sOut);.  int (*x
7a00: 46 69 6c 65 43 6f 6e 74 72 6f 6c 29 28 73 71 6c  FileControl)(sql
7a10: 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69 6e 74 20  ite3_file*, int 
7a20: 6f 70 2c 20 76 6f 69 64 20 2a 70 41 72 67 29 3b  op, void *pArg);
7a30: 0a 20 20 69 6e 74 20 28 2a 78 53 65 63 74 6f 72  .  int (*xSector
7a40: 53 69 7a 65 29 28 73 71 6c 69 74 65 33 5f 66 69  Size)(sqlite3_fi
7a50: 6c 65 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44  le*);.  int (*xD
7a60: 65 76 69 63 65 43 68 61 72 61 63 74 65 72 69 73  eviceCharacteris
7a70: 74 69 63 73 29 28 73 71 6c 69 74 65 33 5f 66 69  tics)(sqlite3_fi
7a80: 6c 65 2a 29 3b 0a 20 20 2f 2a 20 4d 65 74 68 6f  le*);.  /* Metho
7a90: 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61 6c  ds above are val
7aa0: 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 31  id for version 1
7ab0: 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d   */.  int (*xShm
7ac0: 4d 61 70 29 28 73 71 6c 69 74 65 33 5f 66 69 6c  Map)(sqlite3_fil
7ad0: 65 2a 2c 20 69 6e 74 20 69 50 67 2c 20 69 6e 74  e*, int iPg, int
7ae0: 20 70 67 73 7a 2c 20 69 6e 74 2c 20 76 6f 69 64   pgsz, int, void
7af0: 20 76 6f 6c 61 74 69 6c 65 2a 2a 29 3b 0a 20 20   volatile**);.  
7b00: 69 6e 74 20 28 2a 78 53 68 6d 4c 6f 63 6b 29 28  int (*xShmLock)(
7b10: 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c 20 69  sqlite3_file*, i
7b20: 6e 74 20 6f 66 66 73 65 74 2c 20 69 6e 74 20 6e  nt offset, int n
7b30: 2c 20 69 6e 74 20 66 6c 61 67 73 29 3b 0a 20 20  , int flags);.  
7b40: 76 6f 69 64 20 28 2a 78 53 68 6d 42 61 72 72 69  void (*xShmBarri
7b50: 65 72 29 28 73 71 6c 69 74 65 33 5f 66 69 6c 65  er)(sqlite3_file
7b60: 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 68 6d  *);.  int (*xShm
7b70: 55 6e 6d 61 70 29 28 73 71 6c 69 74 65 33 5f 66  Unmap)(sqlite3_f
7b80: 69 6c 65 2a 2c 20 69 6e 74 20 64 65 6c 65 74 65  ile*, int delete
7b90: 46 6c 61 67 29 3b 0a 20 20 2f 2a 20 4d 65 74 68  Flag);.  /* Meth
7ba0: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 76 61  ods above are va
7bb0: 6c 69 64 20 66 6f 72 20 76 65 72 73 69 6f 6e 20  lid for version 
7bc0: 32 20 2a 2f 0a 20 20 2f 2a 20 41 64 64 69 74 69  2 */.  /* Additi
7bd0: 6f 6e 61 6c 20 6d 65 74 68 6f 64 73 20 6d 61 79  onal methods may
7be0: 20 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74   be added in fut
7bf0: 75 72 65 20 72 65 6c 65 61 73 65 73 20 2a 2f 0a  ure releases */.
7c00: 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  };../*.** CAPI3R
7c10: 45 46 3a 20 53 74 61 6e 64 61 72 64 20 46 69 6c  EF: Standard Fil
7c20: 65 20 43 6f 6e 74 72 6f 6c 20 4f 70 63 6f 64 65  e Control Opcode
7c30: 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 69 6e  s.**.** These in
7c40: 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74 73 20  teger constants 
7c50: 61 72 65 20 6f 70 63 6f 64 65 73 20 66 6f 72 20  are opcodes for 
7c60: 74 68 65 20 78 46 69 6c 65 43 6f 6e 74 72 6f 6c  the xFileControl
7c70: 20 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68   method.** of th
7c80: 65 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d 65  e [sqlite3_io_me
7c90: 74 68 6f 64 73 5d 20 6f 62 6a 65 63 74 20 61 6e  thods] object an
7ca0: 64 20 66 6f 72 20 74 68 65 20 5b 73 71 6c 69 74  d for the [sqlit
7cb0: 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f 6c 28  e3_file_control(
7cc0: 29 5d 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 2e  )].** interface.
7cd0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51 4c 49  .**.** The [SQLI
7ce0: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
7cf0: 54 45 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73  TE] opcode is us
7d00: 65 64 20 66 6f 72 20 64 65 62 75 67 67 69 6e 67  ed for debugging
7d10: 2e 20 20 54 68 69 73 0a 2a 2a 20 6f 70 63 6f 64  .  This.** opcod
7d20: 65 20 63 61 75 73 65 73 20 74 68 65 20 78 46 69  e causes the xFi
7d30: 6c 65 43 6f 6e 74 72 6f 6c 20 6d 65 74 68 6f 64  leControl method
7d40: 20 74 6f 20 77 72 69 74 65 20 74 68 65 20 63 75   to write the cu
7d50: 72 72 65 6e 74 20 73 74 61 74 65 20 6f 66 0a 2a  rrent state of.*
7d60: 2a 20 74 68 65 20 6c 6f 63 6b 20 28 6f 6e 65 20  * the lock (one 
7d70: 6f 66 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f  of [SQLITE_LOCK_
7d80: 4e 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4c  NONE], [SQLITE_L
7d90: 4f 43 4b 5f 53 48 41 52 45 44 5d 2c 0a 2a 2a 20  OCK_SHARED],.** 
7da0: 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 52 45 53  [SQLITE_LOCK_RES
7db0: 45 52 56 45 44 5d 2c 20 5b 53 51 4c 49 54 45 5f  ERVED], [SQLITE_
7dc0: 4c 4f 43 4b 5f 50 45 4e 44 49 4e 47 5d 2c 20 6f  LOCK_PENDING], o
7dd0: 72 20 5b 53 51 4c 49 54 45 5f 4c 4f 43 4b 5f 45  r [SQLITE_LOCK_E
7de0: 58 43 4c 55 53 49 56 45 5d 29 0a 2a 2a 20 69 6e  XCLUSIVE]).** in
7df0: 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20 74 68  to an integer th
7e00: 61 74 20 74 68 65 20 70 41 72 67 20 61 72 67 75  at the pArg argu
7e10: 6d 65 6e 74 20 70 6f 69 6e 74 73 20 74 6f 2e 20  ment points to. 
7e20: 54 68 69 73 20 63 61 70 61 62 69 6c 69 74 79 0a  This capability.
7e30: 2a 2a 20 69 73 20 75 73 65 64 20 64 75 72 69 6e  ** is used durin
7e40: 67 20 74 65 73 74 69 6e 67 20 61 6e 64 20 6f 6e  g testing and on
7e50: 6c 79 20 6e 65 65 64 73 20 74 6f 20 62 65 20 73  ly needs to be s
7e60: 75 70 70 6f 72 74 65 64 20 77 68 65 6e 20 53 51  upported when SQ
7e70: 4c 49 54 45 5f 54 45 53 54 0a 2a 2a 20 69 73 20  LITE_TEST.** is 
7e80: 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 54  defined..**.** T
7e90: 68 65 20 5b 53 51 4c 49 54 45 5f 46 43 4e 54 4c  he [SQLITE_FCNTL
7ea0: 5f 53 49 5a 45 5f 48 49 4e 54 5d 20 6f 70 63 6f  _SIZE_HINT] opco
7eb0: 64 65 20 69 73 20 75 73 65 64 20 62 79 20 53 51  de is used by SQ
7ec0: 4c 69 74 65 20 74 6f 20 67 69 76 65 20 74 68 65  Lite to give the
7ed0: 20 56 46 53 0a 2a 2a 20 6c 61 79 65 72 20 61 20   VFS.** layer a 
7ee0: 68 69 6e 74 20 6f 66 20 68 6f 77 20 6c 61 72 67  hint of how larg
7ef0: 65 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  e the database f
7f00: 69 6c 65 20 77 69 6c 6c 20 67 72 6f 77 20 74 6f  ile will grow to
7f10: 20 62 65 20 64 75 72 69 6e 67 20 74 68 65 0a 2a   be during the.*
7f20: 2a 20 63 75 72 72 65 6e 74 20 74 72 61 6e 73 61  * current transa
7f30: 63 74 69 6f 6e 2e 20 20 54 68 69 73 20 68 69 6e  ction.  This hin
7f40: 74 20 69 73 20 6e 6f 74 20 67 75 61 72 61 6e 74  t is not guarant
7f50: 65 65 64 20 74 6f 20 62 65 20 61 63 63 75 72 61  eed to be accura
7f60: 74 65 20 62 75 74 20 69 74 0a 2a 2a 20 69 73 20  te but it.** is 
7f70: 6f 66 74 65 6e 20 63 6c 6f 73 65 2e 20 20 54 68  often close.  Th
7f80: 65 20 75 6e 64 65 72 6c 79 69 6e 67 20 56 46 53  e underlying VFS
7f90: 20 6d 69 67 68 74 20 63 68 6f 6f 73 65 20 74 6f   might choose to
7fa0: 20 70 72 65 61 6c 6c 6f 63 61 74 65 20 64 61 74   preallocate dat
7fb0: 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65 20 73 70  abase.** file sp
7fc0: 61 63 65 20 62 61 73 65 64 20 6f 6e 20 74 68 69  ace based on thi
7fd0: 73 20 68 69 6e 74 20 69 6e 20 6f 72 64 65 72 20  s hint in order 
7fe0: 74 6f 20 68 65 6c 70 20 77 72 69 74 65 73 20 74  to help writes t
7ff0: 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a  o the database.*
8000: 2a 20 66 69 6c 65 20 72 75 6e 20 66 61 73 74 65  * file run faste
8010: 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 53 51  r..**.** The [SQ
8020: 4c 49 54 45 5f 46 43 4e 54 4c 5f 43 48 55 4e 4b  LITE_FCNTL_CHUNK
8030: 5f 53 49 5a 45 5d 20 6f 70 63 6f 64 65 20 69 73  _SIZE] opcode is
8040: 20 75 73 65 64 20 74 6f 20 72 65 71 75 65 73 74   used to request
8050: 20 74 68 61 74 20 74 68 65 20 56 46 53 0a 2a 2a   that the VFS.**
8060: 20 65 78 74 65 6e 64 73 20 61 6e 64 20 74 72 75   extends and tru
8070: 6e 63 61 74 65 73 20 74 68 65 20 64 61 74 61 62  ncates the datab
8080: 61 73 65 20 66 69 6c 65 20 69 6e 20 63 68 75 6e  ase file in chun
8090: 6b 73 20 6f 66 20 61 20 73 69 7a 65 20 73 70 65  ks of a size spe
80a0: 63 69 66 69 65 64 0a 2a 2a 20 62 79 20 74 68 65  cified.** by the
80b0: 20 75 73 65 72 2e 20 54 68 65 20 66 6f 75 72 74   user. The fourt
80c0: 68 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73  h argument to [s
80d0: 71 6c 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74  qlite3_file_cont
80e0: 72 6f 6c 28 29 5d 20 73 68 6f 75 6c 64 20 0a 2a  rol()] should .*
80f0: 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20 69 6e  * point to an in
8100: 74 65 67 65 72 20 28 74 79 70 65 20 69 6e 74 29  teger (type int)
8110: 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20   containing the 
8120: 6e 65 77 20 63 68 75 6e 6b 2d 73 69 7a 65 20 74  new chunk-size t
8130: 6f 20 75 73 65 0a 2a 2a 20 66 6f 72 20 74 68 65  o use.** for the
8140: 20 6e 6f 6d 69 6e 61 74 65 64 20 64 61 74 61 62   nominated datab
8150: 61 73 65 2e 20 41 6c 6c 6f 63 61 74 69 6e 67 20  ase. Allocating 
8160: 64 61 74 61 62 61 73 65 20 66 69 6c 65 20 73 70  database file sp
8170: 61 63 65 20 69 6e 20 6c 61 72 67 65 0a 2a 2a 20  ace in large.** 
8180: 63 68 75 6e 6b 73 20 28 73 61 79 20 31 4d 42 20  chunks (say 1MB 
8190: 61 74 20 61 20 74 69 6d 65 29 2c 20 6d 61 79 20  at a time), may 
81a0: 72 65 64 75 63 65 20 66 69 6c 65 2d 73 79 73 74  reduce file-syst
81b0: 65 6d 20 66 72 61 67 6d 65 6e 74 61 74 69 6f 6e  em fragmentation
81c0: 20 61 6e 64 0a 2a 2a 20 69 6d 70 72 6f 76 65 20   and.** improve 
81d0: 70 65 72 66 6f 72 6d 61 6e 63 65 20 6f 6e 20 73  performance on s
81e0: 6f 6d 65 20 73 79 73 74 65 6d 73 2e 0a 2a 2a 0a  ome systems..**.
81f0: 2a 2a 20 54 68 65 20 5b 53 51 4c 49 54 45 5f 46  ** The [SQLITE_F
8200: 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f 49 4e 54 45  CNTL_FILE_POINTE
8210: 52 5d 20 6f 70 63 6f 64 65 20 69 73 20 75 73 65  R] opcode is use
8220: 64 20 74 6f 20 6f 62 74 61 69 6e 20 61 20 70 6f  d to obtain a po
8230: 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20  inter.** to the 
8240: 5b 73 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 6f  [sqlite3_file] o
8250: 62 6a 65 63 74 20 61 73 73 6f 63 69 61 74 65 64  bject associated
8260: 20 77 69 74 68 20 61 20 70 61 72 74 69 63 75 6c   with a particul
8270: 61 72 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  ar database.** c
8280: 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 53 65 65 20  onnection.  See 
8290: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 66 69 6c  the [sqlite3_fil
82a0: 65 5f 63 6f 6e 74 72 6f 6c 28 29 5d 20 64 6f 63  e_control()] doc
82b0: 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f 72 0a 2a  umentation for.*
82c0: 2a 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  * additional inf
82d0: 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
82e0: 5e 28 54 68 65 20 5b 53 51 4c 49 54 45 5f 46 43  ^(The [SQLITE_FC
82f0: 4e 54 4c 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44  NTL_SYNC_OMITTED
8300: 5d 20 6f 70 63 6f 64 65 20 69 73 20 67 65 6e 65  ] opcode is gene
8310: 72 61 74 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79  rated internally
8320: 20 62 79 0a 2a 2a 20 53 51 4c 69 74 65 20 61 6e   by.** SQLite an
8330: 64 20 73 65 6e 74 20 74 6f 20 61 6c 6c 20 56 46  d sent to all VF
8340: 53 65 73 20 69 6e 20 70 6c 61 63 65 20 6f 66 20  Ses in place of 
8350: 61 20 63 61 6c 6c 20 74 6f 20 74 68 65 20 78 53  a call to the xS
8360: 79 6e 63 20 6d 65 74 68 6f 64 0a 2a 2a 20 77 68  ync method.** wh
8370: 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65 20  en the database 
8380: 63 6f 6e 6e 65 63 74 69 6f 6e 20 68 61 73 20 5b  connection has [
8390: 50 52 41 47 4d 41 20 73 79 6e 63 68 72 6f 6e 6f  PRAGMA synchrono
83a0: 75 73 5d 20 73 65 74 20 74 6f 20 4f 46 46 2e 29  us] set to OFF.)
83b0: 5e 0a 2a 2a 20 53 6f 6d 65 20 73 70 65 63 69 61  ^.** Some specia
83c0: 6c 69 7a 65 64 20 56 46 53 65 73 20 6e 65 65 64  lized VFSes need
83d0: 20 74 68 69 73 20 73 69 67 6e 61 6c 20 69 6e 20   this signal in 
83e0: 6f 72 64 65 72 20 74 6f 20 6f 70 65 72 61 74 65  order to operate
83f0: 20 63 6f 72 72 65 63 74 6c 79 0a 2a 2a 20 77 68   correctly.** wh
8400: 65 6e 20 5b 50 52 41 47 4d 41 20 73 79 6e 63 68  en [PRAGMA synch
8410: 72 6f 6e 6f 75 73 20 7c 20 50 52 41 47 4d 41 20  ronous | PRAGMA 
8420: 73 79 6e 63 68 72 6f 6e 6f 75 73 3d 4f 46 46 5d  synchronous=OFF]
8430: 20 69 73 20 73 65 74 2c 20 62 75 74 20 6d 6f 73   is set, but mos
8440: 74 20 0a 2a 2a 20 56 46 53 65 73 20 64 6f 20 6e  t .** VFSes do n
8450: 6f 74 20 6e 65 65 64 20 74 68 69 73 20 73 69 67  ot need this sig
8460: 6e 61 6c 20 61 6e 64 20 73 68 6f 75 6c 64 20 73  nal and should s
8470: 69 6c 65 6e 74 6c 79 20 69 67 6e 6f 72 65 20 74  ilently ignore t
8480: 68 69 73 20 6f 70 63 6f 64 65 2e 0a 2a 2a 20 41  his opcode..** A
8490: 70 70 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75  pplications shou
84a0: 6c 64 20 6e 6f 74 20 63 61 6c 6c 20 5b 73 71 6c  ld not call [sql
84b0: 69 74 65 33 5f 66 69 6c 65 5f 63 6f 6e 74 72 6f  ite3_file_contro
84c0: 6c 28 29 5d 20 77 69 74 68 20 74 68 69 73 0a 2a  l()] with this.*
84d0: 2a 20 6f 70 63 6f 64 65 20 61 73 20 64 6f 69 6e  * opcode as doin
84e0: 67 20 73 6f 20 6d 61 79 20 64 69 73 72 75 70 74  g so may disrupt
84f0: 20 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 6f   the operation o
8500: 66 20 74 68 65 20 73 70 65 63 69 61 6c 69 7a 65  f the specialize
8510: 64 20 56 46 53 65 73 0a 2a 2a 20 74 68 61 74 20  d VFSes.** that 
8520: 64 6f 20 72 65 71 75 69 72 65 20 69 74 2e 20 20  do require it.  
8530: 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  .*/.#define SQLI
8540: 54 45 5f 46 43 4e 54 4c 5f 4c 4f 43 4b 53 54 41  TE_FCNTL_LOCKSTA
8550: 54 45 20 20 20 20 20 20 20 20 31 0a 23 64 65 66  TE        1.#def
8560: 69 6e 65 20 53 51 4c 49 54 45 5f 47 45 54 5f 4c  ine SQLITE_GET_L
8570: 4f 43 4b 50 52 4f 58 59 46 49 4c 45 20 20 20 20  OCKPROXYFILE    
8580: 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
8590: 54 45 5f 53 45 54 5f 4c 4f 43 4b 50 52 4f 58 59  TE_SET_LOCKPROXY
85a0: 46 49 4c 45 20 20 20 20 20 20 33 0a 23 64 65 66  FILE      3.#def
85b0: 69 6e 65 20 53 51 4c 49 54 45 5f 4c 41 53 54 5f  ine SQLITE_LAST_
85c0: 45 52 52 4e 4f 20 20 20 20 20 20 20 20 20 20 20  ERRNO           
85d0: 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    4.#define SQLI
85e0: 54 45 5f 46 43 4e 54 4c 5f 53 49 5a 45 5f 48 49  TE_FCNTL_SIZE_HI
85f0: 4e 54 20 20 20 20 20 20 20 20 35 0a 23 64 65 66  NT        5.#def
8600: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8610: 5f 43 48 55 4e 4b 5f 53 49 5a 45 20 20 20 20 20  _CHUNK_SIZE     
8620: 20 20 36 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    6.#define SQLI
8630: 54 45 5f 46 43 4e 54 4c 5f 46 49 4c 45 5f 50 4f  TE_FCNTL_FILE_PO
8640: 49 4e 54 45 52 20 20 20 20 20 37 0a 23 64 65 66  INTER     7.#def
8650: 69 6e 65 20 53 51 4c 49 54 45 5f 46 43 4e 54 4c  ine SQLITE_FCNTL
8660: 5f 53 59 4e 43 5f 4f 4d 49 54 54 45 44 20 20 20  _SYNC_OMITTED   
8670: 20 20 38 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    8.#define SQLI
8680: 54 45 5f 46 43 4e 54 4c 5f 52 45 41 44 4f 4e 4c  TE_FCNTL_READONL
8690: 59 5f 53 48 4d 20 20 20 20 20 39 0a 0a 0a 2f 2a  Y_SHM     9.../*
86a0: 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 75  .** CAPI3REF: Mu
86b0: 74 65 78 20 48 61 6e 64 6c 65 0a 2a 2a 0a 2a 2a  tex Handle.**.**
86c0: 20 54 68 65 20 6d 75 74 65 78 20 6d 6f 64 75 6c   The mutex modul
86d0: 65 20 77 69 74 68 69 6e 20 53 51 4c 69 74 65 20  e within SQLite 
86e0: 64 65 66 69 6e 65 73 20 5b 73 71 6c 69 74 65 33  defines [sqlite3
86f0: 5f 6d 75 74 65 78 5d 20 74 6f 20 62 65 20 61 6e  _mutex] to be an
8700: 0a 2a 2a 20 61 62 73 74 72 61 63 74 20 74 79 70  .** abstract typ
8710: 65 20 66 6f 72 20 61 20 6d 75 74 65 78 20 6f 62  e for a mutex ob
8720: 6a 65 63 74 2e 20 20 54 68 65 20 53 51 4c 69 74  ject.  The SQLit
8730: 65 20 63 6f 72 65 20 6e 65 76 65 72 20 6c 6f 6f  e core never loo
8740: 6b 73 0a 2a 2a 20 61 74 20 74 68 65 20 69 6e 74  ks.** at the int
8750: 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
8760: 74 69 6f 6e 20 6f 66 20 61 6e 20 5b 73 71 6c 69  tion of an [sqli
8770: 74 65 33 5f 6d 75 74 65 78 5d 2e 20 20 49 74 20  te3_mutex].  It 
8780: 6f 6e 6c 79 0a 2a 2a 20 64 65 61 6c 73 20 77 69  only.** deals wi
8790: 74 68 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 74  th pointers to t
87a0: 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  he [sqlite3_mute
87b0: 78 5d 20 6f 62 6a 65 63 74 2e 0a 2a 2a 0a 2a 2a  x] object..**.**
87c0: 20 4d 75 74 65 78 65 73 20 61 72 65 20 63 72 65   Mutexes are cre
87d0: 61 74 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69  ated using [sqli
87e0: 74 65 33 5f 6d 75 74 65 78 5f 61 6c 6c 6f 63 28  te3_mutex_alloc(
87f0: 29 5d 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73  )]..*/.typedef s
8800: 74 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 75  truct sqlite3_mu
8810: 74 65 78 20 73 71 6c 69 74 65 33 5f 6d 75 74 65  tex sqlite3_mute
8820: 78 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  x;../*.** CAPI3R
8830: 45 46 3a 20 4f 53 20 49 6e 74 65 72 66 61 63 65  EF: OS Interface
8840: 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 41 6e   Object.**.** An
8850: 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
8860: 20 73 71 6c 69 74 65 33 5f 76 66 73 20 6f 62 6a   sqlite3_vfs obj
8870: 65 63 74 20 64 65 66 69 6e 65 73 20 74 68 65 20  ect defines the 
8880: 69 6e 74 65 72 66 61 63 65 20 62 65 74 77 65 65  interface betwee
8890: 6e 0a 2a 2a 20 74 68 65 20 53 51 4c 69 74 65 20  n.** the SQLite 
88a0: 63 6f 72 65 20 61 6e 64 20 74 68 65 20 75 6e 64  core and the und
88b0: 65 72 6c 79 69 6e 67 20 6f 70 65 72 61 74 69 6e  erlying operatin
88c0: 67 20 73 79 73 74 65 6d 2e 20 20 54 68 65 20 22  g system.  The "
88d0: 76 66 73 22 0a 2a 2a 20 69 6e 20 74 68 65 20 6e  vfs".** in the n
88e0: 61 6d 65 20 6f 66 20 74 68 65 20 6f 62 6a 65 63  ame of the objec
88f0: 74 20 73 74 61 6e 64 73 20 66 6f 72 20 22 76 69  t stands for "vi
8900: 72 74 75 61 6c 20 66 69 6c 65 20 73 79 73 74 65  rtual file syste
8910: 6d 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 76 61  m"..**.** The va
8920: 6c 75 65 20 6f 66 20 74 68 65 20 69 56 65 72 73  lue of the iVers
8930: 69 6f 6e 20 66 69 65 6c 64 20 69 73 20 69 6e 69  ion field is ini
8940: 74 69 61 6c 6c 79 20 31 20 62 75 74 20 6d 61 79  tially 1 but may
8950: 20 62 65 20 6c 61 72 67 65 72 20 69 6e 0a 2a 2a   be larger in.**
8960: 20 66 75 74 75 72 65 20 76 65 72 73 69 6f 6e 73   future versions
8970: 20 6f 66 20 53 51 4c 69 74 65 2e 20 20 41 64 64   of SQLite.  Add
8980: 69 74 69 6f 6e 61 6c 20 66 69 65 6c 64 73 20 6d  itional fields m
8990: 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20 74  ay be appended t
89a0: 6f 20 74 68 69 73 0a 2a 2a 20 6f 62 6a 65 63 74  o this.** object
89b0: 20 77 68 65 6e 20 74 68 65 20 69 56 65 72 73 69   when the iVersi
89c0: 6f 6e 20 76 61 6c 75 65 20 69 73 20 69 6e 63 72  on value is incr
89d0: 65 61 73 65 64 2e 20 20 4e 6f 74 65 20 74 68 61  eased.  Note tha
89e0: 74 20 74 68 65 20 73 74 72 75 63 74 75 72 65 0a  t the structure.
89f0: 2a 2a 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65  ** of the sqlite
8a00: 33 5f 76 66 73 20 6f 62 6a 65 63 74 20 63 68 61  3_vfs object cha
8a10: 6e 67 65 73 20 69 6e 20 74 68 65 20 74 72 61 6e  nges in the tran
8a20: 73 61 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 0a  saction between.
8a30: 2a 2a 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f  ** SQLite versio
8a40: 6e 20 33 2e 35 2e 39 20 61 6e 64 20 33 2e 36 2e  n 3.5.9 and 3.6.
8a50: 30 20 61 6e 64 20 79 65 74 20 74 68 65 20 69 56  0 and yet the iV
8a60: 65 72 73 69 6f 6e 20 66 69 65 6c 64 20 77 61 73  ersion field was
8a70: 20 6e 6f 74 0a 2a 2a 20 6d 6f 64 69 66 69 65 64   not.** modified
8a80: 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 7a 4f 73  ..**.** The szOs
8a90: 46 69 6c 65 20 66 69 65 6c 64 20 69 73 20 74 68  File field is th
8aa0: 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 75  e size of the su
8ab0: 62 63 6c 61 73 73 65 64 20 5b 73 71 6c 69 74 65  bclassed [sqlite
8ac0: 33 5f 66 69 6c 65 5d 0a 2a 2a 20 73 74 72 75 63  3_file].** struc
8ad0: 74 75 72 65 20 75 73 65 64 20 62 79 20 74 68 69  ture used by thi
8ae0: 73 20 56 46 53 2e 20 20 6d 78 50 61 74 68 6e 61  s VFS.  mxPathna
8af0: 6d 65 20 69 73 20 74 68 65 20 6d 61 78 69 6d 75  me is the maximu
8b00: 6d 20 6c 65 6e 67 74 68 20 6f 66 0a 2a 2a 20 61  m length of.** a
8b10: 20 70 61 74 68 6e 61 6d 65 20 69 6e 20 74 68 69   pathname in thi
8b20: 73 20 56 46 53 2e 0a 2a 2a 0a 2a 2a 20 52 65 67  s VFS..**.** Reg
8b30: 69 73 74 65 72 65 64 20 73 71 6c 69 74 65 33 5f  istered sqlite3_
8b40: 76 66 73 20 6f 62 6a 65 63 74 73 20 61 72 65 20  vfs objects are 
8b50: 6b 65 70 74 20 6f 6e 20 61 20 6c 69 6e 6b 65 64  kept on a linked
8b60: 20 6c 69 73 74 20 66 6f 72 6d 65 64 20 62 79 0a   list formed by.
8b70: 2a 2a 20 74 68 65 20 70 4e 65 78 74 20 70 6f 69  ** the pNext poi
8b80: 6e 74 65 72 2e 20 20 54 68 65 20 5b 73 71 6c 69  nter.  The [sqli
8b90: 74 65 33 5f 76 66 73 5f 72 65 67 69 73 74 65 72  te3_vfs_register
8ba0: 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
8bb0: 74 65 33 5f 76 66 73 5f 75 6e 72 65 67 69 73 74  te3_vfs_unregist
8bc0: 65 72 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73  er()] interfaces
8bd0: 20 6d 61 6e 61 67 65 20 74 68 69 73 20 6c 69 73   manage this lis
8be0: 74 0a 2a 2a 20 69 6e 20 61 20 74 68 72 65 61 64  t.** in a thread
8bf0: 2d 73 61 66 65 20 77 61 79 2e 20 20 54 68 65 20  -safe way.  The 
8c00: 5b 73 71 6c 69 74 65 33 5f 76 66 73 5f 66 69 6e  [sqlite3_vfs_fin
8c10: 64 28 29 5d 20 69 6e 74 65 72 66 61 63 65 0a 2a  d()] interface.*
8c20: 2a 20 73 65 61 72 63 68 65 73 20 74 68 65 20 6c  * searches the l
8c30: 69 73 74 2e 20 20 4e 65 69 74 68 65 72 20 74 68  ist.  Neither th
8c40: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 63 6f  e application co
8c50: 64 65 20 6e 6f 72 20 74 68 65 20 56 46 53 0a 2a  de nor the VFS.*
8c60: 2a 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  * implementation
8c70: 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65 20   should use the 
8c80: 70 4e 65 78 74 20 70 6f 69 6e 74 65 72 2e 0a 2a  pNext pointer..*
8c90: 2a 0a 2a 2a 20 54 68 65 20 70 4e 65 78 74 20 66  *.** The pNext f
8ca0: 69 65 6c 64 20 69 73 20 74 68 65 20 6f 6e 6c 79  ield is the only
8cb0: 20 66 69 65 6c 64 20 69 6e 20 74 68 65 20 73 71   field in the sq
8cc0: 6c 69 74 65 33 5f 76 66 73 0a 2a 2a 20 73 74 72  lite3_vfs.** str
8cd0: 75 63 74 75 72 65 20 74 68 61 74 20 53 51 4c 69  ucture that SQLi
8ce0: 74 65 20 77 69 6c 6c 20 65 76 65 72 20 6d 6f 64  te will ever mod
8cf0: 69 66 79 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  ify.  SQLite wil
8d00: 6c 20 6f 6e 6c 79 20 61 63 63 65 73 73 0a 2a 2a  l only access.**
8d10: 20 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20   or modify this 
8d20: 66 69 65 6c 64 20 77 68 69 6c 65 20 68 6f 6c 64  field while hold
8d30: 69 6e 67 20 61 20 70 61 72 74 69 63 75 6c 61 72  ing a particular
8d40: 20 73 74 61 74 69 63 20 6d 75 74 65 78 2e 0a 2a   static mutex..*
8d50: 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74 69 6f  * The applicatio
8d60: 6e 20 73 68 6f 75 6c 64 20 6e 65 76 65 72 20 6d  n should never m
8d70: 6f 64 69 66 79 20 61 6e 79 74 68 69 6e 67 20 77  odify anything w
8d80: 69 74 68 69 6e 20 74 68 65 20 73 71 6c 69 74 65  ithin the sqlite
8d90: 33 5f 76 66 73 0a 2a 2a 20 6f 62 6a 65 63 74 20  3_vfs.** object 
8da0: 6f 6e 63 65 20 74 68 65 20 6f 62 6a 65 63 74 20  once the object 
8db0: 68 61 73 20 62 65 65 6e 20 72 65 67 69 73 74 65  has been registe
8dc0: 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 7a  red..**.** The z
8dd0: 4e 61 6d 65 20 66 69 65 6c 64 20 68 6f 6c 64 73  Name field holds
8de0: 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
8df0: 20 56 46 53 20 6d 6f 64 75 6c 65 2e 20 20 54 68   VFS module.  Th
8e00: 65 20 6e 61 6d 65 20 6d 75 73 74 0a 2a 2a 20 62  e name must.** b
8e10: 65 20 75 6e 69 71 75 65 20 61 63 72 6f 73 73 20  e unique across 
8e20: 61 6c 6c 20 56 46 53 20 6d 6f 64 75 6c 65 73 2e  all VFS modules.
8e30: 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 67  .**.** ^SQLite g
8e40: 75 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74  uarantees that t
8e50: 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20 70 61 72  he zFilename par
8e60: 61 6d 65 74 65 72 20 74 6f 20 78 4f 70 65 6e 0a  ameter to xOpen.
8e70: 2a 2a 20 69 73 20 65 69 74 68 65 72 20 61 20 4e  ** is either a N
8e80: 55 4c 4c 20 70 6f 69 6e 74 65 72 20 6f 72 20 73  ULL pointer or s
8e90: 74 72 69 6e 67 20 6f 62 74 61 69 6e 65 64 0a 2a  tring obtained.*
8ea0: 2a 20 66 72 6f 6d 20 78 46 75 6c 6c 50 61 74 68  * from xFullPath
8eb0: 6e 61 6d 65 28 29 20 77 69 74 68 20 61 6e 20 6f  name() with an o
8ec0: 70 74 69 6f 6e 61 6c 20 73 75 66 66 69 78 20 61  ptional suffix a
8ed0: 64 64 65 64 2e 0a 2a 2a 20 5e 49 66 20 61 20 73  dded..** ^If a s
8ee0: 75 66 66 69 78 20 69 73 20 61 64 64 65 64 20 74  uffix is added t
8ef0: 6f 20 74 68 65 20 7a 46 69 6c 65 6e 61 6d 65 20  o the zFilename 
8f00: 70 61 72 61 6d 65 74 65 72 2c 20 69 74 20 77 69  parameter, it wi
8f10: 6c 6c 0a 2a 2a 20 63 6f 6e 73 69 73 74 20 6f 66  ll.** consist of
8f20: 20 61 20 73 69 6e 67 6c 65 20 22 2d 22 20 63 68   a single "-" ch
8f30: 61 72 61 63 74 65 72 20 66 6f 6c 6c 6f 77 65 64  aracter followed
8f40: 20 62 79 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e   by no more than
8f50: 0a 2a 2a 20 31 30 20 61 6c 70 68 61 6e 75 6d 65  .** 10 alphanume
8f60: 72 69 63 20 61 6e 64 2f 6f 72 20 22 2d 22 20 63  ric and/or "-" c
8f70: 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 20 5e 53  haracters..** ^S
8f80: 51 4c 69 74 65 20 66 75 72 74 68 65 72 20 67 75  QLite further gu
8f90: 61 72 61 6e 74 65 65 73 20 74 68 61 74 0a 2a 2a  arantees that.**
8fa0: 20 74 68 65 20 73 74 72 69 6e 67 20 77 69 6c 6c   the string will
8fb0: 20 62 65 20 76 61 6c 69 64 20 61 6e 64 20 75 6e   be valid and un
8fc0: 63 68 61 6e 67 65 64 20 75 6e 74 69 6c 20 78 43  changed until xC
8fd0: 6c 6f 73 65 28 29 20 69 73 0a 2a 2a 20 63 61 6c  lose() is.** cal
8fe0: 6c 65 64 2e 20 42 65 63 61 75 73 65 20 6f 66 20  led. Because of 
8ff0: 74 68 65 20 70 72 65 76 69 6f 75 73 20 73 65 6e  the previous sen
9000: 74 65 6e 63 65 2c 0a 2a 2a 20 74 68 65 20 5b 73  tence,.** the [s
9010: 71 6c 69 74 65 33 5f 66 69 6c 65 5d 20 63 61 6e  qlite3_file] can
9020: 20 73 61 66 65 6c 79 20 73 74 6f 72 65 20 61 20   safely store a 
9030: 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 0a 2a  pointer to the.*
9040: 2a 20 66 69 6c 65 6e 61 6d 65 20 69 66 20 69 74  * filename if it
9050: 20 6e 65 65 64 73 20 74 6f 20 72 65 6d 65 6d 62   needs to rememb
9060: 65 72 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20  er the filename 
9070: 66 6f 72 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2e  for some reason.
9080: 0a 2a 2a 20 49 66 20 74 68 65 20 7a 46 69 6c 65  .** If the zFile
9090: 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20 74  name parameter t
90a0: 6f 20 78 4f 70 65 6e 20 69 73 20 61 20 4e 55 4c  o xOpen is a NUL
90b0: 4c 20 70 6f 69 6e 74 65 72 20 74 68 65 6e 20 78  L pointer then x
90c0: 4f 70 65 6e 0a 2a 2a 20 6d 75 73 74 20 69 6e 76  Open.** must inv
90d0: 65 6e 74 20 69 74 73 20 6f 77 6e 20 74 65 6d 70  ent its own temp
90e0: 6f 72 61 72 79 20 6e 61 6d 65 20 66 6f 72 20 74  orary name for t
90f0: 68 65 20 66 69 6c 65 2e 20 20 5e 57 68 65 6e 65  he file.  ^Whene
9100: 76 65 72 20 74 68 65 20 0a 2a 2a 20 78 46 69 6c  ver the .** xFil
9110: 65 6e 61 6d 65 20 70 61 72 61 6d 65 74 65 72 20  ename parameter 
9120: 69 73 20 4e 55 4c 4c 20 69 74 20 77 69 6c 6c 20  is NULL it will 
9130: 61 6c 73 6f 20 62 65 20 74 68 65 20 63 61 73 65  also be the case
9140: 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 66 6c 61   that the.** fla
9150: 67 73 20 70 61 72 61 6d 65 74 65 72 20 77 69 6c  gs parameter wil
9160: 6c 20 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54  l include [SQLIT
9170: 45 5f 4f 50 45 4e 5f 44 45 4c 45 54 45 4f 4e 43  E_OPEN_DELETEONC
9180: 4c 4f 53 45 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65  LOSE]..**.** The
9190: 20 66 6c 61 67 73 20 61 72 67 75 6d 65 6e 74 20   flags argument 
91a0: 74 6f 20 78 4f 70 65 6e 28 29 20 69 6e 63 6c 75  to xOpen() inclu
91b0: 64 65 73 20 61 6c 6c 20 62 69 74 73 20 73 65 74  des all bits set
91c0: 20 69 6e 0a 2a 2a 20 74 68 65 20 66 6c 61 67 73   in.** the flags
91d0: 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 5b 73 71   argument to [sq
91e0: 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d  lite3_open_v2()]
91f0: 2e 20 20 4f 72 20 69 66 20 5b 73 71 6c 69 74 65  .  Or if [sqlite
9200: 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20 6f 72 20  3_open()].** or 
9210: 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
9220: 29 5d 20 69 73 20 75 73 65 64 2c 20 74 68 65 6e  )] is used, then
9230: 20 66 6c 61 67 73 20 69 6e 63 6c 75 64 65 73 20   flags includes 
9240: 61 74 20 6c 65 61 73 74 0a 2a 2a 20 5b 53 51 4c  at least.** [SQL
9250: 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
9260: 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f 4f 50  TE] | [SQLITE_OP
9270: 45 4e 5f 43 52 45 41 54 45 5d 2e 20 0a 2a 2a 20  EN_CREATE]. .** 
9280: 49 66 20 78 4f 70 65 6e 28 29 20 6f 70 65 6e 73  If xOpen() opens
9290: 20 61 20 66 69 6c 65 20 72 65 61 64 2d 6f 6e 6c   a file read-onl
92a0: 79 20 74 68 65 6e 20 69 74 20 73 65 74 73 20 2a  y then it sets *
92b0: 70 4f 75 74 46 6c 61 67 73 20 74 6f 0a 2a 2a 20  pOutFlags to.** 
92c0: 69 6e 63 6c 75 64 65 20 5b 53 51 4c 49 54 45 5f  include [SQLITE_
92d0: 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d 2e 20  OPEN_READONLY]. 
92e0: 20 4f 74 68 65 72 20 62 69 74 73 20 69 6e 20 2a   Other bits in *
92f0: 70 4f 75 74 46 6c 61 67 73 20 6d 61 79 20 62 65  pOutFlags may be
9300: 20 73 65 74 2e 0a 2a 2a 0a 2a 2a 20 5e 28 53 51   set..**.** ^(SQ
9310: 4c 69 74 65 20 77 69 6c 6c 20 61 6c 73 6f 20 61  Lite will also a
9320: 64 64 20 6f 6e 65 20 6f 66 20 74 68 65 20 66 6f  dd one of the fo
9330: 6c 6c 6f 77 69 6e 67 20 66 6c 61 67 73 20 74 6f  llowing flags to
9340: 20 74 68 65 20 78 4f 70 65 6e 28 29 0a 2a 2a 20   the xOpen().** 
9350: 63 61 6c 6c 2c 20 64 65 70 65 6e 64 69 6e 67 20  call, depending 
9360: 6f 6e 20 74 68 65 20 6f 62 6a 65 63 74 20 62 65  on the object be
9370: 69 6e 67 20 6f 70 65 6e 65 64 3a 0a 2a 2a 0a 2a  ing opened:.**.*
9380: 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20  * <ul>.** <li>  
9390: 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49  [SQLITE_OPEN_MAI
93a0: 4e 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b  N_DB].** <li>  [
93b0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4d 41 49 4e  SQLITE_OPEN_MAIN
93c0: 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69  _JOURNAL].** <li
93d0: 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  >  [SQLITE_OPEN_
93e0: 54 45 4d 50 5f 44 42 5d 0a 2a 2a 20 3c 6c 69 3e  TEMP_DB].** <li>
93f0: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 54    [SQLITE_OPEN_T
9400: 45 4d 50 5f 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20  EMP_JOURNAL].** 
9410: 3c 6c 69 3e 20 20 5b 53 51 4c 49 54 45 5f 4f 50  <li>  [SQLITE_OP
9420: 45 4e 5f 54 52 41 4e 53 49 45 4e 54 5f 44 42 5d  EN_TRANSIENT_DB]
9430: 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c 49 54  .** <li>  [SQLIT
9440: 45 5f 4f 50 45 4e 5f 53 55 42 4a 4f 55 52 4e 41  E_OPEN_SUBJOURNA
9450: 4c 5d 0a 2a 2a 20 3c 6c 69 3e 20 20 5b 53 51 4c  L].** <li>  [SQL
9460: 49 54 45 5f 4f 50 45 4e 5f 4d 41 53 54 45 52 5f  ITE_OPEN_MASTER_
9470: 4a 4f 55 52 4e 41 4c 5d 0a 2a 2a 20 3c 6c 69 3e  JOURNAL].** <li>
9480: 20 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 57    [SQLITE_OPEN_W
9490: 41 4c 5d 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e 0a 2a  AL].** </ul>)^.*
94a0: 2a 0a 2a 2a 20 54 68 65 20 66 69 6c 65 20 49 2f  *.** The file I/
94b0: 4f 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  O implementation
94c0: 20 63 61 6e 20 75 73 65 20 74 68 65 20 6f 62 6a   can use the obj
94d0: 65 63 74 20 74 79 70 65 20 66 6c 61 67 73 20 74  ect type flags t
94e0: 6f 0a 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20  o.** change the 
94f0: 77 61 79 20 69 74 20 64 65 61 6c 73 20 77 69 74  way it deals wit
9500: 68 20 66 69 6c 65 73 2e 20 20 46 6f 72 20 65 78  h files.  For ex
9510: 61 6d 70 6c 65 2c 20 61 6e 20 61 70 70 6c 69 63  ample, an applic
9520: 61 74 69 6f 6e 0a 2a 2a 20 74 68 61 74 20 64 6f  ation.** that do
9530: 65 73 20 6e 6f 74 20 63 61 72 65 20 61 62 6f 75  es not care abou
9540: 74 20 63 72 61 73 68 20 72 65 63 6f 76 65 72 79  t crash recovery
9550: 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20 6d 69 67   or rollback mig
9560: 68 74 20 6d 61 6b 65 0a 2a 2a 20 74 68 65 20 6f  ht make.** the o
9570: 70 65 6e 20 6f 66 20 61 20 6a 6f 75 72 6e 61 6c  pen of a journal
9580: 20 66 69 6c 65 20 61 20 6e 6f 2d 6f 70 2e 20 20   file a no-op.  
9590: 57 72 69 74 65 73 20 74 6f 20 74 68 69 73 20 6a  Writes to this j
95a0: 6f 75 72 6e 61 6c 20 77 6f 75 6c 64 0a 2a 2a 20  ournal would.** 
95b0: 61 6c 73 6f 20 62 65 20 6e 6f 2d 6f 70 73 2c 20  also be no-ops, 
95c0: 61 6e 64 20 61 6e 79 20 61 74 74 65 6d 70 74 20  and any attempt 
95d0: 74 6f 20 72 65 61 64 20 74 68 65 20 6a 6f 75 72  to read the jour
95e0: 6e 61 6c 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  nal would return
95f0: 0a 2a 2a 20 53 51 4c 49 54 45 5f 49 4f 45 52 52  .** SQLITE_IOERR
9600: 2e 20 20 4f 72 20 74 68 65 20 69 6d 70 6c 65 6d  .  Or the implem
9610: 65 6e 74 61 74 69 6f 6e 20 6d 69 67 68 74 20 72  entation might r
9620: 65 63 6f 67 6e 69 7a 65 20 74 68 61 74 20 61 20  ecognize that a 
9630: 64 61 74 61 62 61 73 65 0a 2a 2a 20 66 69 6c 65  database.** file
9640: 20 77 69 6c 6c 20 62 65 20 64 6f 69 6e 67 20 70   will be doing p
9650: 61 67 65 2d 61 6c 69 67 6e 65 64 20 73 65 63 74  age-aligned sect
9660: 6f 72 20 72 65 61 64 73 20 61 6e 64 20 77 72 69  or reads and wri
9670: 74 65 73 20 69 6e 20 61 20 72 61 6e 64 6f 6d 0a  tes in a random.
9680: 2a 2a 20 6f 72 64 65 72 20 61 6e 64 20 73 65 74  ** order and set
9690: 20 75 70 20 69 74 73 20 49 2f 4f 20 73 75 62 73   up its I/O subs
96a0: 79 73 74 65 6d 20 61 63 63 6f 72 64 69 6e 67 6c  ystem accordingl
96b0: 79 2e 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74 65 20  y..**.** SQLite 
96c0: 6d 69 67 68 74 20 61 6c 73 6f 20 61 64 64 20 6f  might also add o
96d0: 6e 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77  ne of the follow
96e0: 69 6e 67 20 66 6c 61 67 73 20 74 6f 20 74 68 65  ing flags to the
96f0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 3a 0a 2a   xOpen method:.*
9700: 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69  *.** <ul>.** <li
9710: 3e 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44  > [SQLITE_OPEN_D
9720: 45 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a  ELETEONCLOSE].**
9730: 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 4f 50   <li> [SQLITE_OP
9740: 45 4e 5f 45 58 43 4c 55 53 49 56 45 5d 0a 2a 2a  EN_EXCLUSIVE].**
9750: 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 54 68 65   </ul>.**.** The
9760: 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45   [SQLITE_OPEN_DE
9770: 4c 45 54 45 4f 4e 43 4c 4f 53 45 5d 20 66 6c 61  LETEONCLOSE] fla
9780: 67 20 6d 65 61 6e 73 20 74 68 65 20 66 69 6c 65  g means the file
9790: 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 64 65   should be.** de
97a0: 6c 65 74 65 64 20 77 68 65 6e 20 69 74 20 69 73  leted when it is
97b0: 20 63 6c 6f 73 65 64 2e 20 20 5e 54 68 65 20 5b   closed.  ^The [
97c0: 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 44 45 4c 45  SQLITE_OPEN_DELE
97d0: 54 45 4f 4e 43 4c 4f 53 45 5d 0a 2a 2a 20 77 69  TEONCLOSE].** wi
97e0: 6c 6c 20 62 65 20 73 65 74 20 66 6f 72 20 54 45  ll be set for TE
97f0: 4d 50 20 64 61 74 61 62 61 73 65 73 20 61 6e 64  MP databases and
9800: 20 74 68 65 69 72 20 6a 6f 75 72 6e 61 6c 73 2c   their journals,
9810: 20 74 72 61 6e 73 69 65 6e 74 0a 2a 2a 20 64 61   transient.** da
9820: 74 61 62 61 73 65 73 2c 20 61 6e 64 20 73 75 62  tabases, and sub
9830: 6a 6f 75 72 6e 61 6c 73 2e 0a 2a 2a 0a 2a 2a 20  journals..**.** 
9840: 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45  ^The [SQLITE_OPE
9850: 4e 5f 45 58 43 4c 55 53 49 56 45 5d 20 66 6c 61  N_EXCLUSIVE] fla
9860: 67 20 69 73 20 61 6c 77 61 79 73 20 75 73 65 64  g is always used
9870: 20 69 6e 20 63 6f 6e 6a 75 6e 63 74 69 6f 6e 0a   in conjunction.
9880: 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 53 51 4c  ** with the [SQL
9890: 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41 54 45 5d  ITE_OPEN_CREATE]
98a0: 20 66 6c 61 67 2c 20 77 68 69 63 68 20 61 72 65   flag, which are
98b0: 20 62 6f 74 68 20 64 69 72 65 63 74 6c 79 0a 2a   both directly.*
98c0: 2a 20 61 6e 61 6c 6f 67 6f 75 73 20 74 6f 20 74  * analogous to t
98d0: 68 65 20 4f 5f 45 58 43 4c 20 61 6e 64 20 4f 5f  he O_EXCL and O_
98e0: 43 52 45 41 54 20 66 6c 61 67 73 20 6f 66 20 74  CREAT flags of t
98f0: 68 65 20 50 4f 53 49 58 20 6f 70 65 6e 28 29 0a  he POSIX open().
9900: 2a 2a 20 41 50 49 2e 20 20 54 68 65 20 53 51 4c  ** API.  The SQL
9910: 49 54 45 5f 4f 50 45 4e 5f 45 58 43 4c 55 53 49  ITE_OPEN_EXCLUSI
9920: 56 45 20 66 6c 61 67 2c 20 77 68 65 6e 20 70 61  VE flag, when pa
9930: 69 72 65 64 20 77 69 74 68 20 74 68 65 20 0a 2a  ired with the .*
9940: 2a 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52  * SQLITE_OPEN_CR
9950: 45 41 54 45 2c 20 69 73 20 75 73 65 64 20 74 6f  EATE, is used to
9960: 20 69 6e 64 69 63 61 74 65 20 74 68 61 74 20 66   indicate that f
9970: 69 6c 65 20 73 68 6f 75 6c 64 20 61 6c 77 61 79  ile should alway
9980: 73 0a 2a 2a 20 62 65 20 63 72 65 61 74 65 64 2c  s.** be created,
9990: 20 61 6e 64 20 74 68 61 74 20 69 74 20 69 73 20   and that it is 
99a0: 61 6e 20 65 72 72 6f 72 20 69 66 20 69 74 20 61  an error if it a
99b0: 6c 72 65 61 64 79 20 65 78 69 73 74 73 2e 0a 2a  lready exists..*
99c0: 2a 20 49 74 20 69 73 20 3c 69 3e 6e 6f 74 3c 2f  * It is <i>not</
99d0: 69 3e 20 75 73 65 64 20 74 6f 20 69 6e 64 69 63  i> used to indic
99e0: 61 74 65 20 74 68 65 20 66 69 6c 65 20 73 68 6f  ate the file sho
99f0: 75 6c 64 20 62 65 20 6f 70 65 6e 65 64 20 0a 2a  uld be opened .*
9a00: 2a 20 66 6f 72 20 65 78 63 6c 75 73 69 76 65 20  * for exclusive 
9a10: 61 63 63 65 73 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  access..**.** ^A
9a20: 74 20 6c 65 61 73 74 20 73 7a 4f 73 46 69 6c 65  t least szOsFile
9a30: 20 62 79 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79   bytes of memory
9a40: 20 61 72 65 20 61 6c 6c 6f 63 61 74 65 64 20 62   are allocated b
9a50: 79 20 53 51 4c 69 74 65 0a 2a 2a 20 74 6f 20 68  y SQLite.** to h
9a60: 6f 6c 64 20 74 68 65 20 20 5b 73 71 6c 69 74 65  old the  [sqlite
9a70: 33 5f 66 69 6c 65 5d 20 73 74 72 75 63 74 75 72  3_file] structur
9a80: 65 20 70 61 73 73 65 64 20 61 73 20 74 68 65 20  e passed as the 
9a90: 74 68 69 72 64 0a 2a 2a 20 61 72 67 75 6d 65 6e  third.** argumen
9aa0: 74 20 74 6f 20 78 4f 70 65 6e 2e 20 20 54 68 65  t to xOpen.  The
9ab0: 20 78 4f 70 65 6e 20 6d 65 74 68 6f 64 20 64 6f   xOpen method do
9ac0: 65 73 20 6e 6f 74 20 68 61 76 65 20 74 6f 0a 2a  es not have to.*
9ad0: 2a 20 61 6c 6c 6f 63 61 74 65 20 74 68 65 20 73  * allocate the s
9ae0: 74 72 75 63 74 75 72 65 3b 20 69 74 20 73 68 6f  tructure; it sho
9af0: 75 6c 64 20 6a 75 73 74 20 66 69 6c 6c 20 69 74  uld just fill it
9b00: 20 69 6e 2e 20 20 4e 6f 74 65 20 74 68 61 74 0a   in.  Note that.
9b10: 2a 2a 20 74 68 65 20 78 4f 70 65 6e 20 6d 65 74  ** the xOpen met
9b20: 68 6f 64 20 6d 75 73 74 20 73 65 74 20 74 68 65  hod must set the
9b30: 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2e 70 4d   sqlite3_file.pM
9b40: 65 74 68 6f 64 73 20 74 6f 20 65 69 74 68 65 72  ethods to either
9b50: 0a 2a 2a 20 61 20 76 61 6c 69 64 20 5b 73 71 6c  .** a valid [sql
9b60: 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73 5d  ite3_io_methods]
9b70: 20 6f 62 6a 65 63 74 20 6f 72 20 74 6f 20 4e 55   object or to NU
9b80: 4c 4c 2e 20 20 78 4f 70 65 6e 20 6d 75 73 74 20  LL.  xOpen must 
9b90: 64 6f 0a 2a 2a 20 74 68 69 73 20 65 76 65 6e 20  do.** this even 
9ba0: 69 66 20 74 68 65 20 6f 70 65 6e 20 66 61 69 6c  if the open fail
9bb0: 73 2e 20 20 53 51 4c 69 74 65 20 65 78 70 65 63  s.  SQLite expec
9bc0: 74 73 20 74 68 61 74 20 74 68 65 20 73 71 6c 69  ts that the sqli
9bd0: 74 65 33 5f 66 69 6c 65 2e 70 4d 65 74 68 6f 64  te3_file.pMethod
9be0: 73 0a 2a 2a 20 65 6c 65 6d 65 6e 74 20 77 69 6c  s.** element wil
9bf0: 6c 20 62 65 20 76 61 6c 69 64 20 61 66 74 65 72  l be valid after
9c00: 20 78 4f 70 65 6e 20 72 65 74 75 72 6e 73 20 72   xOpen returns r
9c10: 65 67 61 72 64 6c 65 73 73 20 6f 66 20 74 68 65  egardless of the
9c20: 20 73 75 63 63 65 73 73 0a 2a 2a 20 6f 72 20 66   success.** or f
9c30: 61 69 6c 75 72 65 20 6f 66 20 74 68 65 20 78 4f  ailure of the xO
9c40: 70 65 6e 20 63 61 6c 6c 2e 0a 2a 2a 0a 2a 2a 20  pen call..**.** 
9c50: 5e 54 68 65 20 66 6c 61 67 73 20 61 72 67 75 6d  ^The flags argum
9c60: 65 6e 74 20 74 6f 20 78 41 63 63 65 73 73 28 29  ent to xAccess()
9c70: 20 6d 61 79 20 62 65 20 5b 53 51 4c 49 54 45 5f   may be [SQLITE_
9c80: 41 43 43 45 53 53 5f 45 58 49 53 54 53 5d 0a 2a  ACCESS_EXISTS].*
9c90: 2a 20 74 6f 20 74 65 73 74 20 66 6f 72 20 74 68  * to test for th
9ca0: 65 20 65 78 69 73 74 65 6e 63 65 20 6f 66 20 61  e existence of a
9cb0: 20 66 69 6c 65 2c 20 6f 72 20 5b 53 51 4c 49 54   file, or [SQLIT
9cc0: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49  E_ACCESS_READWRI
9cd0: 54 45 5d 20 74 6f 0a 2a 2a 20 74 65 73 74 20 77  TE] to.** test w
9ce0: 68 65 74 68 65 72 20 61 20 66 69 6c 65 20 69 73  hether a file is
9cf0: 20 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72   readable and wr
9d00: 69 74 61 62 6c 65 2c 20 6f 72 20 5b 53 51 4c 49  itable, or [SQLI
9d10: 54 45 5f 41 43 43 45 53 53 5f 52 45 41 44 5d 0a  TE_ACCESS_READ].
9d20: 2a 2a 20 74 6f 20 74 65 73 74 20 77 68 65 74 68  ** to test wheth
9d30: 65 72 20 61 20 66 69 6c 65 20 69 73 20 61 74 20  er a file is at 
9d40: 6c 65 61 73 74 20 72 65 61 64 61 62 6c 65 2e 20  least readable. 
9d50: 20 20 54 68 65 20 66 69 6c 65 20 63 61 6e 20 62    The file can b
9d60: 65 20 61 0a 2a 2a 20 64 69 72 65 63 74 6f 72 79  e a.** directory
9d70: 2e 0a 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ..**.** ^SQLite 
9d80: 77 69 6c 6c 20 61 6c 77 61 79 73 20 61 6c 6c 6f  will always allo
9d90: 63 61 74 65 20 61 74 20 6c 65 61 73 74 20 6d 78  cate at least mx
9da0: 50 61 74 68 6e 61 6d 65 2b 31 20 62 79 74 65 73  Pathname+1 bytes
9db0: 20 66 6f 72 20 74 68 65 0a 2a 2a 20 6f 75 74 70   for the.** outp
9dc0: 75 74 20 62 75 66 66 65 72 20 78 46 75 6c 6c 50  ut buffer xFullP
9dd0: 61 74 68 6e 61 6d 65 2e 20 20 54 68 65 20 65 78  athname.  The ex
9de0: 61 63 74 20 73 69 7a 65 20 6f 66 20 74 68 65 20  act size of the 
9df0: 6f 75 74 70 75 74 20 62 75 66 66 65 72 0a 2a 2a  output buffer.**
9e00: 20 69 73 20 61 6c 73 6f 20 70 61 73 73 65 64 20   is also passed 
9e10: 61 73 20 61 20 70 61 72 61 6d 65 74 65 72 20 74  as a parameter t
9e20: 6f 20 62 6f 74 68 20 20 6d 65 74 68 6f 64 73 2e  o both  methods.
9e30: 20 49 66 20 74 68 65 20 6f 75 74 70 75 74 20 62   If the output b
9e40: 75 66 66 65 72 0a 2a 2a 20 69 73 20 6e 6f 74 20  uffer.** is not 
9e50: 6c 61 72 67 65 20 65 6e 6f 75 67 68 2c 20 5b 53  large enough, [S
9e60: 51 4c 49 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20  QLITE_CANTOPEN] 
9e70: 73 68 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e  should be return
9e80: 65 64 2e 20 53 69 6e 63 65 20 74 68 69 73 20 69  ed. Since this i
9e90: 73 0a 2a 2a 20 68 61 6e 64 6c 65 64 20 61 73 20  s.** handled as 
9ea0: 61 20 66 61 74 61 6c 20 65 72 72 6f 72 20 62 79  a fatal error by
9eb0: 20 53 51 4c 69 74 65 2c 20 76 66 73 20 69 6d 70   SQLite, vfs imp
9ec0: 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20 73 68 6f  lementations sho
9ed0: 75 6c 64 20 65 6e 64 65 61 76 6f 72 0a 2a 2a 20  uld endeavor.** 
9ee0: 74 6f 20 70 72 65 76 65 6e 74 20 74 68 69 73 20  to prevent this 
9ef0: 62 79 20 73 65 74 74 69 6e 67 20 6d 78 50 61 74  by setting mxPat
9f00: 68 6e 61 6d 65 20 74 6f 20 61 20 73 75 66 66 69  hname to a suffi
9f10: 63 69 65 6e 74 6c 79 20 6c 61 72 67 65 20 76 61  ciently large va
9f20: 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78  lue..**.** The x
9f30: 52 61 6e 64 6f 6d 6e 65 73 73 28 29 2c 20 78 53  Randomness(), xS
9f40: 6c 65 65 70 28 29 2c 20 78 43 75 72 72 65 6e 74  leep(), xCurrent
9f50: 54 69 6d 65 28 29 2c 20 61 6e 64 20 78 43 75 72  Time(), and xCur
9f60: 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 28 29 0a  rentTimeInt64().
9f70: 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20 61 72  ** interfaces ar
9f80: 65 20 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 61  e not strictly a
9f90: 20 70 61 72 74 20 6f 66 20 74 68 65 20 66 69 6c   part of the fil
9fa0: 65 73 79 73 74 65 6d 2c 20 62 75 74 20 74 68 65  esystem, but the
9fb0: 79 20 61 72 65 0a 2a 2a 20 69 6e 63 6c 75 64 65  y are.** include
9fc0: 64 20 69 6e 20 74 68 65 20 56 46 53 20 73 74 72  d in the VFS str
9fd0: 75 63 74 75 72 65 20 66 6f 72 20 63 6f 6d 70 6c  ucture for compl
9fe0: 65 74 65 6e 65 73 73 2e 0a 2a 2a 20 54 68 65 20  eteness..** The 
9ff0: 78 52 61 6e 64 6f 6d 6e 65 73 73 28 29 20 66 75  xRandomness() fu
a000: 6e 63 74 69 6f 6e 20 61 74 74 65 6d 70 74 73 20  nction attempts 
a010: 74 6f 20 72 65 74 75 72 6e 20 6e 42 79 74 65 73  to return nBytes
a020: 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 67 6f 6f   bytes.** of goo
a030: 64 2d 71 75 61 6c 69 74 79 20 72 61 6e 64 6f 6d  d-quality random
a040: 6e 65 73 73 20 69 6e 74 6f 20 7a 4f 75 74 2e 20  ness into zOut. 
a050: 20 54 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   The return valu
a060: 65 20 69 73 0a 2a 2a 20 74 68 65 20 61 63 74 75  e is.** the actu
a070: 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  al number of byt
a080: 65 73 20 6f 66 20 72 61 6e 64 6f 6d 6e 65 73 73  es of randomness
a090: 20 6f 62 74 61 69 6e 65 64 2e 0a 2a 2a 20 54 68   obtained..** Th
a0a0: 65 20 78 53 6c 65 65 70 28 29 20 6d 65 74 68 6f  e xSleep() metho
a0b0: 64 20 63 61 75 73 65 73 20 74 68 65 20 63 61 6c  d causes the cal
a0c0: 6c 69 6e 67 20 74 68 72 65 61 64 20 74 6f 20 73  ling thread to s
a0d0: 6c 65 65 70 20 66 6f 72 20 61 74 0a 2a 2a 20 6c  leep for at.** l
a0e0: 65 61 73 74 20 74 68 65 20 6e 75 6d 62 65 72 20  east the number 
a0f0: 6f 66 20 6d 69 63 72 6f 73 65 63 6f 6e 64 73 20  of microseconds 
a100: 67 69 76 65 6e 2e 20 20 5e 54 68 65 20 78 43 75  given.  ^The xCu
a110: 72 72 65 6e 74 54 69 6d 65 28 29 0a 2a 2a 20 6d  rrentTime().** m
a120: 65 74 68 6f 64 20 72 65 74 75 72 6e 73 20 61 20  ethod returns a 
a130: 4a 75 6c 69 61 6e 20 44 61 79 20 4e 75 6d 62 65  Julian Day Numbe
a140: 72 20 66 6f 72 20 74 68 65 20 63 75 72 72 65 6e  r for the curren
a150: 74 20 64 61 74 65 20 61 6e 64 20 74 69 6d 65 20  t date and time 
a160: 61 73 0a 2a 2a 20 61 20 66 6c 6f 61 74 69 6e 67  as.** a floating
a170: 20 70 6f 69 6e 74 20 76 61 6c 75 65 2e 0a 2a 2a   point value..**
a180: 20 5e 54 68 65 20 78 43 75 72 72 65 6e 74 54 69   ^The xCurrentTi
a190: 6d 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64  meInt64() method
a1a0: 20 72 65 74 75 72 6e 73 2c 20 61 73 20 61 6e 20   returns, as an 
a1b0: 69 6e 74 65 67 65 72 2c 20 74 68 65 20 4a 75 6c  integer, the Jul
a1c0: 69 61 6e 0a 2a 2a 20 44 61 79 20 4e 75 6d 62 65  ian.** Day Numbe
a1d0: 72 20 6d 75 6c 74 69 70 6c 65 64 20 62 79 20 38  r multipled by 8
a1e0: 36 34 30 30 30 30 30 20 28 74 68 65 20 6e 75 6d  6400000 (the num
a1f0: 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63 6f  ber of milliseco
a200: 6e 64 73 20 69 6e 20 0a 2a 2a 20 61 20 32 34 2d  nds in .** a 24-
a210: 68 6f 75 72 20 64 61 79 29 2e 20 20 0a 2a 2a 20  hour day).  .** 
a220: 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75 73 65  ^SQLite will use
a230: 20 74 68 65 20 78 43 75 72 72 65 6e 74 54 69 6d   the xCurrentTim
a240: 65 49 6e 74 36 34 28 29 20 6d 65 74 68 6f 64 20  eInt64() method 
a250: 74 6f 20 67 65 74 20 74 68 65 20 63 75 72 72 65  to get the curre
a260: 6e 74 0a 2a 2a 20 64 61 74 65 20 61 6e 64 20 74  nt.** date and t
a270: 69 6d 65 20 69 66 20 74 68 61 74 20 6d 65 74 68  ime if that meth
a280: 6f 64 20 69 73 20 61 76 61 69 6c 61 62 6c 65 20  od is available 
a290: 28 69 66 20 69 56 65 72 73 69 6f 6e 20 69 73 20  (if iVersion is 
a2a0: 32 20 6f 72 20 0a 2a 2a 20 67 72 65 61 74 65 72  2 or .** greater
a2b0: 20 61 6e 64 20 74 68 65 20 66 75 6e 63 74 69 6f   and the functio
a2c0: 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74  n pointer is not
a2d0: 20 4e 55 4c 4c 29 20 61 6e 64 20 77 69 6c 6c 20   NULL) and will 
a2e0: 66 61 6c 6c 20 62 61 63 6b 0a 2a 2a 20 74 6f 20  fall back.** to 
a2f0: 78 43 75 72 72 65 6e 74 54 69 6d 65 28 29 20 69  xCurrentTime() i
a300: 66 20 78 43 75 72 72 65 6e 74 54 69 6d 65 49 6e  f xCurrentTimeIn
a310: 74 36 34 28 29 20 69 73 20 75 6e 61 76 61 69 6c  t64() is unavail
a320: 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  able..**.** ^The
a330: 20 78 53 65 74 53 79 73 74 65 6d 43 61 6c 6c 28   xSetSystemCall(
a340: 29 2c 20 78 47 65 74 53 79 73 74 65 6d 43 61 6c  ), xGetSystemCal
a350: 6c 28 29 2c 20 61 6e 64 20 78 4e 65 73 74 53 79  l(), and xNestSy
a360: 73 74 65 6d 43 61 6c 6c 28 29 20 69 6e 74 65 72  stemCall() inter
a370: 66 61 63 65 73 0a 2a 2a 20 61 72 65 20 6e 6f 74  faces.** are not
a380: 20 75 73 65 64 20 62 79 20 74 68 65 20 53 51 4c   used by the SQL
a390: 69 74 65 20 63 6f 72 65 2e 20 20 54 68 65 73 65  ite core.  These
a3a0: 20 6f 70 74 69 6f 6e 61 6c 20 69 6e 74 65 72 66   optional interf
a3b0: 61 63 65 73 20 61 72 65 20 70 72 6f 76 69 64 65  aces are provide
a3c0: 64 0a 2a 2a 20 62 79 20 73 6f 6d 65 20 56 46 53  d.** by some VFS
a3d0: 65 73 20 74 6f 20 66 61 63 69 6c 69 74 61 74 65  es to facilitate
a3e0: 20 74 65 73 74 69 6e 67 20 6f 66 20 74 68 65 20   testing of the 
a3f0: 56 46 53 20 63 6f 64 65 2e 20 42 79 20 6f 76 65  VFS code. By ove
a400: 72 72 69 64 69 6e 67 20 0a 2a 2a 20 73 79 73 74  rriding .** syst
a410: 65 6d 20 63 61 6c 6c 73 20 77 69 74 68 20 66 75  em calls with fu
a420: 6e 63 74 69 6f 6e 73 20 75 6e 64 65 72 20 69 74  nctions under it
a430: 73 20 63 6f 6e 74 72 6f 6c 2c 20 61 20 74 65 73  s control, a tes
a440: 74 20 70 72 6f 67 72 61 6d 20 63 61 6e 0a 2a 2a  t program can.**
a450: 20 73 69 6d 75 6c 61 74 65 20 66 61 75 6c 74 73   simulate faults
a460: 20 61 6e 64 20 65 72 72 6f 72 20 63 6f 6e 64 69   and error condi
a470: 74 69 6f 6e 73 20 74 68 61 74 20 77 6f 75 6c 64  tions that would
a480: 20 6f 74 68 65 72 77 69 73 65 20 62 65 20 64 69   otherwise be di
a490: 66 66 69 63 75 6c 74 0a 2a 2a 20 6f 72 20 69 6d  fficult.** or im
a4a0: 70 6f 73 73 69 62 6c 65 20 74 6f 20 69 6e 64 75  possible to indu
a4b0: 63 65 2e 20 20 54 68 65 20 73 65 74 20 6f 66 20  ce.  The set of 
a4c0: 73 79 73 74 65 6d 20 63 61 6c 6c 73 20 74 68 61  system calls tha
a4d0: 74 20 63 61 6e 20 62 65 20 6f 76 65 72 72 69 64  t can be overrid
a4e0: 64 65 6e 0a 2a 2a 20 76 61 72 69 65 73 20 66 72  den.** varies fr
a4f0: 6f 6d 20 6f 6e 65 20 56 46 53 20 74 6f 20 61 6e  om one VFS to an
a500: 6f 74 68 65 72 2c 20 61 6e 64 20 66 72 6f 6d 20  other, and from 
a510: 6f 6e 65 20 76 65 72 73 69 6f 6e 20 6f 66 20 74  one version of t
a520: 68 65 20 73 61 6d 65 20 56 46 53 20 74 6f 20 74  he same VFS to t
a530: 68 65 0a 2a 2a 20 6e 65 78 74 2e 20 20 41 70 70  he.** next.  App
a540: 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20 75  lications that u
a550: 73 65 20 74 68 65 73 65 20 69 6e 74 65 72 66 61  se these interfa
a560: 63 65 73 20 6d 75 73 74 20 62 65 20 70 72 65 70  ces must be prep
a570: 61 72 65 64 20 66 6f 72 20 61 6e 79 0a 2a 2a 20  ared for any.** 
a580: 6f 72 20 61 6c 6c 20 6f 66 20 74 68 65 73 65 20  or all of these 
a590: 69 6e 74 65 72 66 61 63 65 73 20 74 6f 20 62 65  interfaces to be
a5a0: 20 4e 55 4c 4c 20 6f 72 20 66 6f 72 20 74 68 65   NULL or for the
a5b0: 69 72 20 62 65 68 61 76 69 6f 72 20 74 6f 20 63  ir behavior to c
a5c0: 68 61 6e 67 65 0a 2a 2a 20 66 72 6f 6d 20 6f 6e  hange.** from on
a5d0: 65 20 72 65 6c 65 61 73 65 20 74 6f 20 74 68 65  e release to the
a5e0: 20 6e 65 78 74 2e 20 20 41 70 70 6c 69 63 61 74   next.  Applicat
a5f0: 69 6f 6e 73 20 6d 75 73 74 20 6e 6f 74 20 61 74  ions must not at
a600: 74 65 6d 70 74 20 74 6f 20 61 63 63 65 73 73 0a  tempt to access.
a610: 2a 2a 20 61 6e 79 20 6f 66 20 74 68 65 73 65 20  ** any of these 
a620: 6d 65 74 68 6f 64 73 20 69 66 20 74 68 65 20 69  methods if the i
a630: 56 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20 56  Version of the V
a640: 46 53 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20  FS is less than 
a650: 33 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  3..*/.typedef st
a660: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 66 73  ruct sqlite3_vfs
a670: 20 73 71 6c 69 74 65 33 5f 76 66 73 3b 0a 74 79   sqlite3_vfs;.ty
a680: 70 65 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c  pedef void (*sql
a690: 69 74 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72  ite3_syscall_ptr
a6a0: 29 28 76 6f 69 64 29 3b 0a 73 74 72 75 63 74 20  )(void);.struct 
a6b0: 73 71 6c 69 74 65 33 5f 76 66 73 20 7b 0a 20 20  sqlite3_vfs {.  
a6c0: 69 6e 74 20 69 56 65 72 73 69 6f 6e 3b 20 20 20  int iVersion;   
a6d0: 20 20 20 20 20 20 20 20 20 2f 2a 20 53 74 72 75           /* Stru
a6e0: 63 74 75 72 65 20 76 65 72 73 69 6f 6e 20 6e 75  cture version nu
a6f0: 6d 62 65 72 20 28 63 75 72 72 65 6e 74 6c 79 20  mber (currently 
a700: 33 29 20 2a 2f 0a 20 20 69 6e 74 20 73 7a 4f 73  3) */.  int szOs
a710: 46 69 6c 65 3b 20 20 20 20 20 20 20 20 20 20 20  File;           
a720: 20 2f 2a 20 53 69 7a 65 20 6f 66 20 73 75 62 63   /* Size of subc
a730: 6c 61 73 73 65 64 20 73 71 6c 69 74 65 33 5f 66  lassed sqlite3_f
a740: 69 6c 65 20 2a 2f 0a 20 20 69 6e 74 20 6d 78 50  ile */.  int mxP
a750: 61 74 68 6e 61 6d 65 3b 20 20 20 20 20 20 20 20  athname;        
a760: 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 66 69 6c    /* Maximum fil
a770: 65 20 70 61 74 68 6e 61 6d 65 20 6c 65 6e 67 74  e pathname lengt
a780: 68 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 76  h */.  sqlite3_v
a790: 66 73 20 2a 70 4e 65 78 74 3b 20 20 20 20 20 20  fs *pNext;      
a7a0: 2f 2a 20 4e 65 78 74 20 72 65 67 69 73 74 65 72  /* Next register
a7b0: 65 64 20 56 46 53 20 2a 2f 0a 20 20 63 6f 6e 73  ed VFS */.  cons
a7c0: 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 3b 20 20  t char *zName;  
a7d0: 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20       /* Name of 
a7e0: 74 68 69 73 20 76 69 72 74 75 61 6c 20 66 69 6c  this virtual fil
a7f0: 65 20 73 79 73 74 65 6d 20 2a 2f 0a 20 20 76 6f  e system */.  vo
a800: 69 64 20 2a 70 41 70 70 44 61 74 61 3b 20 20 20  id *pAppData;   
a810: 20 20 20 20 20 20 20 2f 2a 20 50 6f 69 6e 74 65         /* Pointe
a820: 72 20 74 6f 20 61 70 70 6c 69 63 61 74 69 6f 6e  r to application
a830: 2d 73 70 65 63 69 66 69 63 20 64 61 74 61 20 2a  -specific data *
a840: 2f 0a 20 20 69 6e 74 20 28 2a 78 4f 70 65 6e 29  /.  int (*xOpen)
a850: 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63  (sqlite3_vfs*, c
a860: 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65  onst char *zName
a870: 2c 20 73 71 6c 69 74 65 33 5f 66 69 6c 65 2a 2c  , sqlite3_file*,
a880: 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
a890: 69 6e 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a  int flags, int *
a8a0: 70 4f 75 74 46 6c 61 67 73 29 3b 0a 20 20 69 6e  pOutFlags);.  in
a8b0: 74 20 28 2a 78 44 65 6c 65 74 65 29 28 73 71 6c  t (*xDelete)(sql
a8c0: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a8d0: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a8e0: 74 20 73 79 6e 63 44 69 72 29 3b 0a 20 20 69 6e  t syncDir);.  in
a8f0: 74 20 28 2a 78 41 63 63 65 73 73 29 28 73 71 6c  t (*xAccess)(sql
a900: 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74  ite3_vfs*, const
a910: 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 69 6e   char *zName, in
a920: 74 20 66 6c 61 67 73 2c 20 69 6e 74 20 2a 70 52  t flags, int *pR
a930: 65 73 4f 75 74 29 3b 0a 20 20 69 6e 74 20 28 2a  esOut);.  int (*
a940: 78 46 75 6c 6c 50 61 74 68 6e 61 6d 65 29 28 73  xFullPathname)(s
a950: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e  qlite3_vfs*, con
a960: 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
a970: 69 6e 74 20 6e 4f 75 74 2c 20 63 68 61 72 20 2a  int nOut, char *
a980: 7a 4f 75 74 29 3b 0a 20 20 76 6f 69 64 20 2a 28  zOut);.  void *(
a990: 2a 78 44 6c 4f 70 65 6e 29 28 73 71 6c 69 74 65  *xDlOpen)(sqlite
a9a0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
a9b0: 61 72 20 2a 7a 46 69 6c 65 6e 61 6d 65 29 3b 0a  ar *zFilename);.
a9c0: 20 20 76 6f 69 64 20 28 2a 78 44 6c 45 72 72 6f    void (*xDlErro
a9d0: 72 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  r)(sqlite3_vfs*,
a9e0: 20 69 6e 74 20 6e 42 79 74 65 2c 20 63 68 61 72   int nByte, char
a9f0: 20 2a 7a 45 72 72 4d 73 67 29 3b 0a 20 20 76 6f   *zErrMsg);.  vo
aa00: 69 64 20 28 2a 28 2a 78 44 6c 53 79 6d 29 28 73  id (*(*xDlSym)(s
aa10: 71 6c 69 74 65 33 5f 76 66 73 2a 2c 76 6f 69 64  qlite3_vfs*,void
aa20: 2a 2c 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a  *, const char *z
aa30: 53 79 6d 62 6f 6c 29 29 28 76 6f 69 64 29 3b 0a  Symbol))(void);.
aa40: 20 20 76 6f 69 64 20 28 2a 78 44 6c 43 6c 6f 73    void (*xDlClos
aa50: 65 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c  e)(sqlite3_vfs*,
aa60: 20 76 6f 69 64 2a 29 3b 0a 20 20 69 6e 74 20 28   void*);.  int (
aa70: 2a 78 52 61 6e 64 6f 6d 6e 65 73 73 29 28 73 71  *xRandomness)(sq
aa80: 6c 69 74 65 33 5f 76 66 73 2a 2c 20 69 6e 74 20  lite3_vfs*, int 
aa90: 6e 42 79 74 65 2c 20 63 68 61 72 20 2a 7a 4f 75  nByte, char *zOu
aaa0: 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 6c 65  t);.  int (*xSle
aab0: 65 70 29 28 73 71 6c 69 74 65 33 5f 76 66 73 2a  ep)(sqlite3_vfs*
aac0: 2c 20 69 6e 74 20 6d 69 63 72 6f 73 65 63 6f 6e  , int microsecon
aad0: 64 73 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43 75  ds);.  int (*xCu
aae0: 72 72 65 6e 74 54 69 6d 65 29 28 73 71 6c 69 74  rrentTime)(sqlit
aaf0: 65 33 5f 76 66 73 2a 2c 20 64 6f 75 62 6c 65 2a  e3_vfs*, double*
ab00: 29 3b 0a 20 20 69 6e 74 20 28 2a 78 47 65 74 4c  );.  int (*xGetL
ab10: 61 73 74 45 72 72 6f 72 29 28 73 71 6c 69 74 65  astError)(sqlite
ab20: 33 5f 76 66 73 2a 2c 20 69 6e 74 2c 20 63 68 61  3_vfs*, int, cha
ab30: 72 20 2a 29 3b 0a 20 20 2f 2a 0a 20 20 2a 2a 20  r *);.  /*.  ** 
ab40: 54 68 65 20 6d 65 74 68 6f 64 73 20 61 62 6f 76  The methods abov
ab50: 65 20 61 72 65 20 69 6e 20 76 65 72 73 69 6f 6e  e are in version
ab60: 20 31 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   1 of the sqlite
ab70: 5f 76 66 73 20 6f 62 6a 65 63 74 0a 20 20 2a 2a  _vfs object.  **
ab80: 20 64 65 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68   definition.  Th
ab90: 6f 73 65 20 74 68 61 74 20 66 6f 6c 6c 6f 77 20  ose that follow 
aba0: 61 72 65 20 61 64 64 65 64 20 69 6e 20 76 65 72  are added in ver
abb0: 73 69 6f 6e 20 32 20 6f 72 20 6c 61 74 65 72 0a  sion 2 or later.
abc0: 20 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78 43 75    */.  int (*xCu
abd0: 72 72 65 6e 74 54 69 6d 65 49 6e 74 36 34 29 28  rrentTimeInt64)(
abe0: 73 71 6c 69 74 65 33 5f 76 66 73 2a 2c 20 73 71  sqlite3_vfs*, sq
abf0: 6c 69 74 65 33 5f 69 6e 74 36 34 2a 29 3b 0a 20  lite3_int64*);. 
ac00: 20 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74   /*.  ** The met
ac10: 68 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69  hods above are i
ac20: 6e 20 76 65 72 73 69 6f 6e 73 20 31 20 61 6e 64  n versions 1 and
ac30: 20 32 20 6f 66 20 74 68 65 20 73 71 6c 69 74 65   2 of the sqlite
ac40: 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a 20 20 2a  _vfs object..  *
ac50: 2a 20 54 68 6f 73 65 20 62 65 6c 6f 77 20 61 72  * Those below ar
ac60: 65 20 66 6f 72 20 76 65 72 73 69 6f 6e 20 33 20  e for version 3 
ac70: 61 6e 64 20 67 72 65 61 74 65 72 2e 0a 20 20 2a  and greater..  *
ac80: 2f 0a 20 20 69 6e 74 20 28 2a 78 53 65 74 53 79  /.  int (*xSetSy
ac90: 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65  stemCall)(sqlite
aca0: 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68  3_vfs*, const ch
acb0: 61 72 20 2a 7a 4e 61 6d 65 2c 20 73 71 6c 69 74  ar *zName, sqlit
acc0: 65 33 5f 73 79 73 63 61 6c 6c 5f 70 74 72 29 3b  e3_syscall_ptr);
acd0: 0a 20 20 73 71 6c 69 74 65 33 5f 73 79 73 63 61  .  sqlite3_sysca
ace0: 6c 6c 5f 70 74 72 20 28 2a 78 47 65 74 53 79 73  ll_ptr (*xGetSys
acf0: 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69 74 65 33  temCall)(sqlite3
ad00: 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20 63 68 61  _vfs*, const cha
ad10: 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20 63 6f 6e  r *zName);.  con
ad20: 73 74 20 63 68 61 72 20 2a 28 2a 78 4e 65 78 74  st char *(*xNext
ad30: 53 79 73 74 65 6d 43 61 6c 6c 29 28 73 71 6c 69  SystemCall)(sqli
ad40: 74 65 33 5f 76 66 73 2a 2c 20 63 6f 6e 73 74 20  te3_vfs*, const 
ad50: 63 68 61 72 20 2a 7a 4e 61 6d 65 29 3b 0a 20 20  char *zName);.  
ad60: 2f 2a 0a 20 20 2a 2a 20 54 68 65 20 6d 65 74 68  /*.  ** The meth
ad70: 6f 64 73 20 61 62 6f 76 65 20 61 72 65 20 69 6e  ods above are in
ad80: 20 76 65 72 73 69 6f 6e 73 20 31 20 74 68 72 6f   versions 1 thro
ad90: 75 67 68 20 33 20 6f 66 20 74 68 65 20 73 71 6c  ugh 3 of the sql
ada0: 69 74 65 5f 76 66 73 20 6f 62 6a 65 63 74 2e 0a  ite_vfs object..
adb0: 20 20 2a 2a 20 4e 65 77 20 66 69 65 6c 64 73 20    ** New fields 
adc0: 6d 61 79 20 62 65 20 61 70 70 65 6e 64 65 64 20  may be appended 
add0: 69 6e 20 66 69 67 75 72 65 20 76 65 72 73 69 6f  in figure versio
ade0: 6e 73 2e 20 20 54 68 65 20 69 56 65 72 73 69 6f  ns.  The iVersio
adf0: 6e 0a 20 20 2a 2a 20 76 61 6c 75 65 20 77 69 6c  n.  ** value wil
ae00: 6c 20 69 6e 63 72 65 6d 65 6e 74 20 77 68 65 6e  l increment when
ae10: 65 76 65 72 20 74 68 69 73 20 68 61 70 70 65 6e  ever this happen
ae20: 73 2e 20 0a 20 20 2a 2f 0a 7d 3b 0a 0a 2f 2a 0a  s. .  */.};../*.
ae30: 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6c 61  ** CAPI3REF: Fla
ae40: 67 73 20 66 6f 72 20 74 68 65 20 78 41 63 63 65  gs for the xAcce
ae50: 73 73 20 56 46 53 20 6d 65 74 68 6f 64 0a 2a 2a  ss VFS method.**
ae60: 0a 2a 2a 20 54 68 65 73 65 20 69 6e 74 65 67 65  .** These intege
ae70: 72 20 63 6f 6e 73 74 61 6e 74 73 20 63 61 6e 20  r constants can 
ae80: 62 65 20 75 73 65 64 20 61 73 20 74 68 65 20 74  be used as the t
ae90: 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74  hird parameter t
aea0: 6f 0a 2a 2a 20 74 68 65 20 78 41 63 63 65 73 73  o.** the xAccess
aeb0: 20 6d 65 74 68 6f 64 20 6f 66 20 61 6e 20 5b 73   method of an [s
aec0: 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65  qlite3_vfs] obje
aed0: 63 74 2e 20 20 54 68 65 79 20 64 65 74 65 72 6d  ct.  They determ
aee0: 69 6e 65 0a 2a 2a 20 77 68 61 74 20 6b 69 6e 64  ine.** what kind
aef0: 20 6f 66 20 70 65 72 6d 69 73 73 69 6f 6e 73 20   of permissions 
af00: 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68  the xAccess meth
af10: 6f 64 20 69 73 20 6c 6f 6f 6b 69 6e 67 20 66 6f  od is looking fo
af20: 72 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  r..** With SQLIT
af30: 45 5f 41 43 43 45 53 53 5f 45 58 49 53 54 53 2c  E_ACCESS_EXISTS,
af40: 20 74 68 65 20 78 41 63 63 65 73 73 20 6d 65 74   the xAccess met
af50: 68 6f 64 0a 2a 2a 20 73 69 6d 70 6c 79 20 63 68  hod.** simply ch
af60: 65 63 6b 73 20 77 68 65 74 68 65 72 20 74 68 65  ecks whether the
af70: 20 66 69 6c 65 20 65 78 69 73 74 73 2e 0a 2a 2a   file exists..**
af80: 20 57 69 74 68 20 53 51 4c 49 54 45 5f 41 43 43   With SQLITE_ACC
af90: 45 53 53 5f 52 45 41 44 57 52 49 54 45 2c 20 74  ESS_READWRITE, t
afa0: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
afb0: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
afc0: 68 65 72 20 74 68 65 20 6e 61 6d 65 64 20 64 69  her the named di
afd0: 72 65 63 74 6f 72 79 20 69 73 20 62 6f 74 68 20  rectory is both 
afe0: 72 65 61 64 61 62 6c 65 20 61 6e 64 20 77 72 69  readable and wri
aff0: 74 61 62 6c 65 0a 2a 2a 20 28 69 6e 20 6f 74 68  table.** (in oth
b000: 65 72 20 77 6f 72 64 73 2c 20 69 66 20 66 69 6c  er words, if fil
b010: 65 73 20 63 61 6e 20 62 65 20 61 64 64 65 64 2c  es can be added,
b020: 20 72 65 6d 6f 76 65 64 2c 20 61 6e 64 20 72 65   removed, and re
b030: 6e 61 6d 65 64 20 77 69 74 68 69 6e 0a 2a 2a 20  named within.** 
b040: 74 68 65 20 64 69 72 65 63 74 6f 72 79 29 2e 0a  the directory)..
b050: 2a 2a 20 54 68 65 20 53 51 4c 49 54 45 5f 41 43  ** The SQLITE_AC
b060: 43 45 53 53 5f 52 45 41 44 57 52 49 54 45 20 63  CESS_READWRITE c
b070: 6f 6e 73 74 61 6e 74 20 69 73 20 63 75 72 72 65  onstant is curre
b080: 6e 74 6c 79 20 75 73 65 64 20 6f 6e 6c 79 20 62  ntly used only b
b090: 79 20 74 68 65 0a 2a 2a 20 5b 74 65 6d 70 5f 73  y the.** [temp_s
b0a0: 74 6f 72 65 5f 64 69 72 65 63 74 6f 72 79 20 70  tore_directory p
b0b0: 72 61 67 6d 61 5d 2c 20 74 68 6f 75 67 68 20 74  ragma], though t
b0c0: 68 69 73 20 63 6f 75 6c 64 20 63 68 61 6e 67 65  his could change
b0d0: 20 69 6e 20 61 20 66 75 74 75 72 65 0a 2a 2a 20   in a future.** 
b0e0: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
b0f0: 65 2e 0a 2a 2a 20 57 69 74 68 20 53 51 4c 49 54  e..** With SQLIT
b100: 45 5f 41 43 43 45 53 53 5f 52 45 41 44 2c 20 74  E_ACCESS_READ, t
b110: 68 65 20 78 41 63 63 65 73 73 20 6d 65 74 68 6f  he xAccess metho
b120: 64 0a 2a 2a 20 63 68 65 63 6b 73 20 77 68 65 74  d.** checks whet
b130: 68 65 72 20 74 68 65 20 66 69 6c 65 20 69 73 20  her the file is 
b140: 72 65 61 64 61 62 6c 65 2e 20 20 54 68 65 20 53  readable.  The S
b150: 51 4c 49 54 45 5f 41 43 43 45 53 53 5f 52 45 41  QLITE_ACCESS_REA
b160: 44 20 63 6f 6e 73 74 61 6e 74 20 69 73 0a 2a 2a  D constant is.**
b170: 20 63 75 72 72 65 6e 74 6c 79 20 75 6e 75 73 65   currently unuse
b180: 64 2c 20 74 68 6f 75 67 68 20 69 74 20 6d 69 67  d, though it mig
b190: 68 74 20 62 65 20 75 73 65 64 20 69 6e 20 61 20  ht be used in a 
b1a0: 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f  future release o
b1b0: 66 0a 2a 2a 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a  f.** SQLite..*/.
b1c0: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b1d0: 43 43 45 53 53 5f 45 58 49 53 54 53 20 20 20 20  CCESS_EXISTS    
b1e0: 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
b1f0: 5f 41 43 43 45 53 53 5f 52 45 41 44 57 52 49 54  _ACCESS_READWRIT
b200: 45 20 31 20 20 20 2f 2a 20 55 73 65 64 20 62 79  E 1   /* Used by
b210: 20 50 52 41 47 4d 41 20 74 65 6d 70 5f 73 74 6f   PRAGMA temp_sto
b220: 72 65 5f 64 69 72 65 63 74 6f 72 79 20 2a 2f 0a  re_directory */.
b230: 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41  #define SQLITE_A
b240: 43 43 45 53 53 5f 52 45 41 44 20 20 20 20 20 20  CCESS_READ      
b250: 32 20 20 20 2f 2a 20 55 6e 75 73 65 64 20 2a 2f  2   /* Unused */
b260: 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
b270: 3a 20 46 6c 61 67 73 20 66 6f 72 20 74 68 65 20  : Flags for the 
b280: 78 53 68 6d 4c 6f 63 6b 20 56 46 53 20 6d 65 74  xShmLock VFS met
b290: 68 6f 64 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  hod.**.** These 
b2a0: 69 6e 74 65 67 65 72 20 63 6f 6e 73 74 61 6e 74  integer constant
b2b0: 73 20 64 65 66 69 6e 65 20 74 68 65 20 76 61 72  s define the var
b2c0: 69 6f 75 73 20 6c 6f 63 6b 69 6e 67 20 6f 70 65  ious locking ope
b2d0: 72 61 74 69 6f 6e 73 0a 2a 2a 20 61 6c 6c 6f 77  rations.** allow
b2e0: 65 64 20 62 79 20 74 68 65 20 78 53 68 6d 4c 6f  ed by the xShmLo
b2f0: 63 6b 20 6d 65 74 68 6f 64 20 6f 66 20 5b 73 71  ck method of [sq
b300: 6c 69 74 65 33 5f 69 6f 5f 6d 65 74 68 6f 64 73  lite3_io_methods
b310: 5d 2e 20 20 54 68 65 0a 2a 2a 20 66 6f 6c 6c 6f  ].  The.** follo
b320: 77 69 6e 67 20 61 72 65 20 74 68 65 20 6f 6e 6c  wing are the onl
b330: 79 20 6c 65 67 61 6c 20 63 6f 6d 62 69 6e 61 74  y legal combinat
b340: 69 6f 6e 73 20 6f 66 20 66 6c 61 67 73 20 74 6f  ions of flags to
b350: 20 74 68 65 0a 2a 2a 20 78 53 68 6d 4c 6f 63 6b   the.** xShmLock
b360: 20 6d 65 74 68 6f 64 3a 0a 2a 2a 0a 2a 2a 20 3c   method:.**.** <
b370: 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c  ul>.** <li>  SQL
b380: 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53  ITE_SHM_LOCK | S
b390: 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44  QLITE_SHM_SHARED
b3a0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b3b0: 5f 53 48 4d 5f 4c 4f 43 4b 20 7c 20 53 51 4c 49  _SHM_LOCK | SQLI
b3c0: 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56 45  TE_SHM_EXCLUSIVE
b3d0: 0a 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45  .** <li>  SQLITE
b3e0: 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51  _SHM_UNLOCK | SQ
b3f0: 4c 49 54 45 5f 53 48 4d 5f 53 48 41 52 45 44 0a  LITE_SHM_SHARED.
b400: 2a 2a 20 3c 6c 69 3e 20 20 53 51 4c 49 54 45 5f  ** <li>  SQLITE_
b410: 53 48 4d 5f 55 4e 4c 4f 43 4b 20 7c 20 53 51 4c  SHM_UNLOCK | SQL
b420: 49 54 45 5f 53 48 4d 5f 45 58 43 4c 55 53 49 56  ITE_SHM_EXCLUSIV
b430: 45 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  E.** </ul>.**.**
b440: 20 57 68 65 6e 20 75 6e 6c 6f 63 6b 69 6e 67 2c   When unlocking,
b450: 20 74 68 65 20 73 61 6d 65 20 53 48 41 52 45 44   the same SHARED
b460: 20 6f 72 20 45 58 43 4c 55 53 49 56 45 20 66 6c   or EXCLUSIVE fl
b470: 61 67 20 6d 75 73 74 20 62 65 20 73 75 70 70 6c  ag must be suppl
b480: 69 65 64 20 61 73 0a 2a 2a 20 77 61 73 20 67 69  ied as.** was gi
b490: 76 65 6e 20 6e 6f 20 74 68 65 20 63 6f 72 72 65  ven no the corre
b4a0: 73 70 6f 6e 64 69 6e 67 20 6c 6f 63 6b 2e 20 20  sponding lock.  
b4b0: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 53 68 6d 4c  .**.** The xShmL
b4c0: 6f 63 6b 20 6d 65 74 68 6f 64 20 63 61 6e 20 74  ock method can t
b4d0: 72 61 6e 73 69 74 69 6f 6e 20 62 65 74 77 65 65  ransition betwee
b4e0: 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64 20 53  n unlocked and S
b4f0: 48 41 52 45 44 20 6f 72 0a 2a 2a 20 62 65 74 77  HARED or.** betw
b500: 65 65 6e 20 75 6e 6c 6f 63 6b 65 64 20 61 6e 64  een unlocked and
b510: 20 45 58 43 4c 55 53 49 56 45 2e 20 20 49 74 20   EXCLUSIVE.  It 
b520: 63 61 6e 6e 6f 74 20 74 72 61 6e 73 69 74 69 6f  cannot transitio
b530: 6e 20 62 65 74 77 65 65 6e 20 53 48 41 52 45 44  n between SHARED
b540: 0a 2a 2a 20 61 6e 64 20 45 58 43 4c 55 53 49 56  .** and EXCLUSIV
b550: 45 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  E..*/.#define SQ
b560: 4c 49 54 45 5f 53 48 4d 5f 55 4e 4c 4f 43 4b 20  LITE_SHM_UNLOCK 
b570: 20 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20        1.#define 
b580: 53 51 4c 49 54 45 5f 53 48 4d 5f 4c 4f 43 4b 20  SQLITE_SHM_LOCK 
b590: 20 20 20 20 20 20 20 20 32 0a 23 64 65 66 69 6e          2.#defin
b5a0: 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 53 48 41  e SQLITE_SHM_SHA
b5b0: 52 45 44 20 20 20 20 20 20 20 34 0a 23 64 65 66  RED       4.#def
b5c0: 69 6e 65 20 53 51 4c 49 54 45 5f 53 48 4d 5f 45  ine SQLITE_SHM_E
b5d0: 58 43 4c 55 53 49 56 45 20 20 20 20 38 0a 0a 2f  XCLUSIVE    8../
b5e0: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d  *.** CAPI3REF: M
b5f0: 61 78 69 6d 75 6d 20 78 53 68 6d 4c 6f 63 6b 20  aximum xShmLock 
b600: 69 6e 64 65 78 0a 2a 2a 0a 2a 2a 20 54 68 65 20  index.**.** The 
b610: 78 53 68 6d 4c 6f 63 6b 20 6d 65 74 68 6f 64 20  xShmLock method 
b620: 6f 6e 20 5b 73 71 6c 69 74 65 33 5f 69 6f 5f 6d  on [sqlite3_io_m
b630: 65 74 68 6f 64 73 5d 20 6d 61 79 20 75 73 65 20  ethods] may use 
b640: 76 61 6c 75 65 73 0a 2a 2a 20 62 65 74 77 65 65  values.** betwee
b650: 6e 20 30 20 61 6e 64 20 74 68 69 73 20 75 70 70  n 0 and this upp
b660: 65 72 20 62 6f 75 6e 64 20 61 73 20 69 74 73 20  er bound as its 
b670: 22 6f 66 66 73 65 74 22 20 61 72 67 75 6d 65 6e  "offset" argumen
b680: 74 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74 65  t..** The SQLite
b690: 20 63 6f 72 65 20 77 69 6c 6c 20 6e 65 76 65 72   core will never
b6a0: 20 61 74 74 65 6d 70 74 20 74 6f 20 61 63 71 75   attempt to acqu
b6b0: 69 72 65 20 6f 72 20 72 65 6c 65 61 73 65 20 61  ire or release a
b6c0: 0a 2a 2a 20 6c 6f 63 6b 20 6f 75 74 73 69 64 65  .** lock outside
b6d0: 20 6f 66 20 74 68 69 73 20 72 61 6e 67 65 0a 2a   of this range.*
b6e0: 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
b6f0: 5f 53 48 4d 5f 4e 4c 4f 43 4b 20 20 20 20 20 20  _SHM_NLOCK      
b700: 20 20 38 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49    8.../*.** CAPI
b710: 33 52 45 46 3a 20 49 6e 69 74 69 61 6c 69 7a 65  3REF: Initialize
b720: 20 54 68 65 20 53 51 4c 69 74 65 20 4c 69 62 72   The SQLite Libr
b730: 61 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  ary.**.** ^The s
b740: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
b750: 65 28 29 20 72 6f 75 74 69 6e 65 20 69 6e 69 74  e() routine init
b760: 69 61 6c 69 7a 65 73 20 74 68 65 0a 2a 2a 20 53  ializes the.** S
b770: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
b780: 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 73 68 75  ^The sqlite3_shu
b790: 74 64 6f 77 6e 28 29 20 72 6f 75 74 69 6e 65 0a  tdown() routine.
b7a0: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 65 73 20 61  ** deallocates a
b7b0: 6e 79 20 72 65 73 6f 75 72 63 65 73 20 74 68 61  ny resources tha
b7c0: 74 20 77 65 72 65 20 61 6c 6c 6f 63 61 74 65 64  t were allocated
b7d0: 20 62 79 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   by sqlite3_init
b7e0: 69 61 6c 69 7a 65 28 29 2e 0a 2a 2a 20 54 68 65  ialize()..** The
b7f0: 73 65 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20  se routines are 
b800: 64 65 73 69 67 6e 65 64 20 74 6f 20 61 69 64 20  designed to aid 
b810: 69 6e 20 70 72 6f 63 65 73 73 20 69 6e 69 74 69  in process initi
b820: 61 6c 69 7a 61 74 69 6f 6e 20 61 6e 64 0a 2a 2a  alization and.**
b830: 20 73 68 75 74 64 6f 77 6e 20 6f 6e 20 65 6d 62   shutdown on emb
b840: 65 64 64 65 64 20 73 79 73 74 65 6d 73 2e 20 20  edded systems.  
b850: 57 6f 72 6b 73 74 61 74 69 6f 6e 20 61 70 70 6c  Workstation appl
b860: 69 63 61 74 69 6f 6e 73 20 75 73 69 6e 67 0a 2a  ications using.*
b870: 2a 20 53 51 4c 69 74 65 20 6e 6f 72 6d 61 6c 6c  * SQLite normall
b880: 79 20 64 6f 20 6e 6f 74 20 6e 65 65 64 20 74 6f  y do not need to
b890: 20 69 6e 76 6f 6b 65 20 65 69 74 68 65 72 20 6f   invoke either o
b8a0: 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73  f these routines
b8b0: 2e 0a 2a 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74  ..**.** A call t
b8c0: 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61  o sqlite3_initia
b8d0: 6c 69 7a 65 28 29 20 69 73 20 61 6e 20 22 65 66  lize() is an "ef
b8e0: 66 65 63 74 69 76 65 22 20 63 61 6c 6c 20 69 66  fective" call if
b8f0: 20 69 74 20 69 73 0a 2a 2a 20 74 68 65 20 66 69   it is.** the fi
b900: 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74 65 33  rst time sqlite3
b910: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 69 73  _initialize() is
b920: 20 69 6e 76 6f 6b 65 64 20 64 75 72 69 6e 67 20   invoked during 
b930: 74 68 65 20 6c 69 66 65 74 69 6d 65 20 6f 66 0a  the lifetime of.
b940: 2a 2a 20 74 68 65 20 70 72 6f 63 65 73 73 2c 20  ** the process, 
b950: 6f 72 20 69 66 20 69 74 20 69 73 20 74 68 65 20  or if it is the 
b960: 66 69 72 73 74 20 74 69 6d 65 20 73 71 6c 69 74  first time sqlit
b970: 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20  e3_initialize() 
b980: 69 73 20 69 6e 76 6f 6b 65 64 0a 2a 2a 20 66 6f  is invoked.** fo
b990: 6c 6c 6f 77 69 6e 67 20 61 20 63 61 6c 6c 20 74  llowing a call t
b9a0: 6f 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  o sqlite3_shutdo
b9b0: 77 6e 28 29 2e 20 20 5e 28 4f 6e 6c 79 20 61 6e  wn().  ^(Only an
b9c0: 20 65 66 66 65 63 74 69 76 65 20 63 61 6c 6c 0a   effective call.
b9d0: 2a 2a 20 6f 66 20 73 71 6c 69 74 65 33 5f 69 6e  ** of sqlite3_in
b9e0: 69 74 69 61 6c 69 7a 65 28 29 20 64 6f 65 73 20  itialize() does 
b9f0: 61 6e 79 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  any initializati
ba00: 6f 6e 2e 20 20 41 6c 6c 20 6f 74 68 65 72 20 63  on.  All other c
ba10: 61 6c 6c 73 0a 2a 2a 20 61 72 65 20 68 61 72 6d  alls.** are harm
ba20: 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e 29 5e 0a 2a  less no-ops.)^.*
ba30: 2a 0a 2a 2a 20 41 20 63 61 6c 6c 20 74 6f 20 73  *.** A call to s
ba40: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
ba50: 29 20 69 73 20 61 6e 20 22 65 66 66 65 63 74 69  ) is an "effecti
ba60: 76 65 22 20 63 61 6c 6c 20 69 66 20 69 74 20 69  ve" call if it i
ba70: 73 20 74 68 65 20 66 69 72 73 74 0a 2a 2a 20 63  s the first.** c
ba80: 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
ba90: 68 75 74 64 6f 77 6e 28 29 20 73 69 6e 63 65 20  hutdown() since 
baa0: 74 68 65 20 6c 61 73 74 20 73 71 6c 69 74 65 33  the last sqlite3
bab0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 2e 20 20  _initialize().  
bac0: 5e 28 4f 6e 6c 79 0a 2a 2a 20 61 6e 20 65 66 66  ^(Only.** an eff
bad0: 65 63 74 69 76 65 20 63 61 6c 6c 20 74 6f 20 73  ective call to s
bae0: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
baf0: 29 20 64 6f 65 73 20 61 6e 79 20 64 65 69 6e 69  ) does any deini
bb00: 74 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a 20  tialization..** 
bb10: 41 6c 6c 20 6f 74 68 65 72 20 76 61 6c 69 64 20  All other valid 
bb20: 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33  calls to sqlite3
bb30: 5f 73 68 75 74 64 6f 77 6e 28 29 20 61 72 65 20  _shutdown() are 
bb40: 68 61 72 6d 6c 65 73 73 20 6e 6f 2d 6f 70 73 2e  harmless no-ops.
bb50: 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  )^.**.** The sql
bb60: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
bb70: 29 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 74  ) interface is t
bb80: 68 72 65 61 64 73 61 66 65 2c 20 62 75 74 20 73  hreadsafe, but s
bb90: 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28  qlite3_shutdown(
bba0: 29 0a 2a 2a 20 69 73 20 6e 6f 74 2e 20 20 54 68  ).** is not.  Th
bbb0: 65 20 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f  e sqlite3_shutdo
bbc0: 77 6e 28 29 20 69 6e 74 65 72 66 61 63 65 20 6d  wn() interface m
bbd0: 75 73 74 20 6f 6e 6c 79 20 62 65 20 63 61 6c 6c  ust only be call
bbe0: 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 73 69 6e  ed from a.** sin
bbf0: 67 6c 65 20 74 68 72 65 61 64 2e 20 20 41 6c 6c  gle thread.  All
bc00: 20 6f 70 65 6e 20 5b 64 61 74 61 62 61 73 65 20   open [database 
bc10: 63 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 6d 75 73  connections] mus
bc20: 74 20 62 65 20 63 6c 6f 73 65 64 20 61 6e 64 20  t be closed and 
bc30: 61 6c 6c 0a 2a 2a 20 6f 74 68 65 72 20 53 51 4c  all.** other SQL
bc40: 69 74 65 20 72 65 73 6f 75 72 63 65 73 20 6d 75  ite resources mu
bc50: 73 74 20 62 65 20 64 65 61 6c 6c 6f 63 61 74 65  st be deallocate
bc60: 64 20 70 72 69 6f 72 20 74 6f 20 69 6e 76 6f 6b  d prior to invok
bc70: 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 73  ing.** sqlite3_s
bc80: 68 75 74 64 6f 77 6e 28 29 2e 0a 2a 2a 0a 2a 2a  hutdown()..**.**
bc90: 20 41 6d 6f 6e 67 20 6f 74 68 65 72 20 74 68 69   Among other thi
bca0: 6e 67 73 2c 20 5e 73 71 6c 69 74 65 33 5f 69 6e  ngs, ^sqlite3_in
bcb0: 69 74 69 61 6c 69 7a 65 28 29 20 77 69 6c 6c 20  itialize() will 
bcc0: 69 6e 76 6f 6b 65 0a 2a 2a 20 73 71 6c 69 74 65  invoke.** sqlite
bcd0: 33 5f 6f 73 5f 69 6e 69 74 28 29 2e 20 20 53 69  3_os_init().  Si
bce0: 6d 69 6c 61 72 6c 79 2c 20 5e 73 71 6c 69 74 65  milarly, ^sqlite
bcf0: 33 5f 73 68 75 74 64 6f 77 6e 28 29 0a 2a 2a 20  3_shutdown().** 
bd00: 77 69 6c 6c 20 69 6e 76 6f 6b 65 20 73 71 6c 69  will invoke sqli
bd10: 74 65 33 5f 6f 73 5f 65 6e 64 28 29 2e 0a 2a 2a  te3_os_end()..**
bd20: 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
bd30: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 20 72 6f  _initialize() ro
bd40: 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 5b 53  utine returns [S
bd50: 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63  QLITE_OK] on suc
bd60: 63 65 73 73 2e 0a 2a 2a 20 5e 49 66 20 66 6f 72  cess..** ^If for
bd70: 20 73 6f 6d 65 20 72 65 61 73 6f 6e 2c 20 73 71   some reason, sq
bd80: 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65  lite3_initialize
bd90: 28 29 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  () is unable to 
bda0: 69 6e 69 74 69 61 6c 69 7a 65 0a 2a 2a 20 74 68  initialize.** th
bdb0: 65 20 6c 69 62 72 61 72 79 20 28 70 65 72 68 61  e library (perha
bdc0: 70 73 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20  ps it is unable 
bdd0: 74 6f 20 61 6c 6c 6f 63 61 74 65 20 61 20 6e 65  to allocate a ne
bde0: 65 64 65 64 20 72 65 73 6f 75 72 63 65 20 73 75  eded resource su
bdf0: 63 68 0a 2a 2a 20 61 73 20 61 20 6d 75 74 65 78  ch.** as a mutex
be00: 29 20 69 74 20 72 65 74 75 72 6e 73 20 61 6e 20  ) it returns an 
be10: 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 6f 74 68  [error code] oth
be20: 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
be30: 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  OK]..**.** ^The 
be40: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
be50: 7a 65 28 29 20 72 6f 75 74 69 6e 65 20 69 73 20  ze() routine is 
be60: 63 61 6c 6c 65 64 20 69 6e 74 65 72 6e 61 6c 6c  called internall
be70: 79 20 62 79 20 6d 61 6e 79 20 6f 74 68 65 72 0a  y by many other.
be80: 2a 2a 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ** SQLite interf
be90: 61 63 65 73 20 73 6f 20 74 68 61 74 20 61 6e 20  aces so that an 
bea0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73 75 61  application usua
beb0: 6c 6c 79 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  lly does not nee
bec0: 64 20 74 6f 0a 2a 2a 20 69 6e 76 6f 6b 65 20 73  d to.** invoke s
bed0: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
bee0: 65 28 29 20 64 69 72 65 63 74 6c 79 2e 20 20 46  e() directly.  F
bef0: 6f 72 20 65 78 61 6d 70 6c 65 2c 20 5b 73 71 6c  or example, [sql
bf00: 69 74 65 33 5f 6f 70 65 6e 28 29 5d 0a 2a 2a 20  ite3_open()].** 
bf10: 63 61 6c 6c 73 20 73 71 6c 69 74 65 33 5f 69 6e  calls sqlite3_in
bf20: 69 74 69 61 6c 69 7a 65 28 29 20 73 6f 20 74 68  itialize() so th
bf30: 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72 79  e SQLite library
bf40: 20 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74   will be automat
bf50: 69 63 61 6c 6c 79 0a 2a 2a 20 69 6e 69 74 69 61  ically.** initia
bf60: 6c 69 7a 65 64 20 77 68 65 6e 20 5b 73 71 6c 69  lized when [sqli
bf70: 74 65 33 5f 6f 70 65 6e 28 29 5d 20 69 73 20 63  te3_open()] is c
bf80: 61 6c 6c 65 64 20 69 66 20 69 74 20 68 61 73 20  alled if it has 
bf90: 6e 6f 74 20 62 65 20 69 6e 69 74 69 61 6c 69 7a  not be initializ
bfa0: 65 64 0a 2a 2a 20 61 6c 72 65 61 64 79 2e 20 20  ed.** already.  
bfb0: 5e 48 6f 77 65 76 65 72 2c 20 69 66 20 53 51 4c  ^However, if SQL
bfc0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
bfd0: 77 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45  with the [SQLITE
bfe0: 5f 4f 4d 49 54 5f 41 55 54 4f 49 4e 49 54 5d 0a  _OMIT_AUTOINIT].
bff0: 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  ** compile-time 
c000: 6f 70 74 69 6f 6e 2c 20 74 68 65 6e 20 74 68 65  option, then the
c010: 20 61 75 74 6f 6d 61 74 69 63 20 63 61 6c 6c 73   automatic calls
c020: 20 74 6f 20 73 71 6c 69 74 65 33 5f 69 6e 69 74   to sqlite3_init
c030: 69 61 6c 69 7a 65 28 29 0a 2a 2a 20 61 72 65 20  ialize().** are 
c040: 6f 6d 69 74 74 65 64 20 61 6e 64 20 74 68 65 20  omitted and the 
c050: 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74  application must
c060: 20 63 61 6c 6c 20 73 71 6c 69 74 65 33 5f 69 6e   call sqlite3_in
c070: 69 74 69 61 6c 69 7a 65 28 29 20 64 69 72 65 63  itialize() direc
c080: 74 6c 79 0a 2a 2a 20 70 72 69 6f 72 20 74 6f 20  tly.** prior to 
c090: 75 73 69 6e 67 20 61 6e 79 20 6f 74 68 65 72 20  using any other 
c0a0: 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61 63 65  SQLite interface
c0b0: 2e 20 20 46 6f 72 20 6d 61 78 69 6d 75 6d 20 70  .  For maximum p
c0c0: 6f 72 74 61 62 69 6c 69 74 79 2c 0a 2a 2a 20 69  ortability,.** i
c0d0: 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65 64  t is recommended
c0e0: 20 74 68 61 74 20 61 70 70 6c 69 63 61 74 69 6f   that applicatio
c0f0: 6e 73 20 61 6c 77 61 79 73 20 69 6e 76 6f 6b 65  ns always invoke
c100: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c110: 69 7a 65 28 29 0a 2a 2a 20 64 69 72 65 63 74 6c  ize().** directl
c120: 79 20 70 72 69 6f 72 20 74 6f 20 75 73 69 6e 67  y prior to using
c130: 20 61 6e 79 20 6f 74 68 65 72 20 53 51 4c 69 74   any other SQLit
c140: 65 20 69 6e 74 65 72 66 61 63 65 2e 20 20 46 75  e interface.  Fu
c150: 74 75 72 65 20 72 65 6c 65 61 73 65 73 0a 2a 2a  ture releases.**
c160: 20 6f 66 20 53 51 4c 69 74 65 20 6d 61 79 20 72   of SQLite may r
c170: 65 71 75 69 72 65 20 74 68 69 73 2e 20 20 49 6e  equire this.  In
c180: 20 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68   other words, th
c190: 65 20 62 65 68 61 76 69 6f 72 20 65 78 68 69 62  e behavior exhib
c1a0: 69 74 65 64 0a 2a 2a 20 77 68 65 6e 20 53 51 4c  ited.** when SQL
c1b0: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
c1c0: 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 4f 4d 49  with [SQLITE_OMI
c1d0: 54 5f 41 55 54 4f 49 4e 49 54 5d 20 6d 69 67 68  T_AUTOINIT] migh
c1e0: 74 20 62 65 63 6f 6d 65 20 74 68 65 0a 2a 2a 20  t become the.** 
c1f0: 64 65 66 61 75 6c 74 20 62 65 68 61 76 69 6f 72  default behavior
c200: 20 69 6e 20 73 6f 6d 65 20 66 75 74 75 72 65 20   in some future 
c210: 72 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74  release of SQLit
c220: 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71 6c  e..**.** The sql
c230: 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29 20 72  ite3_os_init() r
c240: 6f 75 74 69 6e 65 20 64 6f 65 73 20 6f 70 65 72  outine does oper
c250: 61 74 69 6e 67 2d 73 79 73 74 65 6d 20 73 70 65  ating-system spe
c260: 63 69 66 69 63 0a 2a 2a 20 69 6e 69 74 69 61 6c  cific.** initial
c270: 69 7a 61 74 69 6f 6e 20 6f 66 20 74 68 65 20 53  ization of the S
c280: 51 4c 69 74 65 20 6c 69 62 72 61 72 79 2e 20 20  QLite library.  
c290: 54 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 65  The sqlite3_os_e
c2a0: 6e 64 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20  nd().** routine 
c2b0: 75 6e 64 6f 65 73 20 74 68 65 20 65 66 66 65 63  undoes the effec
c2c0: 74 20 6f 66 20 73 71 6c 69 74 65 33 5f 6f 73 5f  t of sqlite3_os_
c2d0: 69 6e 69 74 28 29 2e 20 20 54 79 70 69 63 61 6c  init().  Typical
c2e0: 20 74 61 73 6b 73 0a 2a 2a 20 70 65 72 66 6f 72   tasks.** perfor
c2f0: 6d 65 64 20 62 79 20 74 68 65 73 65 20 72 6f 75  med by these rou
c300: 74 69 6e 65 73 20 69 6e 63 6c 75 64 65 20 61 6c  tines include al
c310: 6c 6f 63 61 74 69 6f 6e 20 6f 72 20 64 65 61 6c  location or deal
c320: 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66 20 73  location.** of s
c330: 74 61 74 69 63 20 72 65 73 6f 75 72 63 65 73 2c  tatic resources,
c340: 20 69 6e 69 74 69 61 6c 69 7a 61 74 69 6f 6e 20   initialization 
c350: 6f 66 20 67 6c 6f 62 61 6c 20 76 61 72 69 61 62  of global variab
c360: 6c 65 73 2c 0a 2a 2a 20 73 65 74 74 69 6e 67 20  les,.** setting 
c370: 75 70 20 61 20 64 65 66 61 75 6c 74 20 5b 73 71  up a default [sq
c380: 6c 69 74 65 33 5f 76 66 73 5d 20 6d 6f 64 75 6c  lite3_vfs] modul
c390: 65 2c 20 6f 72 20 73 65 74 74 69 6e 67 20 75 70  e, or setting up
c3a0: 0a 2a 2a 20 61 20 64 65 66 61 75 6c 74 20 63 6f  .** a default co
c3b0: 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 73 69 6e  nfiguration usin
c3c0: 67 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  g [sqlite3_confi
c3d0: 67 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  g()]..**.** The 
c3e0: 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75  application shou
c3f0: 6c 64 20 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20  ld never invoke 
c400: 65 69 74 68 65 72 20 73 71 6c 69 74 65 33 5f 6f  either sqlite3_o
c410: 73 5f 69 6e 69 74 28 29 0a 2a 2a 20 6f 72 20 73  s_init().** or s
c420: 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29 20  qlite3_os_end() 
c430: 64 69 72 65 63 74 6c 79 2e 20 20 54 68 65 20 61  directly.  The a
c440: 70 70 6c 69 63 61 74 69 6f 6e 20 73 68 6f 75 6c  pplication shoul
c450: 64 20 6f 6e 6c 79 20 69 6e 76 6f 6b 65 0a 2a 2a  d only invoke.**
c460: 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
c470: 69 7a 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ize() and sqlite
c480: 33 5f 73 68 75 74 64 6f 77 6e 28 29 2e 20 20 54  3_shutdown().  T
c490: 68 65 20 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e  he sqlite3_os_in
c4a0: 69 74 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  it().** interfac
c4b0: 65 20 69 73 20 63 61 6c 6c 65 64 20 61 75 74 6f  e is called auto
c4c0: 6d 61 74 69 63 61 6c 6c 79 20 62 79 20 73 71 6c  matically by sql
c4d0: 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28  ite3_initialize(
c4e0: 29 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33  ) and.** sqlite3
c4f0: 5f 6f 73 5f 65 6e 64 28 29 20 69 73 20 63 61 6c  _os_end() is cal
c500: 6c 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 73  led by sqlite3_s
c510: 68 75 74 64 6f 77 6e 28 29 2e 20 20 41 70 70 72  hutdown().  Appr
c520: 6f 70 72 69 61 74 65 0a 2a 2a 20 69 6d 70 6c 65  opriate.** imple
c530: 6d 65 6e 74 61 74 69 6f 6e 73 20 66 6f 72 20 73  mentations for s
c540: 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28 29  qlite3_os_init()
c550: 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 6f 73 5f   and sqlite3_os_
c560: 65 6e 64 28 29 0a 2a 2a 20 61 72 65 20 62 75 69  end().** are bui
c570: 6c 74 20 69 6e 74 6f 20 53 51 4c 69 74 65 20 77  lt into SQLite w
c580: 68 65 6e 20 69 74 20 69 73 20 63 6f 6d 70 69 6c  hen it is compil
c590: 65 64 20 66 6f 72 20 55 6e 69 78 2c 20 57 69 6e  ed for Unix, Win
c5a0: 64 6f 77 73 2c 20 6f 72 20 4f 53 2f 32 2e 0a 2a  dows, or OS/2..*
c5b0: 2a 20 57 68 65 6e 20 5b 63 75 73 74 6f 6d 20 62  * When [custom b
c5c0: 75 69 6c 64 73 20 7c 20 62 75 69 6c 74 20 66 6f  uilds | built fo
c5d0: 72 20 6f 74 68 65 72 20 70 6c 61 74 66 6f 72 6d  r other platform
c5e0: 73 5d 0a 2a 2a 20 28 75 73 69 6e 67 20 74 68 65  s].** (using the
c5f0: 20 5b 53 51 4c 49 54 45 5f 4f 53 5f 4f 54 48 45   [SQLITE_OS_OTHE
c600: 52 3d 31 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d  R=1] compile-tim
c610: 65 0a 2a 2a 20 6f 70 74 69 6f 6e 29 20 74 68 65  e.** option) the
c620: 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 75 73   application mus
c630: 74 20 73 75 70 70 6c 79 20 61 20 73 75 69 74 61  t supply a suita
c640: 62 6c 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  ble implementati
c650: 6f 6e 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65  on for.** sqlite
c660: 33 5f 6f 73 5f 69 6e 69 74 28 29 20 61 6e 64 20  3_os_init() and 
c670: 73 71 6c 69 74 65 33 5f 6f 73 5f 65 6e 64 28 29  sqlite3_os_end()
c680: 2e 20 20 41 6e 20 61 70 70 6c 69 63 61 74 69 6f  .  An applicatio
c690: 6e 2d 73 75 70 70 6c 69 65 64 0a 2a 2a 20 69 6d  n-supplied.** im
c6a0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
c6b0: 73 71 6c 69 74 65 33 5f 6f 73 5f 69 6e 69 74 28  sqlite3_os_init(
c6c0: 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 6f 73 5f  ) or sqlite3_os_
c6d0: 65 6e 64 28 29 0a 2a 2a 20 6d 75 73 74 20 72 65  end().** must re
c6e0: 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
c6f0: 20 6f 6e 20 73 75 63 63 65 73 73 20 61 6e 64 20   on success and 
c700: 73 6f 6d 65 20 6f 74 68 65 72 20 5b 65 72 72 6f  some other [erro
c710: 72 20 63 6f 64 65 5d 20 75 70 6f 6e 0a 2a 2a 20  r code] upon.** 
c720: 66 61 69 6c 75 72 65 2e 0a 2a 2f 0a 69 6e 74 20  failure..*/.int 
c730: 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69  sqlite3_initiali
c740: 7a 65 28 76 6f 69 64 29 3b 0a 69 6e 74 20 73 71  ze(void);.int sq
c750: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 76  lite3_shutdown(v
c760: 6f 69 64 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  oid);.int sqlite
c770: 33 5f 6f 73 5f 69 6e 69 74 28 76 6f 69 64 29 3b  3_os_init(void);
c780: 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 73 5f  .int sqlite3_os_
c790: 65 6e 64 28 76 6f 69 64 29 3b 0a 0a 2f 2a 0a 2a  end(void);../*.*
c7a0: 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 66  * CAPI3REF: Conf
c7b0: 69 67 75 72 69 6e 67 20 54 68 65 20 53 51 4c 69  iguring The SQLi
c7c0: 74 65 20 4c 69 62 72 61 72 79 0a 2a 2a 0a 2a 2a  te Library.**.**
c7d0: 20 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e   The sqlite3_con
c7e0: 66 69 67 28 29 20 69 6e 74 65 72 66 61 63 65 20  fig() interface 
c7f0: 69 73 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20  is used to make 
c800: 67 6c 6f 62 61 6c 20 63 6f 6e 66 69 67 75 72 61  global configura
c810: 74 69 6f 6e 0a 2a 2a 20 63 68 61 6e 67 65 73 20  tion.** changes 
c820: 74 6f 20 53 51 4c 69 74 65 20 69 6e 20 6f 72 64  to SQLite in ord
c830: 65 72 20 74 6f 20 74 75 6e 65 20 53 51 4c 69 74  er to tune SQLit
c840: 65 20 74 6f 20 74 68 65 20 73 70 65 63 69 66 69  e to the specifi
c850: 63 20 6e 65 65 64 73 20 6f 66 0a 2a 2a 20 74 68  c needs of.** th
c860: 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2e 20 20  e application.  
c870: 54 68 65 20 64 65 66 61 75 6c 74 20 63 6f 6e 66  The default conf
c880: 69 67 75 72 61 74 69 6f 6e 20 69 73 20 72 65 63  iguration is rec
c890: 6f 6d 6d 65 6e 64 65 64 20 66 6f 72 20 6d 6f 73  ommended for mos
c8a0: 74 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  t.** application
c8b0: 73 20 61 6e 64 20 73 6f 20 74 68 69 73 20 72 6f  s and so this ro
c8c0: 75 74 69 6e 65 20 69 73 20 75 73 75 61 6c 6c 79  utine is usually
c8d0: 20 6e 6f 74 20 6e 65 63 65 73 73 61 72 79 2e 20   not necessary. 
c8e0: 20 49 74 20 69 73 0a 2a 2a 20 70 72 6f 76 69 64   It is.** provid
c8f0: 65 64 20 74 6f 20 73 75 70 70 6f 72 74 20 72 61  ed to support ra
c900: 72 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  re applications 
c910: 77 69 74 68 20 75 6e 75 73 75 61 6c 20 6e 65 65  with unusual nee
c920: 64 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 73 71  ds..**.** The sq
c930: 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 69  lite3_config() i
c940: 6e 74 65 72 66 61 63 65 20 69 73 20 6e 6f 74 20  nterface is not 
c950: 74 68 72 65 61 64 73 61 66 65 2e 20 20 54 68 65  threadsafe.  The
c960: 20 61 70 70 6c 69 63 61 74 69 6f 6e 0a 2a 2a 20   application.** 
c970: 6d 75 73 74 20 69 6e 73 75 72 65 20 74 68 61 74  must insure that
c980: 20 6e 6f 20 6f 74 68 65 72 20 53 51 4c 69 74 65   no other SQLite
c990: 20 69 6e 74 65 72 66 61 63 65 73 20 61 72 65 20   interfaces are 
c9a0: 69 6e 76 6f 6b 65 64 20 62 79 20 6f 74 68 65 72  invoked by other
c9b0: 0a 2a 2a 20 74 68 72 65 61 64 73 20 77 68 69 6c  .** threads whil
c9c0: 65 20 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67  e sqlite3_config
c9d0: 28 29 20 69 73 20 72 75 6e 6e 69 6e 67 2e 20 20  () is running.  
c9e0: 46 75 72 74 68 65 72 6d 6f 72 65 2c 20 73 71 6c  Furthermore, sql
c9f0: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 0a 2a 2a  ite3_config().**
ca00: 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 69 6e 76   may only be inv
ca10: 6f 6b 65 64 20 70 72 69 6f 72 20 74 6f 20 6c 69  oked prior to li
ca20: 62 72 61 72 79 20 69 6e 69 74 69 61 6c 69 7a 61  brary initializa
ca30: 74 69 6f 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  tion using.** [s
ca40: 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c 69 7a  qlite3_initializ
ca50: 65 28 29 5d 20 6f 72 20 61 66 74 65 72 20 73 68  e()] or after sh
ca60: 75 74 64 6f 77 6e 20 62 79 20 5b 73 71 6c 69 74  utdown by [sqlit
ca70: 65 33 5f 73 68 75 74 64 6f 77 6e 28 29 5d 2e 0a  e3_shutdown()]..
ca80: 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 63  ** ^If sqlite3_c
ca90: 6f 6e 66 69 67 28 29 20 69 73 20 63 61 6c 6c 65  onfig() is calle
caa0: 64 20 61 66 74 65 72 20 5b 73 71 6c 69 74 65 33  d after [sqlite3
cab0: 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d 20 61  _initialize()] a
cac0: 6e 64 20 62 65 66 6f 72 65 0a 2a 2a 20 5b 73 71  nd before.** [sq
cad0: 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e 28 29  lite3_shutdown()
cae0: 5d 20 74 68 65 6e 20 69 74 20 77 69 6c 6c 20 72  ] then it will r
caf0: 65 74 75 72 6e 20 53 51 4c 49 54 45 5f 4d 49 53  eturn SQLITE_MIS
cb00: 55 53 45 2e 0a 2a 2a 20 4e 6f 74 65 2c 20 68 6f  USE..** Note, ho
cb10: 77 65 76 65 72 2c 20 74 68 61 74 20 5e 73 71 6c  wever, that ^sql
cb20: 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 20 63 61  ite3_config() ca
cb30: 6e 20 62 65 20 63 61 6c 6c 65 64 20 61 73 20 70  n be called as p
cb40: 61 72 74 20 6f 66 20 74 68 65 0a 2a 2a 20 69 6d  art of the.** im
cb50: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f 66 20  plementation of 
cb60: 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64  an application-d
cb70: 65 66 69 6e 65 64 20 5b 73 71 6c 69 74 65 33 5f  efined [sqlite3_
cb80: 6f 73 5f 69 6e 69 74 28 29 5d 2e 0a 2a 2a 0a 2a  os_init()]..**.*
cb90: 2a 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75  * The first argu
cba0: 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
cbb0: 63 6f 6e 66 69 67 28 29 20 69 73 20 61 6e 20 69  config() is an i
cbc0: 6e 74 65 67 65 72 0a 2a 2a 20 5b 53 51 4c 49 54  nteger.** [SQLIT
cbd0: 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
cbe0: 48 52 45 41 44 20 7c 20 63 6f 6e 66 69 67 75 72  HREAD | configur
cbf0: 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d 20 74 68  ation option] th
cc00: 61 74 20 64 65 74 65 72 6d 69 6e 65 73 0a 2a 2a  at determines.**
cc10: 20 77 68 61 74 20 70 72 6f 70 65 72 74 79 20 6f   what property o
cc20: 66 20 53 51 4c 69 74 65 20 69 73 20 74 6f 20 62  f SQLite is to b
cc30: 65 20 63 6f 6e 66 69 67 75 72 65 64 2e 20 20 53  e configured.  S
cc40: 75 62 73 65 71 75 65 6e 74 20 61 72 67 75 6d 65  ubsequent argume
cc50: 6e 74 73 0a 2a 2a 20 76 61 72 79 20 64 65 70 65  nts.** vary depe
cc60: 6e 64 69 6e 67 20 6f 6e 20 74 68 65 20 5b 53 51  nding on the [SQ
cc70: 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47  LITE_CONFIG_SING
cc80: 4c 45 54 48 52 45 41 44 20 7c 20 63 6f 6e 66 69  LETHREAD | confi
cc90: 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 5d  guration option]
cca0: 0a 2a 2a 20 69 6e 20 74 68 65 20 66 69 72 73 74  .** in the first
ccb0: 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a   argument..**.**
ccc0: 20 5e 57 68 65 6e 20 61 20 63 6f 6e 66 69 67 75   ^When a configu
ccd0: 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 69 73  ration option is
cce0: 20 73 65 74 2c 20 73 71 6c 69 74 65 33 5f 63 6f   set, sqlite3_co
ccf0: 6e 66 69 67 28 29 20 72 65 74 75 72 6e 73 20 5b  nfig() returns [
cd00: 53 51 4c 49 54 45 5f 4f 4b 5d 2e 0a 2a 2a 20 5e  SQLITE_OK]..** ^
cd10: 49 66 20 74 68 65 20 6f 70 74 69 6f 6e 20 69 73  If the option is
cd20: 20 75 6e 6b 6e 6f 77 6e 20 6f 72 20 53 51 4c 69   unknown or SQLi
cd30: 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f 20  te is unable to 
cd40: 73 65 74 20 74 68 65 20 6f 70 74 69 6f 6e 0a 2a  set the option.*
cd50: 2a 20 74 68 65 6e 20 74 68 69 73 20 72 6f 75 74  * then this rout
cd60: 69 6e 65 20 72 65 74 75 72 6e 73 20 61 20 6e 6f  ine returns a no
cd70: 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63 6f  n-zero [error co
cd80: 64 65 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  de]..*/.int sqli
cd90: 74 65 33 5f 63 6f 6e 66 69 67 28 69 6e 74 2c 20  te3_config(int, 
cda0: 2e 2e 2e 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ...);../*.** CAP
cdb0: 49 33 52 45 46 3a 20 43 6f 6e 66 69 67 75 72 65  I3REF: Configure
cdc0: 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
cdd0: 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 20  tions.**.** The 
cde0: 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69  sqlite3_db_confi
cdf0: 67 28 29 20 69 6e 74 65 72 66 61 63 65 20 69 73  g() interface is
ce00: 20 75 73 65 64 20 74 6f 20 6d 61 6b 65 20 63 6f   used to make co
ce10: 6e 66 69 67 75 72 61 74 69 6f 6e 0a 2a 2a 20 63  nfiguration.** c
ce20: 68 61 6e 67 65 73 20 74 6f 20 61 20 5b 64 61 74  hanges to a [dat
ce30: 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
ce40: 5d 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  ].  The interfac
ce50: 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 0a  e is similar to.
ce60: 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  ** [sqlite3_conf
ce70: 69 67 28 29 5d 20 65 78 63 65 70 74 20 74 68 61  ig()] except tha
ce80: 74 20 74 68 65 20 63 68 61 6e 67 65 73 20 61 70  t the changes ap
ce90: 70 6c 79 20 74 6f 20 61 20 73 69 6e 67 6c 65 0a  ply to a single.
cea0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
ceb0: 6e 65 63 74 69 6f 6e 5d 20 28 73 70 65 63 69 66  nection] (specif
cec0: 69 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74  ied in the first
ced0: 20 61 72 67 75 6d 65 6e 74 29 2e 0a 2a 2a 0a 2a   argument)..**.*
cee0: 2a 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67  * The second arg
cef0: 75 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33  ument to sqlite3
cf00: 5f 64 62 5f 63 6f 6e 66 69 67 28 44 2c 56 2c 2e  _db_config(D,V,.
cf10: 2e 2e 29 20 20 69 73 20 74 68 65 0a 2a 2a 20 5b  ..)  is the.** [
cf20: 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f  SQLITE_DBCONFIG_
cf30: 4c 4f 4f 4b 41 53 49 44 45 20 7c 20 63 6f 6e 66  LOOKASIDE | conf
cf40: 69 67 75 72 61 74 69 6f 6e 20 76 65 72 62 5d 20  iguration verb] 
cf50: 2d 20 61 6e 20 69 6e 74 65 67 65 72 20 63 6f 64  - an integer cod
cf60: 65 20 0a 2a 2a 20 74 68 61 74 20 69 6e 64 69 63  e .** that indic
cf70: 61 74 65 73 20 77 68 61 74 20 61 73 70 65 63 74  ates what aspect
cf80: 20 6f 66 20 74 68 65 20 5b 64 61 74 61 62 61 73   of the [databas
cf90: 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 73  e connection] is
cfa0: 20 62 65 69 6e 67 20 63 6f 6e 66 69 67 75 72 65   being configure
cfb0: 64 2e 0a 2a 2a 20 53 75 62 73 65 71 75 65 6e 74  d..** Subsequent
cfc0: 20 61 72 67 75 6d 65 6e 74 73 20 76 61 72 79 20   arguments vary 
cfd0: 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 74 68 65  depending on the
cfe0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 76   configuration v
cff0: 65 72 62 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c  erb..**.** ^Call
d000: 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 64 62 5f  s to sqlite3_db_
d010: 63 6f 6e 66 69 67 28 29 20 72 65 74 75 72 6e 20  config() return 
d020: 53 51 4c 49 54 45 5f 4f 4b 20 69 66 20 61 6e 64  SQLITE_OK if and
d030: 20 6f 6e 6c 79 20 69 66 0a 2a 2a 20 74 68 65 20   only if.** the 
d040: 63 61 6c 6c 20 69 73 20 63 6f 6e 73 69 64 65 72  call is consider
d050: 65 64 20 73 75 63 63 65 73 73 66 75 6c 2e 0a 2a  ed successful..*
d060: 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 64 62  /.int sqlite3_db
d070: 5f 63 6f 6e 66 69 67 28 73 71 6c 69 74 65 33 2a  _config(sqlite3*
d080: 2c 20 69 6e 74 20 6f 70 2c 20 2e 2e 2e 29 3b 0a  , int op, ...);.
d090: 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
d0a0: 20 4d 65 6d 6f 72 79 20 41 6c 6c 6f 63 61 74 69   Memory Allocati
d0b0: 6f 6e 20 52 6f 75 74 69 6e 65 73 0a 2a 2a 0a 2a  on Routines.**.*
d0c0: 2a 20 41 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  * An instance of
d0d0: 20 74 68 69 73 20 6f 62 6a 65 63 74 20 64 65 66   this object def
d0e0: 69 6e 65 73 20 74 68 65 20 69 6e 74 65 72 66 61  ines the interfa
d0f0: 63 65 20 62 65 74 77 65 65 6e 20 53 51 4c 69 74  ce between SQLit
d100: 65 0a 2a 2a 20 61 6e 64 20 6c 6f 77 2d 6c 65 76  e.** and low-lev
d110: 65 6c 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  el memory alloca
d120: 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 2e 0a 2a  tion routines..*
d130: 2a 0a 2a 2a 20 54 68 69 73 20 6f 62 6a 65 63 74  *.** This object
d140: 20 69 73 20 75 73 65 64 20 69 6e 20 6f 6e 6c 79   is used in only
d150: 20 6f 6e 65 20 70 6c 61 63 65 20 69 6e 20 74 68   one place in th
d160: 65 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66 61  e SQLite interfa
d170: 63 65 2e 0a 2a 2a 20 41 20 70 6f 69 6e 74 65 72  ce..** A pointer
d180: 20 74 6f 20 61 6e 20 69 6e 73 74 61 6e 63 65 20   to an instance 
d190: 6f 66 20 74 68 69 73 20 6f 62 6a 65 63 74 20 69  of this object i
d1a0: 73 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 74  s the argument t
d1b0: 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
d1c0: 6e 66 69 67 28 29 5d 20 77 68 65 6e 20 74 68 65  nfig()] when the
d1d0: 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f   configuration o
d1e0: 70 74 69 6f 6e 20 69 73 0a 2a 2a 20 5b 53 51 4c  ption is.** [SQL
d1f0: 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f  ITE_CONFIG_MALLO
d200: 43 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f 43 4f  C] or [SQLITE_CO
d210: 4e 46 49 47 5f 47 45 54 4d 41 4c 4c 4f 43 5d 2e  NFIG_GETMALLOC].
d220: 20 20 0a 2a 2a 20 42 79 20 63 72 65 61 74 69 6e    .** By creatin
d230: 67 20 61 6e 20 69 6e 73 74 61 6e 63 65 20 6f 66  g an instance of
d240: 20 74 68 69 73 20 6f 62 6a 65 63 74 0a 2a 2a 20   this object.** 
d250: 61 6e 64 20 70 61 73 73 69 6e 67 20 69 74 20 74  and passing it t
d260: 6f 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  o [sqlite3_confi
d270: 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49  g]([SQLITE_CONFI
d280: 47 5f 4d 41 4c 4c 4f 43 5d 29 0a 2a 2a 20 64 75  G_MALLOC]).** du
d290: 72 69 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69  ring configurati
d2a0: 6f 6e 2c 20 61 6e 20 61 70 70 6c 69 63 61 74 69  on, an applicati
d2b0: 6f 6e 20 63 61 6e 20 73 70 65 63 69 66 79 20 61  on can specify a
d2c0: 6e 20 61 6c 74 65 72 6e 61 74 69 76 65 0a 2a 2a  n alternative.**
d2d0: 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69   memory allocati
d2e0: 6f 6e 20 73 75 62 73 79 73 74 65 6d 20 66 6f 72  on subsystem for
d2f0: 20 53 51 4c 69 74 65 20 74 6f 20 75 73 65 20 66   SQLite to use f
d300: 6f 72 20 61 6c 6c 20 6f 66 20 69 74 73 0a 2a 2a  or all of its.**
d310: 20 64 79 6e 61 6d 69 63 20 6d 65 6d 6f 72 79 20   dynamic memory 
d320: 6e 65 65 64 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  needs..**.** Not
d330: 65 20 74 68 61 74 20 53 51 4c 69 74 65 20 63 6f  e that SQLite co
d340: 6d 65 73 20 77 69 74 68 20 73 65 76 65 72 61 6c  mes with several
d350: 20 5b 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72   [built-in memor
d360: 79 20 61 6c 6c 6f 63 61 74 6f 72 73 5d 0a 2a 2a  y allocators].**
d370: 20 74 68 61 74 20 61 72 65 20 70 65 72 66 65 63   that are perfec
d380: 74 6c 79 20 61 64 65 71 75 61 74 65 20 66 6f 72  tly adequate for
d390: 20 74 68 65 20 6f 76 65 72 77 68 65 6c 6d 69 6e   the overwhelmin
d3a0: 67 20 6d 61 6a 6f 72 69 74 79 20 6f 66 20 61 70  g majority of ap
d3b0: 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a 20 61 6e  plications.** an
d3c0: 64 20 74 68 61 74 20 74 68 69 73 20 6f 62 6a 65  d that this obje
d3d0: 63 74 20 69 73 20 6f 6e 6c 79 20 75 73 65 66 75  ct is only usefu
d3e0: 6c 20 74 6f 20 61 20 74 69 6e 79 20 6d 69 6e 6f  l to a tiny mino
d3f0: 72 69 74 79 20 6f 66 20 61 70 70 6c 69 63 61 74  rity of applicat
d400: 69 6f 6e 73 0a 2a 2a 20 77 69 74 68 20 73 70 65  ions.** with spe
d410: 63 69 61 6c 69 7a 65 64 20 6d 65 6d 6f 72 79 20  cialized memory 
d420: 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71 75 69  allocation requi
d430: 72 65 6d 65 6e 74 73 2e 20 20 54 68 69 73 20 6f  rements.  This o
d440: 62 6a 65 63 74 20 69 73 0a 2a 2a 20 61 6c 73 6f  bject is.** also
d450: 20 75 73 65 64 20 64 75 72 69 6e 67 20 74 65 73   used during tes
d460: 74 69 6e 67 20 6f 66 20 53 51 4c 69 74 65 20 69  ting of SQLite i
d470: 6e 20 6f 72 64 65 72 20 74 6f 20 73 70 65 63 69  n order to speci
d480: 66 79 20 61 6e 20 61 6c 74 65 72 6e 61 74 69 76  fy an alternativ
d490: 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  e.** memory allo
d4a0: 63 61 74 6f 72 20 74 68 61 74 20 73 69 6d 75 6c  cator that simul
d4b0: 61 74 65 73 20 6d 65 6d 6f 72 79 20 6f 75 74 2d  ates memory out-
d4c0: 6f 66 2d 6d 65 6d 6f 72 79 20 63 6f 6e 64 69 74  of-memory condit
d4d0: 69 6f 6e 73 20 69 6e 0a 2a 2a 20 6f 72 64 65 72  ions in.** order
d4e0: 20 74 6f 20 76 65 72 69 66 79 20 74 68 61 74 20   to verify that 
d4f0: 53 51 4c 69 74 65 20 72 65 63 6f 76 65 72 73 20  SQLite recovers 
d500: 67 72 61 63 65 66 75 6c 6c 79 20 66 72 6f 6d 20  gracefully from 
d510: 73 75 63 68 0a 2a 2a 20 63 6f 6e 64 69 74 69 6f  such.** conditio
d520: 6e 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 4d  ns..**.** The xM
d530: 61 6c 6c 6f 63 20 61 6e 64 20 78 46 72 65 65 20  alloc and xFree 
d540: 6d 65 74 68 6f 64 73 20 6d 75 73 74 20 77 6f 72  methods must wor
d550: 6b 20 6c 69 6b 65 20 74 68 65 0a 2a 2a 20 6d 61  k like the.** ma
d560: 6c 6c 6f 63 28 29 20 61 6e 64 20 66 72 65 65 28  lloc() and free(
d570: 29 20 66 75 6e 63 74 69 6f 6e 73 20 66 72 6f 6d  ) functions from
d580: 20 74 68 65 20 73 74 61 6e 64 61 72 64 20 43 20   the standard C 
d590: 6c 69 62 72 61 72 79 2e 0a 2a 2a 20 54 68 65 20  library..** The 
d5a0: 78 52 65 61 6c 6c 6f 63 20 6d 65 74 68 6f 64 20  xRealloc method 
d5b0: 6d 75 73 74 20 77 6f 72 6b 20 6c 69 6b 65 20 72  must work like r
d5c0: 65 61 6c 6c 6f 63 28 29 20 66 72 6f 6d 20 74 68  ealloc() from th
d5d0: 65 20 73 74 61 6e 64 61 72 64 20 43 20 6c 69 62  e standard C lib
d5e0: 72 61 72 79 0a 2a 2a 20 77 69 74 68 20 74 68 65  rary.** with the
d5f0: 20 65 78 63 65 70 74 69 6f 6e 20 74 68 61 74 20   exception that 
d600: 69 66 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72  if the second ar
d610: 67 75 6d 65 6e 74 20 74 6f 20 78 52 65 61 6c 6c  gument to xReall
d620: 6f 63 20 69 73 20 7a 65 72 6f 2c 0a 2a 2a 20 78  oc is zero,.** x
d630: 52 65 61 6c 6c 6f 63 20 6d 75 73 74 20 62 65 20  Realloc must be 
d640: 61 20 6e 6f 2d 6f 70 20 2d 20 69 74 20 6d 75 73  a no-op - it mus
d650: 74 20 6e 6f 74 20 70 65 72 66 6f 72 6d 20 61 6e  t not perform an
d660: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 6f 72 0a  y allocation or.
d670: 2a 2a 20 64 65 61 6c 6c 6f 63 61 74 69 6f 6e 2e  ** deallocation.
d680: 20 20 5e 53 51 4c 69 74 65 20 67 75 61 72 61 6e    ^SQLite guaran
d690: 74 65 65 73 20 74 68 61 74 20 74 68 65 20 73 65  tees that the se
d6a0: 63 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f  cond argument to
d6b0: 0a 2a 2a 20 78 52 65 61 6c 6c 6f 63 20 69 73 20  .** xRealloc is 
d6c0: 61 6c 77 61 79 73 20 61 20 76 61 6c 75 65 20 72  always a value r
d6d0: 65 74 75 72 6e 65 64 20 62 79 20 61 20 70 72 69  eturned by a pri
d6e0: 6f 72 20 63 61 6c 6c 20 74 6f 20 78 52 6f 75 6e  or call to xRoun
d6f0: 64 75 70 2e 0a 2a 2a 20 41 6e 64 20 73 6f 20 69  dup..** And so i
d700: 6e 20 63 61 73 65 73 20 77 68 65 72 65 20 78 52  n cases where xR
d710: 6f 75 6e 64 75 70 20 61 6c 77 61 79 73 20 72 65  oundup always re
d720: 74 75 72 6e 73 20 61 20 70 6f 73 69 74 69 76 65  turns a positive
d730: 20 6e 75 6d 62 65 72 2c 0a 2a 2a 20 78 52 65 61   number,.** xRea
d740: 6c 6c 6f 63 20 63 61 6e 20 70 65 72 66 6f 72 6d  lloc can perform
d750: 20 65 78 61 63 74 6c 79 20 61 73 20 74 68 65 20   exactly as the 
d760: 73 74 61 6e 64 61 72 64 20 6c 69 62 72 61 72 79  standard library
d770: 20 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64 0a 2a   realloc() and.*
d780: 2a 20 73 74 69 6c 6c 20 62 65 20 69 6e 20 63 6f  * still be in co
d790: 6d 70 6c 69 61 6e 63 65 20 77 69 74 68 20 74 68  mpliance with th
d7a0: 69 73 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e  is specification
d7b0: 2e 0a 2a 2a 0a 2a 2a 20 78 53 69 7a 65 20 73 68  ..**.** xSize sh
d7c0: 6f 75 6c 64 20 72 65 74 75 72 6e 20 74 68 65 20  ould return the 
d7d0: 61 6c 6c 6f 63 61 74 65 64 20 73 69 7a 65 20 6f  allocated size o
d7e0: 66 20 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  f a memory alloc
d7f0: 61 74 69 6f 6e 0a 2a 2a 20 70 72 65 76 69 6f 75  ation.** previou
d800: 73 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  sly obtained fro
d810: 6d 20 78 4d 61 6c 6c 6f 63 20 6f 72 20 78 52 65  m xMalloc or xRe
d820: 61 6c 6c 6f 63 2e 20 20 54 68 65 20 61 6c 6c 6f  alloc.  The allo
d830: 63 61 74 65 64 20 73 69 7a 65 0a 2a 2a 20 69 73  cated size.** is
d840: 20 61 6c 77 61 79 73 20 61 74 20 6c 65 61 73 74   always at least
d850: 20 61 73 20 62 69 67 20 61 73 20 74 68 65 20 72   as big as the r
d860: 65 71 75 65 73 74 65 64 20 73 69 7a 65 20 62 75  equested size bu
d870: 74 20 6d 61 79 20 62 65 20 6c 61 72 67 65 72 2e  t may be larger.
d880: 0a 2a 2a 0a 2a 2a 20 54 68 65 20 78 52 6f 75 6e  .**.** The xRoun
d890: 64 75 70 20 6d 65 74 68 6f 64 20 72 65 74 75 72  dup method retur
d8a0: 6e 73 20 77 68 61 74 20 77 6f 75 6c 64 20 62 65  ns what would be
d8b0: 20 74 68 65 20 61 6c 6c 6f 63 61 74 65 64 20 73   the allocated s
d8c0: 69 7a 65 20 6f 66 0a 2a 2a 20 61 20 6d 65 6d 6f  ize of.** a memo
d8d0: 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 67 69  ry allocation gi
d8e0: 76 65 6e 20 61 20 70 61 72 74 69 63 75 6c 61 72  ven a particular
d8f0: 20 72 65 71 75 65 73 74 65 64 20 73 69 7a 65 2e   requested size.
d900: 20 20 4d 6f 73 74 20 6d 65 6d 6f 72 79 0a 2a 2a    Most memory.**
d910: 20 61 6c 6c 6f 63 61 74 6f 72 73 20 72 6f 75 6e   allocators roun
d920: 64 20 75 70 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f  d up memory allo
d930: 63 61 74 69 6f 6e 73 20 61 74 20 6c 65 61 73 74  cations at least
d940: 20 74 6f 20 74 68 65 20 6e 65 78 74 20 6d 75 6c   to the next mul
d950: 74 69 70 6c 65 0a 2a 2a 20 6f 66 20 38 2e 20 20  tiple.** of 8.  
d960: 53 6f 6d 65 20 61 6c 6c 6f 63 61 74 6f 72 73 20  Some allocators 
d970: 72 6f 75 6e 64 20 75 70 20 74 6f 20 61 20 6c 61  round up to a la
d980: 72 67 65 72 20 6d 75 6c 74 69 70 6c 65 20 6f 72  rger multiple or
d990: 20 74 6f 20 61 20 70 6f 77 65 72 20 6f 66 20 32   to a power of 2
d9a0: 2e 0a 2a 2a 20 45 76 65 72 79 20 6d 65 6d 6f 72  ..** Every memor
d9b0: 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 72 65 71  y allocation req
d9c0: 75 65 73 74 20 63 6f 6d 69 6e 67 20 69 6e 20 74  uest coming in t
d9d0: 68 72 6f 75 67 68 20 5b 73 71 6c 69 74 65 33 5f  hrough [sqlite3_
d9e0: 6d 61 6c 6c 6f 63 28 29 5d 0a 2a 2a 20 6f 72 20  malloc()].** or 
d9f0: 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63  [sqlite3_realloc
da00: 28 29 5d 20 66 69 72 73 74 20 63 61 6c 6c 73 20  ()] first calls 
da10: 78 52 6f 75 6e 64 75 70 2e 20 20 49 66 20 78 52  xRoundup.  If xR
da20: 6f 75 6e 64 75 70 20 72 65 74 75 72 6e 73 20 30  oundup returns 0
da30: 2c 20 0a 2a 2a 20 74 68 61 74 20 63 61 75 73 65  , .** that cause
da40: 73 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64  s the correspond
da50: 69 6e 67 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  ing memory alloc
da60: 61 74 69 6f 6e 20 74 6f 20 66 61 69 6c 2e 0a 2a  ation to fail..*
da70: 2a 0a 2a 2a 20 54 68 65 20 78 49 6e 69 74 20 6d  *.** The xInit m
da80: 65 74 68 6f 64 20 69 6e 69 74 69 61 6c 69 7a 65  ethod initialize
da90: 73 20 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c  s the memory all
daa0: 6f 63 61 74 6f 72 2e 20 20 28 46 6f 72 20 65 78  ocator.  (For ex
dab0: 61 6d 70 6c 65 2c 0a 2a 2a 20 69 74 20 6d 69 67  ample,.** it mig
dac0: 68 74 20 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20  ht allocate any 
dad0: 72 65 71 75 69 72 65 20 6d 75 74 65 78 65 73 20  require mutexes 
dae0: 6f 72 20 69 6e 69 74 69 61 6c 69 7a 65 20 69 6e  or initialize in
daf0: 74 65 72 6e 61 6c 20 64 61 74 61 0a 2a 2a 20 73  ternal data.** s
db00: 74 72 75 63 74 75 72 65 73 2e 20 20 54 68 65 20  tructures.  The 
db10: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
db20: 20 69 73 20 69 6e 76 6f 6b 65 64 20 28 69 6e 64   is invoked (ind
db30: 69 72 65 63 74 6c 79 29 20 62 79 0a 2a 2a 20 5b  irectly) by.** [
db40: 73 71 6c 69 74 65 33 5f 73 68 75 74 64 6f 77 6e  sqlite3_shutdown
db50: 28 29 5d 20 61 6e 64 20 73 68 6f 75 6c 64 20 64  ()] and should d
db60: 65 61 6c 6c 6f 63 61 74 65 20 61 6e 79 20 72 65  eallocate any re
db70: 73 6f 75 72 63 65 73 20 61 63 71 75 69 72 65 64  sources acquired
db80: 0a 2a 2a 20 62 79 20 78 49 6e 69 74 2e 20 20 54  .** by xInit.  T
db90: 68 65 20 70 41 70 70 44 61 74 61 20 70 6f 69 6e  he pAppData poin
dba0: 74 65 72 20 69 73 20 75 73 65 64 20 61 73 20 74  ter is used as t
dbb0: 68 65 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65  he only paramete
dbc0: 72 20 74 6f 0a 2a 2a 20 78 49 6e 69 74 20 61 6e  r to.** xInit an
dbd0: 64 20 78 53 68 75 74 64 6f 77 6e 2e 0a 2a 2a 0a  d xShutdown..**.
dbe0: 2a 2a 20 53 51 4c 69 74 65 20 68 6f 6c 64 73 20  ** SQLite holds 
dbf0: 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55 54 45  the [SQLITE_MUTE
dc00: 58 5f 53 54 41 54 49 43 5f 4d 41 53 54 45 52 5d  X_STATIC_MASTER]
dc10: 20 6d 75 74 65 78 20 77 68 65 6e 20 69 74 20 69   mutex when it i
dc20: 6e 76 6f 6b 65 73 0a 2a 2a 20 74 68 65 20 78 49  nvokes.** the xI
dc30: 6e 69 74 20 6d 65 74 68 6f 64 2c 20 73 6f 20 74  nit method, so t
dc40: 68 65 20 78 49 6e 69 74 20 6d 65 74 68 6f 64 20  he xInit method 
dc50: 6e 65 65 64 20 6e 6f 74 20 62 65 20 74 68 72 65  need not be thre
dc60: 61 64 73 61 66 65 2e 20 20 54 68 65 0a 2a 2a 20  adsafe.  The.** 
dc70: 78 53 68 75 74 64 6f 77 6e 20 6d 65 74 68 6f 64  xShutdown method
dc80: 20 69 73 20 6f 6e 6c 79 20 63 61 6c 6c 65 64 20   is only called 
dc90: 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 73 68  from [sqlite3_sh
dca0: 75 74 64 6f 77 6e 28 29 5d 20 73 6f 20 69 74 20  utdown()] so it 
dcb0: 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 6e 65 65 64  does.** not need
dcc0: 20 74 6f 20 62 65 20 74 68 72 65 61 64 73 61 66   to be threadsaf
dcd0: 65 20 65 69 74 68 65 72 2e 20 20 46 6f 72 20 61  e either.  For a
dce0: 6c 6c 20 6f 74 68 65 72 20 6d 65 74 68 6f 64 73  ll other methods
dcf0: 2c 20 53 51 4c 69 74 65 0a 2a 2a 20 68 6f 6c 64  , SQLite.** hold
dd00: 73 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 4d 55  s the [SQLITE_MU
dd10: 54 45 58 5f 53 54 41 54 49 43 5f 4d 45 4d 5d 20  TEX_STATIC_MEM] 
dd20: 6d 75 74 65 78 20 61 73 20 6c 6f 6e 67 20 61 73  mutex as long as
dd30: 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
dd40: 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53  CONFIG_MEMSTATUS
dd50: 5d 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  ] configuration 
dd60: 6f 70 74 69 6f 6e 20 69 73 20 74 75 72 6e 65 64  option is turned
dd70: 20 6f 6e 20 28 77 68 69 63 68 0a 2a 2a 20 69 74   on (which.** it
dd80: 20 69 73 20 62 79 20 64 65 66 61 75 6c 74 29 20   is by default) 
dd90: 61 6e 64 20 73 6f 20 74 68 65 20 6d 65 74 68 6f  and so the metho
dda0: 64 73 20 61 72 65 20 61 75 74 6f 6d 61 74 69 63  ds are automatic
ddb0: 61 6c 6c 79 20 73 65 72 69 61 6c 69 7a 65 64 2e  ally serialized.
ddc0: 0a 2a 2a 20 48 6f 77 65 76 65 72 2c 20 69 66 20  .** However, if 
ddd0: 5b 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d  [SQLITE_CONFIG_M
dde0: 45 4d 53 54 41 54 55 53 5d 20 69 73 20 64 69 73  EMSTATUS] is dis
ddf0: 61 62 6c 65 64 2c 20 74 68 65 6e 20 74 68 65 20  abled, then the 
de00: 6f 74 68 65 72 0a 2a 2a 20 6d 65 74 68 6f 64 73  other.** methods
de10: 20 6d 75 73 74 20 62 65 20 74 68 72 65 61 64 73   must be threads
de20: 61 66 65 20 6f 72 20 65 6c 73 65 20 6d 61 6b 65  afe or else make
de30: 20 74 68 65 69 72 20 6f 77 6e 20 61 72 72 61 6e   their own arran
de40: 67 65 6d 65 6e 74 73 20 66 6f 72 0a 2a 2a 20 73  gements for.** s
de50: 65 72 69 61 6c 69 7a 61 74 69 6f 6e 2e 0a 2a 2a  erialization..**
de60: 0a 2a 2a 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  .** SQLite will 
de70: 6e 65 76 65 72 20 69 6e 76 6f 6b 65 20 78 49 6e  never invoke xIn
de80: 69 74 28 29 20 6d 6f 72 65 20 74 68 61 6e 20 6f  it() more than o
de90: 6e 63 65 20 77 69 74 68 6f 75 74 20 61 6e 20 69  nce without an i
dea0: 6e 74 65 72 76 65 6e 69 6e 67 0a 2a 2a 20 63 61  ntervening.** ca
deb0: 6c 6c 20 74 6f 20 78 53 68 75 74 64 6f 77 6e 28  ll to xShutdown(
dec0: 29 2e 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  )..*/.typedef st
ded0: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
dee0: 5f 6d 65 74 68 6f 64 73 20 73 71 6c 69 74 65 33  _methods sqlite3
def0: 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 3b 0a 73 74  _mem_methods;.st
df00: 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d  ruct sqlite3_mem
df10: 5f 6d 65 74 68 6f 64 73 20 7b 0a 20 20 76 6f 69  _methods {.  voi
df20: 64 20 2a 28 2a 78 4d 61 6c 6c 6f 63 29 28 69 6e  d *(*xMalloc)(in
df30: 74 29 3b 20 20 20 20 20 20 20 20 20 2f 2a 20 4d  t);         /* M
df40: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
df50: 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 20 20 76   function */.  v
df60: 6f 69 64 20 28 2a 78 46 72 65 65 29 28 76 6f 69  oid (*xFree)(voi
df70: 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20 2f 2a  d*);          /*
df80: 20 46 72 65 65 20 61 20 70 72 69 6f 72 20 61 6c   Free a prior al
df90: 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a 20 20 76 6f  location */.  vo
dfa0: 69 64 20 2a 28 2a 78 52 65 61 6c 6c 6f 63 29 28  id *(*xRealloc)(
dfb0: 76 6f 69 64 2a 2c 69 6e 74 29 3b 20 20 2f 2a 20  void*,int);  /* 
dfc0: 52 65 73 69 7a 65 20 61 6e 20 61 6c 6c 6f 63 61  Resize an alloca
dfd0: 74 69 6f 6e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a  tion */.  int (*
dfe0: 78 53 69 7a 65 29 28 76 6f 69 64 2a 29 3b 20 20  xSize)(void*);  
dff0: 20 20 20 20 20 20 20 20 20 2f 2a 20 52 65 74 75           /* Retu
e000: 72 6e 20 74 68 65 20 73 69 7a 65 20 6f 66 20 61  rn the size of a
e010: 6e 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 2a 2f 0a  n allocation */.
e020: 20 20 69 6e 74 20 28 2a 78 52 6f 75 6e 64 75 70    int (*xRoundup
e030: 29 28 69 6e 74 29 3b 20 20 20 20 20 20 20 20 20  )(int);         
e040: 20 2f 2a 20 52 6f 75 6e 64 20 75 70 20 72 65 71   /* Round up req
e050: 75 65 73 74 20 73 69 7a 65 20 74 6f 20 61 6c 6c  uest size to all
e060: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 2a 2f 0a  ocation size */.
e070: 20 20 69 6e 74 20 28 2a 78 49 6e 69 74 29 28 76    int (*xInit)(v
e080: 6f 69 64 2a 29 3b 20 20 20 20 20 20 20 20 20 20  oid*);          
e090: 20 2f 2a 20 49 6e 69 74 69 61 6c 69 7a 65 20 74   /* Initialize t
e0a0: 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  he memory alloca
e0b0: 74 6f 72 20 2a 2f 0a 20 20 76 6f 69 64 20 28 2a  tor */.  void (*
e0c0: 78 53 68 75 74 64 6f 77 6e 29 28 76 6f 69 64 2a  xShutdown)(void*
e0d0: 29 3b 20 20 20 20 20 20 2f 2a 20 44 65 69 6e 69  );      /* Deini
e0e0: 74 69 61 6c 69 7a 65 20 74 68 65 20 6d 65 6d 6f  tialize the memo
e0f0: 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20 2a 2f 0a  ry allocator */.
e100: 20 20 76 6f 69 64 20 2a 70 41 70 70 44 61 74 61    void *pAppData
e110: 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  ;               
e120: 20 2f 2a 20 41 72 67 75 6d 65 6e 74 20 74 6f 20   /* Argument to 
e130: 78 49 6e 69 74 28 29 20 61 6e 64 20 78 53 68 75  xInit() and xShu
e140: 74 64 6f 77 6e 28 29 20 2a 2f 0a 7d 3b 0a 0a 2f  tdown() */.};../
e150: 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
e160: 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 4f 70 74  onfiguration Opt
e170: 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65  ions.**.** These
e180: 20 63 6f 6e 73 74 61 6e 74 73 20 61 72 65 20 74   constants are t
e190: 68 65 20 61 76 61 69 6c 61 62 6c 65 20 69 6e 74  he available int
e1a0: 65 67 65 72 20 63 6f 6e 66 69 67 75 72 61 74 69  eger configurati
e1b0: 6f 6e 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 0a  on options that.
e1c0: 2a 2a 20 63 61 6e 20 62 65 20 70 61 73 73 65 64  ** can be passed
e1d0: 20 61 73 20 74 68 65 20 66 69 72 73 74 20 61 72   as the first ar
e1e0: 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 5b 73  gument to the [s
e1f0: 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28 29 5d  qlite3_config()]
e200: 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a 2a 0a 2a   interface..**.*
e210: 2a 20 4e 65 77 20 63 6f 6e 66 69 67 75 72 61 74  * New configurat
e220: 69 6f 6e 20 6f 70 74 69 6f 6e 73 20 6d 61 79 20  ion options may 
e230: 62 65 20 61 64 64 65 64 20 69 6e 20 66 75 74 75  be added in futu
e240: 72 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53  re releases of S
e250: 51 4c 69 74 65 2e 0a 2a 2a 20 45 78 69 73 74 69  QLite..** Existi
e260: 6e 67 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ng configuration
e270: 20 6f 70 74 69 6f 6e 73 20 6d 69 67 68 74 20 62   options might b
e280: 65 20 64 69 73 63 6f 6e 74 69 6e 75 65 64 2e 20  e discontinued. 
e290: 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 0a 2a 2a   Applications.**
e2a0: 20 73 68 6f 75 6c 64 20 63 68 65 63 6b 20 74 68   should check th
e2b0: 65 20 72 65 74 75 72 6e 20 63 6f 64 65 20 66 72  e return code fr
e2c0: 6f 6d 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66  om [sqlite3_conf
e2d0: 69 67 28 29 5d 20 74 6f 20 6d 61 6b 65 20 73 75  ig()] to make su
e2e0: 72 65 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 63  re that.** the c
e2f0: 61 6c 6c 20 77 6f 72 6b 65 64 2e 20 20 54 68 65  all worked.  The
e300: 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
e310: 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
e320: 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
e330: 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
e340: 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
e350: 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
e360: 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
e370: 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
e380: 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
e390: 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
e3a0: 54 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45  TE_CONFIG_SINGLE
e3b0: 54 48 52 45 41 44 3c 2f 64 74 3e 0a 2a 2a 20 3c  THREAD</dt>.** <
e3c0: 64 64 3e 54 68 65 72 65 20 61 72 65 20 6e 6f 20  dd>There are no 
e3d0: 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68 69  arguments to thi
e3e0: 73 20 6f 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73  s option.  ^This
e3f0: 20 6f 70 74 69 6f 6e 20 73 65 74 73 20 74 68 65   option sets the
e400: 0a 2a 2a 20 5b 74 68 72 65 61 64 69 6e 67 20 6d  .** [threading m
e410: 6f 64 65 5d 20 74 6f 20 53 69 6e 67 6c 65 2d 74  ode] to Single-t
e420: 68 72 65 61 64 2e 20 20 49 6e 20 6f 74 68 65 72  hread.  In other
e430: 20 77 6f 72 64 73 2c 20 69 74 20 64 69 73 61 62   words, it disab
e440: 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65 78  les.** all mutex
e450: 69 6e 67 20 61 6e 64 20 70 75 74 73 20 53 51 4c  ing and puts SQL
e460: 69 74 65 20 69 6e 74 6f 20 61 20 6d 6f 64 65 20  ite into a mode 
e470: 77 68 65 72 65 20 69 74 20 63 61 6e 20 6f 6e 6c  where it can onl
e480: 79 20 62 65 20 75 73 65 64 0a 2a 2a 20 62 79 20  y be used.** by 
e490: 61 20 73 69 6e 67 6c 65 20 74 68 72 65 61 64 2e  a single thread.
e4a0: 20 20 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73     ^If SQLite is
e4b0: 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a   compiled with.*
e4c0: 2a 20 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48  * the [SQLITE_TH
e4d0: 52 45 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54  READSAFE | SQLIT
e4e0: 45 5f 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20  E_THREADSAFE=0] 
e4f0: 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74  compile-time opt
e500: 69 6f 6e 20 74 68 65 6e 0a 2a 2a 20 69 74 20 69  ion then.** it i
e510: 73 20 6e 6f 74 20 70 6f 73 73 69 62 6c 65 20 74  s not possible t
e520: 6f 20 63 68 61 6e 67 65 20 74 68 65 20 5b 74 68  o change the [th
e530: 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 66 72  reading mode] fr
e540: 6f 6d 20 69 74 73 20 64 65 66 61 75 6c 74 0a 2a  om its default.*
e550: 2a 20 76 61 6c 75 65 20 6f 66 20 53 69 6e 67 6c  * value of Singl
e560: 65 2d 74 68 72 65 61 64 20 61 6e 64 20 73 6f 20  e-thread and so 
e570: 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
e580: 29 5d 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 0a  )] will return .
e590: 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52  ** [SQLITE_ERROR
e5a0: 5d 20 69 66 20 63 61 6c 6c 65 64 20 77 69 74 68  ] if called with
e5b0: 20 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46   the SQLITE_CONF
e5c0: 49 47 5f 53 49 4e 47 4c 45 54 48 52 45 41 44 0a  IG_SINGLETHREAD.
e5d0: 2a 2a 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  ** configuration
e5e0: 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a 2a   option.</dd>.**
e5f0: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
e600: 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48 52 45 41  ONFIG_MULTITHREA
e610: 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  D</dt>.** <dd>Th
e620: 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67 75 6d  ere are no argum
e630: 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f 70 74  ents to this opt
e640: 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70 74 69  ion.  ^This opti
e650: 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20 5b  on sets the.** [
e660: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
e670: 74 6f 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 2e  to Multi-thread.
e680: 20 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73    In other words
e690: 2c 20 69 74 20 64 69 73 61 62 6c 65 73 0a 2a 2a  , it disables.**
e6a0: 20 6d 75 74 65 78 69 6e 67 20 6f 6e 20 5b 64 61   mutexing on [da
e6b0: 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
e6c0: 6e 5d 20 61 6e 64 20 5b 70 72 65 70 61 72 65 64  n] and [prepared
e6d0: 20 73 74 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65   statement] obje
e6e0: 63 74 73 2e 0a 2a 2a 20 54 68 65 20 61 70 70 6c  cts..** The appl
e6f0: 69 63 61 74 69 6f 6e 20 69 73 20 72 65 73 70 6f  ication is respo
e700: 6e 73 69 62 6c 65 20 66 6f 72 20 73 65 72 69 61  nsible for seria
e710: 6c 69 7a 69 6e 67 20 61 63 63 65 73 73 20 74 6f  lizing access to
e720: 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f  .** [database co
e730: 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20 5b  nnections] and [
e740: 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
e750: 6e 74 73 5d 2e 20 20 42 75 74 20 6f 74 68 65 72  nts].  But other
e760: 20 6d 75 74 65 78 65 73 0a 2a 2a 20 61 72 65 20   mutexes.** are 
e770: 65 6e 61 62 6c 65 64 20 73 6f 20 74 68 61 74 20  enabled so that 
e780: 53 51 4c 69 74 65 20 77 69 6c 6c 20 62 65 20 73  SQLite will be s
e790: 61 66 65 20 74 6f 20 75 73 65 20 69 6e 20 61 20  afe to use in a 
e7a0: 6d 75 6c 74 69 2d 74 68 72 65 61 64 65 64 0a 2a  multi-threaded.*
e7b0: 2a 20 65 6e 76 69 72 6f 6e 6d 65 6e 74 20 61 73  * environment as
e7c0: 20 6c 6f 6e 67 20 61 73 20 6e 6f 20 74 77 6f 20   long as no two 
e7d0: 74 68 72 65 61 64 73 20 61 74 74 65 6d 70 74 20  threads attempt 
e7e0: 74 6f 20 75 73 65 20 74 68 65 20 73 61 6d 65 0a  to use the same.
e7f0: 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
e800: 6e 65 63 74 69 6f 6e 5d 20 61 74 20 74 68 65 20  nection] at the 
e810: 73 61 6d 65 20 74 69 6d 65 2e 20 20 5e 49 66 20  same time.  ^If 
e820: 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69 6c  SQLite is compil
e830: 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b  ed with.** the [
e840: 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46  SQLITE_THREADSAF
e850: 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45 41  E | SQLITE_THREA
e860: 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65  DSAFE=0] compile
e870: 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65  -time option the
e880: 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20 70  n.** it is not p
e890: 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20 74  ossible to set t
e8a0: 68 65 20 4d 75 6c 74 69 2d 74 68 72 65 61 64 20  he Multi-thread 
e8b0: 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d  [threading mode]
e8c0: 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
e8d0: 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20  _config()] will 
e8e0: 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
e8f0: 52 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20  RROR] if called 
e900: 77 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49  with the.** SQLI
e910: 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
e920: 48 52 45 41 44 20 63 6f 6e 66 69 67 75 72 61 74  HREAD configurat
e930: 69 6f 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e  ion option.</dd>
e940: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
e950: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
e960: 5a 45 44 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  ZED</dt>.** <dd>
e970: 54 68 65 72 65 20 61 72 65 20 6e 6f 20 61 72 67  There are no arg
e980: 75 6d 65 6e 74 73 20 74 6f 20 74 68 69 73 20 6f  uments to this o
e990: 70 74 69 6f 6e 2e 20 20 5e 54 68 69 73 20 6f 70  ption.  ^This op
e9a0: 74 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a  tion sets the.**
e9b0: 20 5b 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65   [threading mode
e9c0: 5d 20 74 6f 20 53 65 72 69 61 6c 69 7a 65 64 2e  ] to Serialized.
e9d0: 20 49 6e 20 6f 74 68 65 72 20 77 6f 72 64 73 2c   In other words,
e9e0: 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 65 6e 61   this option ena
e9f0: 62 6c 65 73 0a 2a 2a 20 61 6c 6c 20 6d 75 74 65  bles.** all mute
ea00: 78 65 73 20 69 6e 63 6c 75 64 69 6e 67 20 74 68  xes including th
ea10: 65 20 72 65 63 75 72 73 69 76 65 0a 2a 2a 20 6d  e recursive.** m
ea20: 75 74 65 78 65 73 20 6f 6e 20 5b 64 61 74 61 62  utexes on [datab
ea30: 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20  ase connection] 
ea40: 61 6e 64 20 5b 70 72 65 70 61 72 65 64 20 73 74  and [prepared st
ea50: 61 74 65 6d 65 6e 74 5d 20 6f 62 6a 65 63 74 73  atement] objects
ea60: 2e 0a 2a 2a 20 49 6e 20 74 68 69 73 20 6d 6f 64  ..** In this mod
ea70: 65 20 28 77 68 69 63 68 20 69 73 20 74 68 65 20  e (which is the 
ea80: 64 65 66 61 75 6c 74 20 77 68 65 6e 20 53 51 4c  default when SQL
ea90: 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
eaa0: 77 69 74 68 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  with.** [SQLITE_
eab0: 54 48 52 45 41 44 53 41 46 45 3d 31 5d 29 20 74  THREADSAFE=1]) t
eac0: 68 65 20 53 51 4c 69 74 65 20 6c 69 62 72 61 72  he SQLite librar
ead0: 79 20 77 69 6c 6c 20 69 74 73 65 6c 66 20 73 65  y will itself se
eae0: 72 69 61 6c 69 7a 65 20 61 63 63 65 73 73 0a 2a  rialize access.*
eaf0: 2a 20 74 6f 20 5b 64 61 74 61 62 61 73 65 20 63  * to [database c
eb00: 6f 6e 6e 65 63 74 69 6f 6e 73 5d 20 61 6e 64 20  onnections] and 
eb10: 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
eb20: 65 6e 74 73 5d 20 73 6f 20 74 68 61 74 20 74 68  ents] so that th
eb30: 65 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e  e.** application
eb40: 20 69 73 20 66 72 65 65 20 74 6f 20 75 73 65 20   is free to use 
eb50: 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
eb60: 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f  se connection] o
eb70: 72 20 74 68 65 0a 2a 2a 20 73 61 6d 65 20 5b 70  r the.** same [p
eb80: 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
eb90: 74 5d 20 69 6e 20 64 69 66 66 65 72 65 6e 74 20  t] in different 
eba0: 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
ebb0: 61 6d 65 20 74 69 6d 65 2e 0a 2a 2a 20 5e 49 66  ame time..** ^If
ebc0: 20 53 51 4c 69 74 65 20 69 73 20 63 6f 6d 70 69   SQLite is compi
ebd0: 6c 65 64 20 77 69 74 68 0a 2a 2a 20 74 68 65 20  led with.** the 
ebe0: 5b 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41  [SQLITE_THREADSA
ebf0: 46 45 20 7c 20 53 51 4c 49 54 45 5f 54 48 52 45  FE | SQLITE_THRE
ec00: 41 44 53 41 46 45 3d 30 5d 20 63 6f 6d 70 69 6c  ADSAFE=0] compil
ec10: 65 2d 74 69 6d 65 20 6f 70 74 69 6f 6e 20 74 68  e-time option th
ec20: 65 6e 0a 2a 2a 20 69 74 20 69 73 20 6e 6f 74 20  en.** it is not 
ec30: 70 6f 73 73 69 62 6c 65 20 74 6f 20 73 65 74 20  possible to set 
ec40: 74 68 65 20 53 65 72 69 61 6c 69 7a 65 64 20 5b  the Serialized [
ec50: 74 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20  threading mode] 
ec60: 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  and.** [sqlite3_
ec70: 63 6f 6e 66 69 67 28 29 5d 20 77 69 6c 6c 20 72  config()] will r
ec80: 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45 52  eturn [SQLITE_ER
ec90: 52 4f 52 5d 20 69 66 20 63 61 6c 6c 65 64 20 77  ROR] if called w
eca0: 69 74 68 20 74 68 65 0a 2a 2a 20 53 51 4c 49 54  ith the.** SQLIT
ecb0: 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41 4c 49  E_CONFIG_SERIALI
ecc0: 5a 45 44 20 63 6f 6e 66 69 67 75 72 61 74 69 6f  ZED configuratio
ecd0: 6e 20 6f 70 74 69 6f 6e 2e 3c 2f 64 64 3e 0a 2a  n option.</dd>.*
ece0: 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
ecf0: 43 4f 4e 46 49 47 5f 4d 41 4c 4c 4f 43 3c 2f 64  CONFIG_MALLOC</d
ed00: 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
ed10: 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61  s option takes a
ed20: 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
ed30: 20 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e   which is a poin
ed40: 74 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73  ter to an.** ins
ed50: 74 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71  tance of the [sq
ed60: 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64  lite3_mem_method
ed70: 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20 54  s] structure.  T
ed80: 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65 63  he argument spec
ed90: 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e 61  ifies.** alterna
eda0: 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20 6d  tive low-level m
edb0: 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
edc0: 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20   routines to be 
edd0: 75 73 65 64 20 69 6e 20 70 6c 61 63 65 20 6f 66  used in place of
ede0: 0a 2a 2a 20 74 68 65 20 6d 65 6d 6f 72 79 20 61  .** the memory a
edf0: 6c 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e  llocation routin
ee00: 65 73 20 62 75 69 6c 74 20 69 6e 74 6f 20 53 51  es built into SQ
ee10: 4c 69 74 65 2e 29 5e 20 5e 53 51 4c 69 74 65 20  Lite.)^ ^SQLite 
ee20: 6d 61 6b 65 73 0a 2a 2a 20 69 74 73 20 6f 77 6e  makes.** its own
ee30: 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
ee40: 20 74 68 65 20 63 6f 6e 74 65 6e 74 20 6f 66 20   the content of 
ee50: 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d  the [sqlite3_mem
ee60: 5f 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74  _methods] struct
ee70: 75 72 65 0a 2a 2a 20 62 65 66 6f 72 65 20 74 68  ure.** before th
ee80: 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69  e [sqlite3_confi
ee90: 67 28 29 5d 20 63 61 6c 6c 20 72 65 74 75 72 6e  g()] call return
eea0: 73 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  s.</dd>.**.** <d
eeb0: 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
eec0: 47 45 54 4d 41 4c 4c 4f 43 3c 2f 64 74 3e 0a 2a  GETMALLOC</dt>.*
eed0: 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73 20 6f 70  * <dd> ^(This op
eee0: 74 69 6f 6e 20 74 61 6b 65 73 20 61 20 73 69 6e  tion takes a sin
eef0: 67 6c 65 20 61 72 67 75 6d 65 6e 74 20 77 68 69  gle argument whi
ef00: 63 68 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20  ch is a pointer 
ef10: 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74 61 6e 63  to an.** instanc
ef20: 65 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65  e of the [sqlite
ef30: 33 5f 6d 65 6d 5f 6d 65 74 68 6f 64 73 5d 20 73  3_mem_methods] s
ef40: 74 72 75 63 74 75 72 65 2e 20 20 54 68 65 20 5b  tructure.  The [
ef50: 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
ef60: 6f 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72  ods].** structur
ef70: 65 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68  e is filled with
ef80: 20 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64   the currently d
ef90: 65 66 69 6e 65 64 20 6d 65 6d 6f 72 79 20 61 6c  efined memory al
efa0: 6c 6f 63 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65  location routine
efb0: 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20 6f 70 74  s.)^.** This opt
efc0: 69 6f 6e 20 63 61 6e 20 62 65 20 75 73 65 64 20  ion can be used 
efd0: 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74 68 65 20  to overload the 
efe0: 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79 20 61  default memory a
eff0: 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72 6f 75  llocation.** rou
f000: 74 69 6e 65 73 20 77 69 74 68 20 61 20 77 72 61  tines with a wra
f010: 70 70 65 72 20 74 68 61 74 20 73 69 6d 75 6c 61  pper that simula
f020: 74 69 6f 6e 73 20 6d 65 6d 6f 72 79 20 61 6c 6c  tions memory all
f030: 6f 63 61 74 69 6f 6e 20 66 61 69 6c 75 72 65 20  ocation failure 
f040: 6f 72 0a 2a 2a 20 74 72 61 63 6b 73 20 6d 65 6d  or.** tracks mem
f050: 6f 72 79 20 75 73 61 67 65 2c 20 66 6f 72 20 65  ory usage, for e
f060: 78 61 6d 70 6c 65 2e 20 3c 2f 64 64 3e 0a 2a 2a  xample. </dd>.**
f070: 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43  .** <dt>SQLITE_C
f080: 4f 4e 46 49 47 5f 4d 45 4d 53 54 41 54 55 53 3c  ONFIG_MEMSTATUS<
f090: 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68  /dt>.** <dd> ^Th
f0a0: 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20  is option takes 
f0b0: 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
f0c0: 6f 66 20 74 79 70 65 20 69 6e 74 2c 20 69 6e 74  of type int, int
f0d0: 65 72 70 72 65 74 65 64 20 61 73 20 61 20 0a 2a  erpreted as a .*
f0e0: 2a 20 62 6f 6f 6c 65 61 6e 2c 20 77 68 69 63 68  * boolean, which
f0f0: 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69 73 61   enables or disa
f100: 62 6c 65 73 20 74 68 65 20 63 6f 6c 6c 65 63 74  bles the collect
f110: 69 6f 6e 20 6f 66 20 6d 65 6d 6f 72 79 20 61 6c  ion of memory al
f120: 6c 6f 63 61 74 69 6f 6e 20 0a 2a 2a 20 73 74 61  location .** sta
f130: 74 69 73 74 69 63 73 2e 20 5e 28 57 68 65 6e 20  tistics. ^(When 
f140: 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
f150: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
f160: 20 64 69 73 61 62 6c 65 64 2c 20 74 68 65 20 0a   disabled, the .
f170: 2a 2a 20 66 6f 6c 6c 6f 77 69 6e 67 20 53 51 4c  ** following SQL
f180: 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 20 62  ite interfaces b
f190: 65 63 6f 6d 65 20 6e 6f 6e 2d 6f 70 65 72 61 74  ecome non-operat
f1a0: 69 6f 6e 61 6c 3a 0a 2a 2a 20 20 20 3c 75 6c 3e  ional:.**   <ul>
f1b0: 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c 69  .**   <li> [sqli
f1c0: 74 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28  te3_memory_used(
f1d0: 29 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71  )].**   <li> [sq
f1e0: 6c 69 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67  lite3_memory_hig
f1f0: 68 77 61 74 65 72 28 29 5d 0a 2a 2a 20 20 20 3c  hwater()].**   <
f200: 6c 69 3e 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  li> [sqlite3_sof
f210: 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
f220: 5d 0a 2a 2a 20 20 20 3c 6c 69 3e 20 5b 73 71 6c  ].**   <li> [sql
f230: 69 74 65 33 5f 73 74 61 74 75 73 28 29 5d 0a 2a  ite3_status()].*
f240: 2a 20 20 20 3c 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e  *   </ul>)^.** ^
f250: 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  Memory allocatio
f260: 6e 20 73 74 61 74 69 73 74 69 63 73 20 61 72 65  n statistics are
f270: 20 65 6e 61 62 6c 65 64 20 62 79 20 64 65 66 61   enabled by defa
f280: 75 6c 74 20 75 6e 6c 65 73 73 20 53 51 4c 69 74  ult unless SQLit
f290: 65 20 69 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64  e is.** compiled
f2a0: 20 77 69 74 68 20 5b 53 51 4c 49 54 45 5f 44 45   with [SQLITE_DE
f2b0: 46 41 55 4c 54 5f 4d 45 4d 53 54 41 54 55 53 5d  FAULT_MEMSTATUS]
f2c0: 3d 30 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  =0 in which case
f2d0: 20 6d 65 6d 6f 72 79 0a 2a 2a 20 61 6c 6c 6f 63   memory.** alloc
f2e0: 61 74 69 6f 6e 20 73 74 61 74 69 73 74 69 63 73  ation statistics
f2f0: 20 61 72 65 20 64 69 73 61 62 6c 65 64 20 62 79   are disabled by
f300: 20 64 65 66 61 75 6c 74 2e 0a 2a 2a 20 3c 2f 64   default..** </d
f310: 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
f320: 49 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54  ITE_CONFIG_SCRAT
f330: 43 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  CH</dt>.** <dd> 
f340: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f350: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f360: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f370: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f380: 65 20 66 6f 72 0a 2a 2a 20 73 63 72 61 74 63 68  e for.** scratch
f390: 20 6d 65 6d 6f 72 79 2e 20 20 54 68 65 72 65 20   memory.  There 
f3a0: 61 72 65 20 74 68 72 65 65 20 61 72 67 75 6d 65  are three argume
f3b0: 6e 74 73 3a 20 20 41 20 70 6f 69 6e 74 65 72 20  nts:  A pointer 
f3c0: 61 6e 20 38 2d 62 79 74 65 0a 2a 2a 20 61 6c 69  an 8-byte.** ali
f3d0: 67 6e 65 64 20 6d 65 6d 6f 72 79 20 62 75 66 66  gned memory buff
f3e0: 65 72 20 66 72 6f 6d 20 77 68 69 63 68 20 74 68  er from which th
f3f0: 65 20 73 63 72 61 74 63 68 20 61 6c 6c 6f 63 61  e scratch alloca
f400: 74 69 6f 6e 73 20 77 69 6c 6c 20 62 65 0a 2a 2a  tions will be.**
f410: 20 64 72 61 77 6e 2c 20 74 68 65 20 73 69 7a 65   drawn, the size
f420: 20 6f 66 20 65 61 63 68 20 73 63 72 61 74 63 68   of each scratch
f430: 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 28 73 7a 29   allocation (sz)
f440: 2c 0a 2a 2a 20 61 6e 64 20 74 68 65 20 6d 61 78  ,.** and the max
f450: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 73  imum number of s
f460: 63 72 61 74 63 68 20 61 6c 6c 6f 63 61 74 69 6f  cratch allocatio
f470: 6e 73 20 28 4e 29 2e 20 20 54 68 65 20 73 7a 0a  ns (N).  The sz.
f480: 2a 2a 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  ** argument must
f490: 20 62 65 20 61 20 6d 75 6c 74 69 70 6c 65 20 6f   be a multiple o
f4a0: 66 20 31 36 2e 0a 2a 2a 20 54 68 65 20 66 69 72  f 16..** The fir
f4b0: 73 74 20 61 72 67 75 6d 65 6e 74 20 6d 75 73 74  st argument must
f4c0: 20 62 65 20 61 20 70 6f 69 6e 74 65 72 20 74 6f   be a pointer to
f4d0: 20 61 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e   an 8-byte align
f4e0: 65 64 20 62 75 66 66 65 72 0a 2a 2a 20 6f 66 20  ed buffer.** of 
f4f0: 61 74 20 6c 65 61 73 74 20 73 7a 2a 4e 20 62 79  at least sz*N by
f500: 74 65 73 20 6f 66 20 6d 65 6d 6f 72 79 2e 0a 2a  tes of memory..*
f510: 2a 20 5e 53 51 4c 69 74 65 20 77 69 6c 6c 20 75  * ^SQLite will u
f520: 73 65 20 6e 6f 20 6d 6f 72 65 20 74 68 61 6e 20  se no more than 
f530: 74 77 6f 20 73 63 72 61 74 63 68 20 62 75 66 66  two scratch buff
f540: 65 72 73 20 70 65 72 20 74 68 72 65 61 64 2e 20  ers per thread. 
f550: 20 53 6f 0a 2a 2a 20 4e 20 73 68 6f 75 6c 64 20   So.** N should 
f560: 62 65 20 73 65 74 20 74 6f 20 74 77 69 63 65 20  be set to twice 
f570: 74 68 65 20 65 78 70 65 63 74 65 64 20 6d 61 78  the expected max
f580: 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 74  imum number of t
f590: 68 72 65 61 64 73 2e 0a 2a 2a 20 5e 53 51 4c 69  hreads..** ^SQLi
f5a0: 74 65 20 77 69 6c 6c 20 6e 65 76 65 72 20 72 65  te will never re
f5b0: 71 75 69 72 65 20 61 20 73 63 72 61 74 63 68 20  quire a scratch 
f5c0: 62 75 66 66 65 72 20 74 68 61 74 20 69 73 20 6d  buffer that is m
f5d0: 6f 72 65 20 74 68 61 6e 20 36 0a 2a 2a 20 74 69  ore than 6.** ti
f5e0: 6d 65 73 20 74 68 65 20 64 61 74 61 62 61 73 65  mes the database
f5f0: 20 70 61 67 65 20 73 69 7a 65 2e 20 5e 49 66 20   page size. ^If 
f600: 53 51 4c 69 74 65 20 6e 65 65 64 73 20 6e 65 65  SQLite needs nee
f610: 64 73 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a 2a  ds additional.**
f620: 20 73 63 72 61 74 63 68 20 6d 65 6d 6f 72 79 20   scratch memory 
f630: 62 65 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70  beyond what is p
f640: 72 6f 76 69 64 65 64 20 62 79 20 74 68 69 73 20  rovided by this 
f650: 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70  configuration op
f660: 74 69 6f 6e 2c 20 74 68 65 6e 20 0a 2a 2a 20 5b  tion, then .** [
f670: 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
f680: 5d 20 77 69 6c 6c 20 62 65 20 75 73 65 64 20 74  ] will be used t
f690: 6f 20 6f 62 74 61 69 6e 20 74 68 65 20 6d 65 6d  o obtain the mem
f6a0: 6f 72 79 20 6e 65 65 64 65 64 2e 3c 2f 64 64 3e  ory needed.</dd>
f6b0: 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
f6c0: 45 5f 43 4f 4e 46 49 47 5f 50 41 47 45 43 41 43  E_CONFIG_PAGECAC
f6d0: 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20  HE</dt>.** <dd> 
f6e0: 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20 73 70 65  ^This option spe
f6f0: 63 69 66 69 65 73 20 61 20 73 74 61 74 69 63 20  cifies a static 
f700: 6d 65 6d 6f 72 79 20 62 75 66 66 65 72 20 74 68  memory buffer th
f710: 61 74 20 53 51 4c 69 74 65 20 63 61 6e 20 75 73  at SQLite can us
f720: 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 64 61 74  e for.** the dat
f730: 61 62 61 73 65 20 70 61 67 65 20 63 61 63 68 65  abase page cache
f740: 20 77 69 74 68 20 74 68 65 20 64 65 66 61 75 6c   with the defaul
f750: 74 20 70 61 67 65 20 63 61 63 68 65 20 69 6d 70  t page cache imp
f760: 6c 65 6d 65 6e 61 74 69 6f 6e 2e 20 20 0a 2a 2a  lemenation.  .**
f770: 20 54 68 69 73 20 63 6f 6e 66 69 67 75 72 61 74   This configurat
f780: 69 6f 6e 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62  ion should not b
f790: 65 20 75 73 65 64 20 69 66 20 61 6e 20 61 70 70  e used if an app
f7a0: 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 20  lication-define 
f7b0: 70 61 67 65 0a 2a 2a 20 63 61 63 68 65 20 69 6d  page.** cache im
f7c0: 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
f7d0: 6c 6f 61 64 65 64 20 75 73 69 6e 67 20 74 68 65  loaded using the
f7e0: 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 50   SQLITE_CONFIG_P
f7f0: 43 41 43 48 45 20 6f 70 74 69 6f 6e 2e 0a 2a 2a  CACHE option..**
f800: 20 54 68 65 72 65 20 61 72 65 20 74 68 72 65 65   There are three
f810: 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74 68   arguments to th
f820: 69 73 20 6f 70 74 69 6f 6e 3a 20 41 20 70 6f 69  is option: A poi
f830: 6e 74 65 72 20 74 6f 20 38 2d 62 79 74 65 20 61  nter to 8-byte a
f840: 6c 69 67 6e 65 64 0a 2a 2a 20 6d 65 6d 6f 72 79  ligned.** memory
f850: 2c 20 74 68 65 20 73 69 7a 65 20 6f 66 20 65 61  , the size of ea
f860: 63 68 20 70 61 67 65 20 62 75 66 66 65 72 20 28  ch page buffer (
f870: 73 7a 29 2c 20 61 6e 64 20 74 68 65 20 6e 75 6d  sz), and the num
f880: 62 65 72 20 6f 66 20 70 61 67 65 73 20 28 4e 29  ber of pages (N)
f890: 2e 0a 2a 2a 20 54 68 65 20 73 7a 20 61 72 67 75  ..** The sz argu
f8a0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65 20 74  ment should be t
f8b0: 68 65 20 73 69 7a 65 20 6f 66 20 74 68 65 20 6c  he size of the l
f8c0: 61 72 67 65 73 74 20 64 61 74 61 62 61 73 65 20  argest database 
f8d0: 70 61 67 65 0a 2a 2a 20 28 61 20 70 6f 77 65 72  page.** (a power
f8e0: 20 6f 66 20 74 77 6f 20 62 65 74 77 65 65 6e 20   of two between 
f8f0: 35 31 32 20 61 6e 64 20 33 32 37 36 38 29 20 70  512 and 32768) p
f900: 6c 75 73 20 61 20 6c 69 74 74 6c 65 20 65 78 74  lus a little ext
f910: 72 61 20 66 6f 72 20 65 61 63 68 0a 2a 2a 20 70  ra for each.** p
f920: 61 67 65 20 68 65 61 64 65 72 2e 20 20 5e 54 68  age header.  ^Th
f930: 65 20 70 61 67 65 20 68 65 61 64 65 72 20 73 69  e page header si
f940: 7a 65 20 69 73 20 32 30 20 74 6f 20 34 30 20 62  ze is 20 to 40 b
f950: 79 74 65 73 20 64 65 70 65 6e 64 69 6e 67 20 6f  ytes depending o
f960: 6e 0a 2a 2a 20 74 68 65 20 68 6f 73 74 20 61 72  n.** the host ar
f970: 63 68 69 74 65 63 74 75 72 65 2e 20 20 5e 49 74  chitecture.  ^It
f980: 20 69 73 20 68 61 72 6d 6c 65 73 73 2c 20 61 70   is harmless, ap
f990: 61 72 74 20 66 72 6f 6d 20 74 68 65 20 77 61 73  art from the was
f9a0: 74 65 64 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74  ted memory,.** t
f9b0: 6f 20 6d 61 6b 65 20 73 7a 20 61 20 6c 69 74 74  o make sz a litt
f9c0: 6c 65 20 74 6f 6f 20 6c 61 72 67 65 2e 20 20 54  le too large.  T
f9d0: 68 65 20 66 69 72 73 74 0a 2a 2a 20 61 72 67 75  he first.** argu
f9e0: 6d 65 6e 74 20 73 68 6f 75 6c 64 20 70 6f 69 6e  ment should poin
f9f0: 74 20 74 6f 20 61 6e 20 61 6c 6c 6f 63 61 74 69  t to an allocati
fa00: 6f 6e 20 6f 66 20 61 74 20 6c 65 61 73 74 20 73  on of at least s
fa10: 7a 2a 4e 20 62 79 74 65 73 20 6f 66 20 6d 65 6d  z*N bytes of mem
fa20: 6f 72 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65 20  ory..** ^SQLite 
fa30: 77 69 6c 6c 20 75 73 65 20 74 68 65 20 6d 65 6d  will use the mem
fa40: 6f 72 79 20 70 72 6f 76 69 64 65 64 20 62 79 20  ory provided by 
fa50: 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
fa60: 6e 74 20 74 6f 20 73 61 74 69 73 66 79 20 69 74  nt to satisfy it
fa70: 73 0a 2a 2a 20 6d 65 6d 6f 72 79 20 6e 65 65 64  s.** memory need
fa80: 73 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20  s for the first 
fa90: 4e 20 70 61 67 65 73 20 74 68 61 74 20 69 74 20  N pages that it 
faa0: 61 64 64 73 20 74 6f 20 63 61 63 68 65 2e 20 20  adds to cache.  
fab0: 5e 49 66 20 61 64 64 69 74 69 6f 6e 61 6c 0a 2a  ^If additional.*
fac0: 2a 20 70 61 67 65 20 63 61 63 68 65 20 6d 65 6d  * page cache mem
fad0: 6f 72 79 20 69 73 20 6e 65 65 64 65 64 20 62 65  ory is needed be
fae0: 79 6f 6e 64 20 77 68 61 74 20 69 73 20 70 72 6f  yond what is pro
faf0: 76 69 64 65 64 20 62 79 20 74 68 69 73 20 6f 70  vided by this op
fb00: 74 69 6f 6e 2c 20 74 68 65 6e 0a 2a 2a 20 53 51  tion, then.** SQ
fb10: 4c 69 74 65 20 67 6f 65 73 20 74 6f 20 5b 73 71  Lite goes to [sq
fb20: 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20  lite3_malloc()] 
fb30: 66 6f 72 20 74 68 65 20 61 64 64 69 74 69 6f 6e  for the addition
fb40: 61 6c 20 73 74 6f 72 61 67 65 20 73 70 61 63 65  al storage space
fb50: 2e 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72  ..** The pointer
fb60: 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
fb70: 67 75 6d 65 6e 74 20 6d 75 73 74 0a 2a 2a 20 62  gument must.** b
fb80: 65 20 61 6c 69 67 6e 65 64 20 74 6f 20 61 6e 20  e aligned to an 
fb90: 38 2d 62 79 74 65 20 62 6f 75 6e 64 61 72 79 20  8-byte boundary 
fba0: 6f 72 20 73 75 62 73 65 71 75 65 6e 74 20 62 65  or subsequent be
fbb0: 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
fbc0: 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 75 6e 64 65  .** will be unde
fbd0: 66 69 6e 65 64 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  fined.</dd>.**.*
fbe0: 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
fbf0: 46 49 47 5f 48 45 41 50 3c 2f 64 74 3e 0a 2a 2a  FIG_HEAP</dt>.**
fc00: 20 3c 64 64 3e 20 5e 54 68 69 73 20 6f 70 74 69   <dd> ^This opti
fc10: 6f 6e 20 73 70 65 63 69 66 69 65 73 20 61 20 73  on specifies a s
fc20: 74 61 74 69 63 20 6d 65 6d 6f 72 79 20 62 75 66  tatic memory buf
fc30: 66 65 72 20 74 68 61 74 20 53 51 4c 69 74 65 20  fer that SQLite 
fc40: 77 69 6c 6c 20 75 73 65 0a 2a 2a 20 66 6f 72 20  will use.** for 
fc50: 61 6c 6c 20 6f 66 20 69 74 73 20 64 79 6e 61 6d  all of its dynam
fc60: 69 63 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  ic memory alloca
fc70: 74 69 6f 6e 20 6e 65 65 64 73 20 62 65 79 6f 6e  tion needs beyon
fc80: 64 20 74 68 6f 73 65 20 70 72 6f 76 69 64 65 64  d those provided
fc90: 0a 2a 2a 20 66 6f 72 20 62 79 20 5b 53 51 4c 49  .** for by [SQLI
fca0: 54 45 5f 43 4f 4e 46 49 47 5f 53 43 52 41 54 43  TE_CONFIG_SCRATC
fcb0: 48 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 43  H] and [SQLITE_C
fcc0: 4f 4e 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d  ONFIG_PAGECACHE]
fcd0: 2e 0a 2a 2a 20 54 68 65 72 65 20 61 72 65 20 74  ..** There are t
fce0: 68 72 65 65 20 61 72 67 75 6d 65 6e 74 73 3a 20  hree arguments: 
fcf0: 41 6e 20 38 2d 62 79 74 65 20 61 6c 69 67 6e 65  An 8-byte aligne
fd00: 64 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65  d pointer to the
fd10: 20 6d 65 6d 6f 72 79 2c 0a 2a 2a 20 74 68 65 20   memory,.** the 
fd20: 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
fd30: 69 6e 20 74 68 65 20 6d 65 6d 6f 72 79 20 62 75  in the memory bu
fd40: 66 66 65 72 2c 20 61 6e 64 20 74 68 65 20 6d 69  ffer, and the mi
fd50: 6e 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e  nimum allocation
fd60: 20 73 69 7a 65 2e 0a 2a 2a 20 5e 49 66 20 74 68   size..** ^If th
fd70: 65 20 66 69 72 73 74 20 70 6f 69 6e 74 65 72 20  e first pointer 
fd80: 28 74 68 65 20 6d 65 6d 6f 72 79 20 70 6f 69 6e  (the memory poin
fd90: 74 65 72 29 20 69 73 20 4e 55 4c 4c 2c 20 74 68  ter) is NULL, th
fda0: 65 6e 20 53 51 4c 69 74 65 20 72 65 76 65 72 74  en SQLite revert
fdb0: 73 0a 2a 2a 20 74 6f 20 75 73 69 6e 67 20 69 74  s.** to using it
fdc0: 73 20 64 65 66 61 75 6c 74 20 6d 65 6d 6f 72 79  s default memory
fdd0: 20 61 6c 6c 6f 63 61 74 6f 72 20 28 74 68 65 20   allocator (the 
fde0: 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28 29 20  system malloc() 
fdf0: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 29 2c  implementation),
fe00: 0a 2a 2a 20 75 6e 64 6f 69 6e 67 20 61 6e 79 20  .** undoing any 
fe10: 70 72 69 6f 72 20 69 6e 76 6f 63 61 74 69 6f 6e  prior invocation
fe20: 20 6f 66 20 5b 53 51 4c 49 54 45 5f 43 4f 4e 46   of [SQLITE_CONF
fe30: 49 47 5f 4d 41 4c 4c 4f 43 5d 2e 20 20 5e 49 66  IG_MALLOC].  ^If
fe40: 20 74 68 65 0a 2a 2a 20 6d 65 6d 6f 72 79 20 70   the.** memory p
fe50: 6f 69 6e 74 65 72 20 69 73 20 6e 6f 74 20 4e 55  ointer is not NU
fe60: 4c 4c 20 61 6e 64 20 65 69 74 68 65 72 20 5b 53  LL and either [S
fe70: 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d  QLITE_ENABLE_MEM
fe80: 53 59 53 33 5d 20 6f 72 0a 2a 2a 20 5b 53 51 4c  SYS3] or.** [SQL
fe90: 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 53 59  ITE_ENABLE_MEMSY
fea0: 53 35 5d 20 61 72 65 20 64 65 66 69 6e 65 64 2c  S5] are defined,
feb0: 20 74 68 65 6e 20 74 68 65 20 61 6c 74 65 72 6e   then the altern
fec0: 61 74 69 76 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  ative memory.** 
fed0: 61 6c 6c 6f 63 61 74 6f 72 20 69 73 20 65 6e 67  allocator is eng
fee0: 61 67 65 64 20 74 6f 20 68 61 6e 64 6c 65 20 61  aged to handle a
fef0: 6c 6c 20 6f 66 20 53 51 4c 69 74 65 73 20 6d 65  ll of SQLites me
ff00: 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  mory allocation 
ff10: 6e 65 65 64 73 2e 0a 2a 2a 20 54 68 65 20 66 69  needs..** The fi
ff20: 72 73 74 20 70 6f 69 6e 74 65 72 20 28 74 68 65  rst pointer (the
ff30: 20 6d 65 6d 6f 72 79 20 70 6f 69 6e 74 65 72 29   memory pointer)
ff40: 20 6d 75 73 74 20 62 65 20 61 6c 69 67 6e 65 64   must be aligned
ff50: 20 74 6f 20 61 6e 20 38 2d 62 79 74 65 0a 2a 2a   to an 8-byte.**
ff60: 20 62 6f 75 6e 64 61 72 79 20 6f 72 20 73 75 62   boundary or sub
ff70: 73 65 71 75 65 6e 74 20 62 65 68 61 76 69 6f 72  sequent behavior
ff80: 20 6f 66 20 53 51 4c 69 74 65 20 77 69 6c 6c 20   of SQLite will 
ff90: 62 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a  be undefined..**
ffa0: 20 54 68 65 20 6d 69 6e 69 6d 75 6d 20 61 6c 6c   The minimum all
ffb0: 6f 63 61 74 69 6f 6e 20 73 69 7a 65 20 69 73 20  ocation size is 
ffc0: 63 61 70 70 65 64 20 61 74 20 32 5e 31 32 2e 20  capped at 2^12. 
ffd0: 52 65 61 73 6f 6e 61 62 6c 65 20 76 61 6c 75 65  Reasonable value
ffe0: 73 0a 2a 2a 20 66 6f 72 20 74 68 65 20 6d 69 6e  s.** for the min
fff0: 69 6d 75 6d 20 61 6c 6c 6f 63 61 74 69 6f 6e 20  imum allocation 
10000 73 69 7a 65 20 61 72 65 20 32 5e 35 20 74 68 72  size are 2^5 thr
10010 6f 75 67 68 20 32 5e 38 2e 3c 2f 64 64 3e 0a 2a  ough 2^8.</dd>.*
10020 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f  *.** <dt>SQLITE_
10030 43 4f 4e 46 49 47 5f 4d 55 54 45 58 3c 2f 64 74  CONFIG_MUTEX</dt
10040 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69 73  >.** <dd> ^(This
10050 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
10060 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
10070 77 68 69 63 68 20 69 73 20 61 20 70 6f 69 6e 74  which is a point
10080 65 72 20 74 6f 20 61 6e 0a 2a 2a 20 69 6e 73 74  er to an.** inst
10090 61 6e 63 65 20 6f 66 20 74 68 65 20 5b 73 71 6c  ance of the [sql
100a0 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
100b0 64 73 5d 20 73 74 72 75 63 74 75 72 65 2e 20 20  ds] structure.  
100c0 54 68 65 20 61 72 67 75 6d 65 6e 74 20 73 70 65  The argument spe
100d0 63 69 66 69 65 73 0a 2a 2a 20 61 6c 74 65 72 6e  cifies.** altern
100e0 61 74 69 76 65 20 6c 6f 77 2d 6c 65 76 65 6c 20  ative low-level 
100f0 6d 75 74 65 78 20 72 6f 75 74 69 6e 65 73 20 74  mutex routines t
10100 6f 20 62 65 20 75 73 65 64 20 69 6e 20 70 6c 61  o be used in pla
10110 63 65 0a 2a 2a 20 74 68 65 20 6d 75 74 65 78 20  ce.** the mutex 
10120 72 6f 75 74 69 6e 65 73 20 62 75 69 6c 74 20 69  routines built i
10130 6e 74 6f 20 53 51 4c 69 74 65 2e 29 5e 20 20 5e  nto SQLite.)^  ^
10140 53 51 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63  SQLite makes a c
10150 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 63 6f  opy of the.** co
10160 6e 74 65 6e 74 20 6f 66 20 74 68 65 20 5b 73 71  ntent of the [sq
10170 6c 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68  lite3_mutex_meth
10180 6f 64 73 5d 20 73 74 72 75 63 74 75 72 65 20 62  ods] structure b
10190 65 66 6f 72 65 20 74 68 65 20 63 61 6c 6c 20 74  efore the call t
101a0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f  o.** [sqlite3_co
101b0 6e 66 69 67 28 29 5d 20 72 65 74 75 72 6e 73 2e  nfig()] returns.
101c0 20 5e 49 66 20 53 51 4c 69 74 65 20 69 73 20 63   ^If SQLite is c
101d0 6f 6d 70 69 6c 65 64 20 77 69 74 68 0a 2a 2a 20  ompiled with.** 
101e0 74 68 65 20 5b 53 51 4c 49 54 45 5f 54 48 52 45  the [SQLITE_THRE
101f0 41 44 53 41 46 45 20 7c 20 53 51 4c 49 54 45 5f  ADSAFE | SQLITE_
10200 54 48 52 45 41 44 53 41 46 45 3d 30 5d 20 63 6f  THREADSAFE=0] co
10210 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 70 74 69 6f  mpile-time optio
10220 6e 20 74 68 65 6e 0a 2a 2a 20 74 68 65 20 65 6e  n then.** the en
10230 74 69 72 65 20 6d 75 74 65 78 69 6e 67 20 73 75  tire mutexing su
10240 62 73 79 73 74 65 6d 20 69 73 20 6f 6d 69 74 74  bsystem is omitt
10250 65 64 20 66 72 6f 6d 20 74 68 65 20 62 75 69 6c  ed from the buil
10260 64 20 61 6e 64 20 68 65 6e 63 65 20 63 61 6c 6c  d and hence call
10270 73 20 74 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  s to.** [sqlite3
10280 5f 63 6f 6e 66 69 67 28 29 5d 20 77 69 74 68 20  _config()] with 
10290 74 68 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  the SQLITE_CONFI
102a0 47 5f 4d 55 54 45 58 20 63 6f 6e 66 69 67 75 72  G_MUTEX configur
102b0 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 20 77 69 6c  ation option wil
102c0 6c 0a 2a 2a 20 72 65 74 75 72 6e 20 5b 53 51 4c  l.** return [SQL
102d0 49 54 45 5f 45 52 52 4f 52 5d 2e 3c 2f 64 64 3e  ITE_ERROR].</dd>
102e0 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49 54  .**.** <dt>SQLIT
102f0 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54 45  E_CONFIG_GETMUTE
10300 58 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  X</dt>.** <dd> ^
10310 28 54 68 69 73 20 6f 70 74 69 6f 6e 20 74 61 6b  (This option tak
10320 65 73 20 61 20 73 69 6e 67 6c 65 20 61 72 67 75  es a single argu
10330 6d 65 6e 74 20 77 68 69 63 68 20 69 73 20 61 20  ment which is a 
10340 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 0a 2a 2a  pointer to an.**
10350 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 65   instance of the
10360 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65 78 5f   [sqlite3_mutex_
10370 6d 65 74 68 6f 64 73 5d 20 73 74 72 75 63 74 75  methods] structu
10380 72 65 2e 20 20 54 68 65 0a 2a 2a 20 5b 73 71 6c  re.  The.** [sql
10390 69 74 65 33 5f 6d 75 74 65 78 5f 6d 65 74 68 6f  ite3_mutex_metho
103a0 64 73 5d 0a 2a 2a 20 73 74 72 75 63 74 75 72 65  ds].** structure
103b0 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74 68 20   is filled with 
103c0 74 68 65 20 63 75 72 72 65 6e 74 6c 79 20 64 65  the currently de
103d0 66 69 6e 65 64 20 6d 75 74 65 78 20 72 6f 75 74  fined mutex rout
103e0 69 6e 65 73 2e 29 5e 0a 2a 2a 20 54 68 69 73 20  ines.)^.** This 
103f0 6f 70 74 69 6f 6e 20 63 61 6e 20 62 65 20 75 73  option can be us
10400 65 64 20 74 6f 20 6f 76 65 72 6c 6f 61 64 20 74  ed to overload t
10410 68 65 20 64 65 66 61 75 6c 74 20 6d 75 74 65 78  he default mutex
10420 20 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 72   allocation.** r
10430 6f 75 74 69 6e 65 73 20 77 69 74 68 20 61 20 77  outines with a w
10440 72 61 70 70 65 72 20 75 73 65 64 20 74 6f 20 74  rapper used to t
10450 72 61 63 6b 20 6d 75 74 65 78 20 75 73 61 67 65  rack mutex usage
10460 20 66 6f 72 20 70 65 72 66 6f 72 6d 61 6e 63 65   for performance
10470 0a 2a 2a 20 70 72 6f 66 69 6c 69 6e 67 20 6f 72  .** profiling or
10480 20 74 65 73 74 69 6e 67 2c 20 66 6f 72 20 65 78   testing, for ex
10490 61 6d 70 6c 65 2e 20 20 20 5e 49 66 20 53 51 4c  ample.   ^If SQL
104a0 69 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20  ite is compiled 
104b0 77 69 74 68 0a 2a 2a 20 74 68 65 20 5b 53 51 4c  with.** the [SQL
104c0 49 54 45 5f 54 48 52 45 41 44 53 41 46 45 20 7c  ITE_THREADSAFE |
104d0 20 53 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41   SQLITE_THREADSA
104e0 46 45 3d 30 5d 20 63 6f 6d 70 69 6c 65 2d 74 69  FE=0] compile-ti
104f0 6d 65 20 6f 70 74 69 6f 6e 20 74 68 65 6e 0a 2a  me option then.*
10500 2a 20 74 68 65 20 65 6e 74 69 72 65 20 6d 75 74  * the entire mut
10510 65 78 69 6e 67 20 73 75 62 73 79 73 74 65 6d 20  exing subsystem 
10520 69 73 20 6f 6d 69 74 74 65 64 20 66 72 6f 6d 20  is omitted from 
10530 74 68 65 20 62 75 69 6c 64 20 61 6e 64 20 68 65  the build and he
10540 6e 63 65 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a 20  nce calls to.** 
10550 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67 28  [sqlite3_config(
10560 29 5d 20 77 69 74 68 20 74 68 65 20 53 51 4c 49  )] with the SQLI
10570 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 4d 55 54  TE_CONFIG_GETMUT
10580 45 58 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e  EX configuration
10590 20 6f 70 74 69 6f 6e 20 77 69 6c 6c 0a 2a 2a 20   option will.** 
105a0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 45  return [SQLITE_E
105b0 52 52 4f 52 5d 2e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  RROR].</dd>.**.*
105c0 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e  * <dt>SQLITE_CON
105d0 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 3c 2f 64  FIG_LOOKASIDE</d
105e0 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 28 54 68 69  t>.** <dd> ^(Thi
105f0 73 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 74  s option takes t
10600 77 6f 20 61 72 67 75 6d 65 6e 74 73 20 74 68 61  wo arguments tha
10610 74 20 64 65 74 65 72 6d 69 6e 65 20 74 68 65 20  t determine the 
10620 64 65 66 61 75 6c 74 0a 2a 2a 20 6d 65 6d 6f 72  default.** memor
10630 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 66 6f 72  y allocation for
10640 20 74 68 65 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   the lookaside m
10650 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f 72 20  emory allocator 
10660 6f 6e 20 65 61 63 68 0a 2a 2a 20 5b 64 61 74 61  on each.** [data
10670 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
10680 2e 20 20 54 68 65 20 66 69 72 73 74 20 61 72 67  .  The first arg
10690 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a 20  ument is the.** 
106a0 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f 6f  size of each loo
106b0 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73 6c  kaside buffer sl
106c0 6f 74 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e  ot and the secon
106d0 64 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  d is the number 
106e0 6f 66 0a 2a 2a 20 73 6c 6f 74 73 20 61 6c 6c 6f  of.** slots allo
106f0 63 61 74 65 64 20 74 6f 20 65 61 63 68 20 64 61  cated to each da
10700 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
10710 6e 2e 29 5e 20 20 5e 28 54 68 69 73 20 6f 70 74  n.)^  ^(This opt
10720 69 6f 6e 20 73 65 74 73 20 74 68 65 0a 2a 2a 20  ion sets the.** 
10730 3c 69 3e 64 65 66 61 75 6c 74 3c 2f 69 3e 20 6c  <i>default</i> l
10740 6f 6f 6b 61 73 69 64 65 20 73 69 7a 65 2e 20 54  ookaside size. T
10750 68 65 20 5b 53 51 4c 49 54 45 5f 44 42 43 4f 4e  he [SQLITE_DBCON
10760 46 49 47 5f 4c 4f 4f 4b 41 53 49 44 45 5d 0a 2a  FIG_LOOKASIDE].*
10770 2a 20 76 65 72 62 20 74 6f 20 5b 73 71 6c 69 74  * verb to [sqlit
10780 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29 5d 20  e3_db_config()] 
10790 63 61 6e 20 62 65 20 75 73 65 64 20 74 6f 20 63  can be used to c
107a0 68 61 6e 67 65 20 74 68 65 20 6c 6f 6f 6b 61 73  hange the lookas
107b0 69 64 65 0a 2a 2a 20 63 6f 6e 66 69 67 75 72 61  ide.** configura
107c0 74 69 6f 6e 20 6f 6e 20 69 6e 64 69 76 69 64 75  tion on individu
107d0 61 6c 20 63 6f 6e 6e 65 63 74 69 6f 6e 73 2e 29  al connections.)
107e0 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  ^ </dd>.**.** <d
107f0 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10800 50 43 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c  PCACHE</dt>.** <
10810 64 64 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f  dd> ^(This optio
10820 6e 20 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65  n takes a single
10830 20 61 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20   argument which 
10840 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a  is a pointer to.
10850 2a 2a 20 61 6e 20 5b 73 71 6c 69 74 65 33 5f 70  ** an [sqlite3_p
10860 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f  cache_methods] o
10870 62 6a 65 63 74 2e 20 20 54 68 69 73 20 6f 62 6a  bject.  This obj
10880 65 63 74 20 73 70 65 63 69 66 69 65 73 20 74 68  ect specifies th
10890 65 20 69 6e 74 65 72 66 61 63 65 0a 2a 2a 20 74  e interface.** t
108a0 6f 20 61 20 63 75 73 74 6f 6d 20 70 61 67 65 20  o a custom page 
108b0 63 61 63 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  cache implementa
108c0 74 69 6f 6e 2e 29 5e 20 20 5e 53 51 4c 69 74 65  tion.)^  ^SQLite
108d0 20 6d 61 6b 65 73 20 61 20 63 6f 70 79 20 6f 66   makes a copy of
108e0 20 74 68 65 0a 2a 2a 20 6f 62 6a 65 63 74 20 61   the.** object a
108f0 6e 64 20 75 73 65 73 20 69 74 20 66 6f 72 20 70  nd uses it for p
10900 61 67 65 20 63 61 63 68 65 20 6d 65 6d 6f 72 79  age cache memory
10910 20 61 6c 6c 6f 63 61 74 69 6f 6e 73 2e 3c 2f 64   allocations.</d
10920 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51 4c  d>.**.** <dt>SQL
10930 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45 54 50 43  ITE_CONFIG_GETPC
10940 41 43 48 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  ACHE</dt>.** <dd
10950 3e 20 5e 28 54 68 69 73 20 6f 70 74 69 6f 6e 20  > ^(This option 
10960 74 61 6b 65 73 20 61 20 73 69 6e 67 6c 65 20 61  takes a single a
10970 72 67 75 6d 65 6e 74 20 77 68 69 63 68 20 69 73  rgument which is
10980 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e   a pointer to an
10990 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 63 61  .** [sqlite3_pca
109a0 63 68 65 5f 6d 65 74 68 6f 64 73 5d 20 6f 62 6a  che_methods] obj
109b0 65 63 74 2e 20 20 53 51 4c 69 74 65 20 63 6f 70  ect.  SQLite cop
109c0 69 65 73 20 6f 66 20 74 68 65 20 63 75 72 72 65  ies of the curre
109d0 6e 74 0a 2a 2a 20 70 61 67 65 20 63 61 63 68 65  nt.** page cache
109e0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
109f0 69 6e 74 6f 20 74 68 61 74 20 6f 62 6a 65 63 74  into that object
10a00 2e 29 5e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20  .)^ </dd>.**.** 
10a10 3c 64 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49  <dt>SQLITE_CONFI
10a20 47 5f 4c 4f 47 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  G_LOG</dt>.** <d
10a30 64 3e 20 5e 54 68 65 20 53 51 4c 49 54 45 5f 43  d> ^The SQLITE_C
10a40 4f 4e 46 49 47 5f 4c 4f 47 20 6f 70 74 69 6f 6e  ONFIG_LOG option
10a50 20 74 61 6b 65 73 20 74 77 6f 20 61 72 67 75 6d   takes two argum
10a60 65 6e 74 73 3a 20 61 20 70 6f 69 6e 74 65 72 20  ents: a pointer 
10a70 74 6f 20 61 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e  to a.** function
10a80 20 77 69 74 68 20 61 20 63 61 6c 6c 20 73 69 67   with a call sig
10a90 6e 61 74 75 72 65 20 6f 66 20 76 6f 69 64 28 2a  nature of void(*
10aa0 29 28 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73  )(void*,int,cons
10ab0 74 20 63 68 61 72 2a 29 2c 20 0a 2a 2a 20 61 6e  t char*), .** an
10ac0 64 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 76  d a pointer to v
10ad0 6f 69 64 2e 20 5e 49 66 20 74 68 65 20 66 75 6e  oid. ^If the fun
10ae0 63 74 69 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73  ction pointer is
10af0 20 6e 6f 74 20 4e 55 4c 4c 2c 20 69 74 20 69 73   not NULL, it is
10b00 0a 2a 2a 20 69 6e 76 6f 6b 65 64 20 62 79 20 5b  .** invoked by [
10b10 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20 74  sqlite3_log()] t
10b20 6f 20 70 72 6f 63 65 73 73 20 65 61 63 68 20 6c  o process each l
10b30 6f 67 67 69 6e 67 20 65 76 65 6e 74 2e 20 20 5e  ogging event.  ^
10b40 49 66 20 74 68 65 0a 2a 2a 20 66 75 6e 63 74 69  If the.** functi
10b50 6f 6e 20 70 6f 69 6e 74 65 72 20 69 73 20 4e 55  on pointer is NU
10b60 4c 4c 2c 20 74 68 65 20 5b 73 71 6c 69 74 65 33  LL, the [sqlite3
10b70 5f 6c 6f 67 28 29 5d 20 69 6e 74 65 72 66 61 63  _log()] interfac
10b80 65 20 62 65 63 6f 6d 65 73 20 61 20 6e 6f 2d 6f  e becomes a no-o
10b90 70 2e 0a 2a 2a 20 5e 54 68 65 20 76 6f 69 64 20  p..** ^The void 
10ba0 70 6f 69 6e 74 65 72 20 74 68 61 74 20 69 73 20  pointer that is 
10bb0 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75 6d  the second argum
10bc0 65 6e 74 20 74 6f 20 53 51 4c 49 54 45 5f 43 4f  ent to SQLITE_CO
10bd0 4e 46 49 47 5f 4c 4f 47 20 69 73 0a 2a 2a 20 70  NFIG_LOG is.** p
10be0 61 73 73 65 64 20 74 68 72 6f 75 67 68 20 61 73  assed through as
10bf0 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d   the first param
10c00 65 74 65 72 20 74 6f 20 74 68 65 20 61 70 70 6c  eter to the appl
10c10 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
10c20 6c 6f 67 67 65 72 0a 2a 2a 20 66 75 6e 63 74 69  logger.** functi
10c30 6f 6e 20 77 68 65 6e 65 76 65 72 20 74 68 61 74  on whenever that
10c40 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 69 6e 76   function is inv
10c50 6f 6b 65 64 2e 20 20 5e 54 68 65 20 73 65 63 6f  oked.  ^The seco
10c60 6e 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f 0a  nd parameter to.
10c70 2a 2a 20 74 68 65 20 6c 6f 67 67 65 72 20 66 75  ** the logger fu
10c80 6e 63 74 69 6f 6e 20 69 73 20 61 20 63 6f 70 79  nction is a copy
10c90 20 6f 66 20 74 68 65 20 66 69 72 73 74 20 70 61   of the first pa
10ca0 72 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 63  rameter to the c
10cb0 6f 72 72 65 73 70 6f 6e 64 69 6e 67 0a 2a 2a 20  orresponding.** 
10cc0 5b 73 71 6c 69 74 65 33 5f 6c 6f 67 28 29 5d 20  [sqlite3_log()] 
10cd0 63 61 6c 6c 20 61 6e 64 20 69 73 20 69 6e 74 65  call and is inte
10ce0 6e 64 65 64 20 74 6f 20 62 65 20 61 20 5b 72 65  nded to be a [re
10cf0 73 75 6c 74 20 63 6f 64 65 5d 20 6f 72 20 61 6e  sult code] or an
10d00 0a 2a 2a 20 5b 65 78 74 65 6e 64 65 64 20 72 65  .** [extended re
10d10 73 75 6c 74 20 63 6f 64 65 5d 2e 20 20 5e 54 68  sult code].  ^Th
10d20 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74 65  e third paramete
10d30 72 20 70 61 73 73 65 64 20 74 6f 20 74 68 65 20  r passed to the 
10d40 6c 6f 67 67 65 72 20 69 73 0a 2a 2a 20 6c 6f 67  logger is.** log
10d50 20 6d 65 73 73 61 67 65 20 61 66 74 65 72 20 66   message after f
10d60 6f 72 6d 61 74 74 69 6e 67 20 76 69 61 20 5b 73  ormatting via [s
10d70 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28  qlite3_snprintf(
10d80 29 5d 2e 0a 2a 2a 20 54 68 65 20 53 51 4c 69 74  )]..** The SQLit
10d90 65 20 6c 6f 67 67 69 6e 67 20 69 6e 74 65 72 66  e logging interf
10da0 61 63 65 20 69 73 20 6e 6f 74 20 72 65 65 6e 74  ace is not reent
10db0 72 61 6e 74 3b 20 74 68 65 20 6c 6f 67 67 65 72  rant; the logger
10dc0 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 73 75 70   function.** sup
10dd0 70 6c 69 65 64 20 62 79 20 74 68 65 20 61 70 70  plied by the app
10de0 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
10df0 74 20 69 6e 76 6f 6b 65 20 61 6e 79 20 53 51 4c  t invoke any SQL
10e00 69 74 65 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  ite interface..*
10e10 2a 20 49 6e 20 61 20 6d 75 6c 74 69 2d 74 68 72  * In a multi-thr
10e20 65 61 64 65 64 20 61 70 70 6c 69 63 61 74 69 6f  eaded applicatio
10e30 6e 2c 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  n, the applicati
10e40 6f 6e 2d 64 65 66 69 6e 65 64 20 6c 6f 67 67 65  on-defined logge
10e50 72 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 6d 75  r.** function mu
10e60 73 74 20 62 65 20 74 68 72 65 61 64 73 61 66 65  st be threadsafe
10e70 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64  . </dd>.**.** <d
10e80 74 3e 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  t>SQLITE_CONFIG_
10e90 55 52 49 0a 2a 2a 20 3c 64 64 3e 20 54 68 69 73  URI.** <dd> This
10ea0 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 61 20   option takes a 
10eb0 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74 20  single argument 
10ec0 6f 66 20 74 79 70 65 20 69 6e 74 2e 20 49 66 20  of type int. If 
10ed0 6e 6f 6e 2d 7a 65 72 6f 2c 20 74 68 65 6e 0a 2a  non-zero, then.*
10ee0 2a 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 20 69  * URI handling i
10ef0 73 20 67 6c 6f 62 61 6c 6c 79 20 65 6e 61 62 6c  s globally enabl
10f00 65 64 2e 20 49 66 20 74 68 65 20 70 61 72 61 6d  ed. If the param
10f10 65 74 65 72 20 69 73 20 7a 65 72 6f 2c 20 74 68  eter is zero, th
10f20 65 6e 20 55 52 49 20 68 61 6e 64 6c 69 6e 67 0a  en URI handling.
10f30 2a 2a 20 69 73 20 67 6c 6f 62 61 6c 6c 79 20 64  ** is globally d
10f40 69 73 61 62 6c 65 64 2e 20 49 66 20 55 52 49 20  isabled. If URI 
10f50 68 61 6e 64 6c 69 6e 67 20 69 73 20 67 6c 6f 62  handling is glob
10f60 61 6c 6c 79 20 65 6e 61 62 6c 65 64 2c 20 61 6c  ally enabled, al
10f70 6c 20 66 69 6c 65 6e 61 6d 65 73 0a 2a 2a 20 70  l filenames.** p
10f80 61 73 73 65 64 20 74 6f 20 5b 73 71 6c 69 74 65  assed to [sqlite
10f90 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
10fa0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 2c 20  te3_open_v2()], 
10fb0 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28  [sqlite3_open16(
10fc0 29 5d 20 6f 72 0a 2a 2a 20 73 70 65 63 69 66 69  )] or.** specifi
10fd0 65 64 20 61 73 20 70 61 72 74 20 6f 66 20 5b 41  ed as part of [A
10fe0 54 54 41 43 48 5d 20 63 6f 6d 6d 61 6e 64 73 20  TTACH] commands 
10ff0 61 72 65 20 69 6e 74 65 72 70 72 65 74 65 64 20  are interpreted 
11000 61 73 20 55 52 49 73 2c 20 72 65 67 61 72 64 6c  as URIs, regardl
11010 65 73 73 0a 2a 2a 20 6f 66 20 77 68 65 74 68 65  ess.** of whethe
11020 72 20 6f 72 20 6e 6f 74 20 74 68 65 20 5b 53 51  r or not the [SQ
11030 4c 49 54 45 5f 4f 50 45 4e 5f 55 52 49 5d 20 66  LITE_OPEN_URI] f
11040 6c 61 67 20 69 73 20 73 65 74 20 77 68 65 6e 20  lag is set when 
11050 74 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  the database.** 
11060 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 70  connection is op
11070 65 6e 65 64 2e 20 49 66 20 69 74 20 69 73 20 67  ened. If it is g
11080 6c 6f 62 61 6c 6c 79 20 64 69 73 61 62 6c 65 64  lobally disabled
11090 2c 20 66 69 6c 65 6e 61 6d 65 73 20 61 72 65 0a  , filenames are.
110a0 2a 2a 20 6f 6e 6c 79 20 69 6e 74 65 72 70 72 65  ** only interpre
110b0 74 65 64 20 61 73 20 55 52 49 73 20 69 66 20 74  ted as URIs if t
110c0 68 65 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 55  he SQLITE_OPEN_U
110d0 52 49 20 66 6c 61 67 20 69 73 20 73 65 74 20 77  RI flag is set w
110e0 68 65 6e 20 74 68 65 0a 2a 2a 20 64 61 74 61 62  hen the.** datab
110f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
11100 73 20 6f 70 65 6e 65 64 2e 20 42 79 20 64 65 66  s opened. By def
11110 61 75 6c 74 2c 20 55 52 49 20 68 61 6e 64 6c 69  ault, URI handli
11120 6e 67 20 69 73 20 67 6c 6f 62 61 6c 6c 79 0a 2a  ng is globally.*
11130 2a 20 64 69 73 61 62 6c 65 64 2e 20 54 68 65 20  * disabled. The 
11140 64 65 66 61 75 6c 74 20 76 61 6c 75 65 20 6d 61  default value ma
11150 79 20 62 65 20 63 68 61 6e 67 65 64 20 62 79 20  y be changed by 
11160 63 6f 6d 70 69 6c 69 6e 67 20 77 69 74 68 20 74  compiling with t
11170 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 55 53  he.** [SQLITE_US
11180 45 5f 55 52 49 5d 20 73 79 6d 62 6f 6c 20 64 65  E_URI] symbol de
11190 66 69 6e 65 64 2e 0a 2a 2a 20 3c 2f 64 6c 3e 0a  fined..** </dl>.
111a0 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
111b0 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
111c0 48 52 45 41 44 20 20 31 20 20 2f 2a 20 6e 69 6c  HREAD  1  /* nil
111d0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
111e0 54 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54  TE_CONFIG_MULTIT
111f0 48 52 45 41 44 20 20 20 32 20 20 2f 2a 20 6e 69  HREAD   2  /* ni
11200 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  l */.#define SQL
11210 49 54 45 5f 43 4f 4e 46 49 47 5f 53 45 52 49 41  ITE_CONFIG_SERIA
11220 4c 49 5a 45 44 20 20 20 20 33 20 20 2f 2a 20 6e  LIZED    3  /* n
11230 69 6c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  il */.#define SQ
11240 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 41 4c 4c  LITE_CONFIG_MALL
11250 4f 43 20 20 20 20 20 20 20 20 34 20 20 2f 2a 20  OC        4  /* 
11260 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65 74 68  sqlite3_mem_meth
11270 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ods* */.#define 
11280 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 47 45  SQLITE_CONFIG_GE
11290 54 4d 41 4c 4c 4f 43 20 20 20 20 20 35 20 20 2f  TMALLOC     5  /
112a0 2a 20 73 71 6c 69 74 65 33 5f 6d 65 6d 5f 6d 65  * sqlite3_mem_me
112b0 74 68 6f 64 73 2a 20 2a 2f 0a 23 64 65 66 69 6e  thods* */.#defin
112c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
112d0 53 43 52 41 54 43 48 20 20 20 20 20 20 20 36 20  SCRATCH       6 
112e0 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74 20 73   /* void*, int s
112f0 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64 65 66  z, int N */.#def
11300 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49  ine SQLITE_CONFI
11310 47 5f 50 41 47 45 43 41 43 48 45 20 20 20 20 20  G_PAGECACHE     
11320 37 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69 6e 74  7  /* void*, int
11330 20 73 7a 2c 20 69 6e 74 20 4e 20 2a 2f 0a 23 64   sz, int N */.#d
11340 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11350 46 49 47 5f 48 45 41 50 20 20 20 20 20 20 20 20  FIG_HEAP        
11360 20 20 38 20 20 2f 2a 20 76 6f 69 64 2a 2c 20 69    8  /* void*, i
11370 6e 74 20 6e 42 79 74 65 2c 20 69 6e 74 20 6d 69  nt nByte, int mi
11380 6e 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  n */.#define SQL
11390 49 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54  ITE_CONFIG_MEMST
113a0 41 54 55 53 20 20 20 20 20 39 20 20 2f 2a 20 62  ATUS     9  /* b
113b0 6f 6f 6c 65 61 6e 20 2a 2f 0a 23 64 65 66 69 6e  oolean */.#defin
113c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
113d0 4d 55 54 45 58 20 20 20 20 20 20 20 20 31 30 20  MUTEX        10 
113e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 6d 75 74 65   /* sqlite3_mute
113f0 78 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23 64  x_methods* */.#d
11400 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11410 46 49 47 5f 47 45 54 4d 55 54 45 58 20 20 20 20  FIG_GETMUTEX    
11420 20 31 31 20 20 2f 2a 20 73 71 6c 69 74 65 33 5f   11  /* sqlite3_
11430 6d 75 74 65 78 5f 6d 65 74 68 6f 64 73 2a 20 2a  mutex_methods* *
11440 2f 0a 2f 2a 20 70 72 65 76 69 6f 75 73 6c 79 20  /./* previously 
11450 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f 43 48  SQLITE_CONFIG_CH
11460 55 4e 4b 41 4c 4c 4f 43 20 31 32 20 77 68 69 63  UNKALLOC 12 whic
11470 68 20 69 73 20 6e 6f 77 20 75 6e 75 73 65 64 2e  h is now unused.
11480 20 2a 2f 20 0a 23 64 65 66 69 6e 65 20 53 51 4c   */ .#define SQL
11490 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
114a0 53 49 44 45 20 20 20 20 31 33 20 20 2f 2a 20 69  SIDE    13  /* i
114b0 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66 69 6e  nt int */.#defin
114c0 65 20 53 51 4c 49 54 45 5f 43 4f 4e 46 49 47 5f  e SQLITE_CONFIG_
114d0 50 43 41 43 48 45 20 20 20 20 20 20 20 31 34 20  PCACHE       14 
114e0 20 2f 2a 20 73 71 6c 69 74 65 33 5f 70 63 61 63   /* sqlite3_pcac
114f0 68 65 5f 6d 65 74 68 6f 64 73 2a 20 2a 2f 0a 23  he_methods* */.#
11500 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f  define SQLITE_CO
11510 4e 46 49 47 5f 47 45 54 50 43 41 43 48 45 20 20  NFIG_GETPCACHE  
11520 20 20 31 35 20 20 2f 2a 20 73 71 6c 69 74 65 33    15  /* sqlite3
11530 5f 70 63 61 63 68 65 5f 6d 65 74 68 6f 64 73 2a  _pcache_methods*
11540 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
11550 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 47 20 20 20  TE_CONFIG_LOG   
11560 20 20 20 20 20 20 20 31 36 20 20 2f 2a 20 78 46         16  /* xF
11570 75 6e 63 2c 20 76 6f 69 64 2a 20 2a 2f 0a 23 64  unc, void* */.#d
11580 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 43 4f 4e  efine SQLITE_CON
11590 46 49 47 5f 55 52 49 20 20 20 20 20 20 20 20 20  FIG_URI         
115a0 20 31 37 20 20 2f 2a 20 69 6e 74 20 2a 2f 0a 0a   17  /* int */..
115b0 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20  /*.** CAPI3REF: 
115c0 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63 74  Database Connect
115d0 69 6f 6e 20 43 6f 6e 66 69 67 75 72 61 74 69 6f  ion Configuratio
115e0 6e 20 4f 70 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20  n Options.**.** 
115f0 54 68 65 73 65 20 63 6f 6e 73 74 61 6e 74 73 20  These constants 
11600 61 72 65 20 74 68 65 20 61 76 61 69 6c 61 62 6c  are the availabl
11610 65 20 69 6e 74 65 67 65 72 20 63 6f 6e 66 69 67  e integer config
11620 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e 73 20  uration options 
11630 74 68 61 74 0a 2a 2a 20 63 61 6e 20 62 65 20 70  that.** can be p
11640 61 73 73 65 64 20 61 73 20 74 68 65 20 73 65 63  assed as the sec
11650 6f 6e 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 20  ond argument to 
11660 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f  the [sqlite3_db_
11670 63 6f 6e 66 69 67 28 29 5d 20 69 6e 74 65 72 66  config()] interf
11680 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 4e 65 77 20 63  ace..**.** New c
11690 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 70 74  onfiguration opt
116a0 69 6f 6e 73 20 6d 61 79 20 62 65 20 61 64 64 65  ions may be adde
116b0 64 20 69 6e 20 66 75 74 75 72 65 20 72 65 6c 65  d in future rele
116c0 61 73 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 0a  ases of SQLite..
116d0 2a 2a 20 45 78 69 73 74 69 6e 67 20 63 6f 6e 66  ** Existing conf
116e0 69 67 75 72 61 74 69 6f 6e 20 6f 70 74 69 6f 6e  iguration option
116f0 73 20 6d 69 67 68 74 20 62 65 20 64 69 73 63 6f  s might be disco
11700 6e 74 69 6e 75 65 64 2e 20 20 41 70 70 6c 69 63  ntinued.  Applic
11710 61 74 69 6f 6e 73 0a 2a 2a 20 73 68 6f 75 6c 64  ations.** should
11720 20 63 68 65 63 6b 20 74 68 65 20 72 65 74 75 72   check the retur
11730 6e 20 63 6f 64 65 20 66 72 6f 6d 20 5b 73 71 6c  n code from [sql
11740 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67 28 29  ite3_db_config()
11750 5d 20 74 6f 20 6d 61 6b 65 20 73 75 72 65 20 74  ] to make sure t
11760 68 61 74 0a 2a 2a 20 74 68 65 20 63 61 6c 6c 20  hat.** the call 
11770 77 6f 72 6b 65 64 2e 20 20 5e 54 68 65 20 5b 73  worked.  ^The [s
11780 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e 66 69 67  qlite3_db_config
11790 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 77 69  ()] interface wi
117a0 6c 6c 20 72 65 74 75 72 6e 20 61 0a 2a 2a 20 6e  ll return a.** n
117b0 6f 6e 2d 7a 65 72 6f 20 5b 65 72 72 6f 72 20 63  on-zero [error c
117c0 6f 64 65 5d 20 69 66 20 61 20 64 69 73 63 6f 6e  ode] if a discon
117d0 74 69 6e 75 65 64 20 6f 72 20 75 6e 73 75 70 70  tinued or unsupp
117e0 6f 72 74 65 64 20 63 6f 6e 66 69 67 75 72 61 74  orted configurat
117f0 69 6f 6e 20 6f 70 74 69 6f 6e 0a 2a 2a 20 69 73  ion option.** is
11800 20 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20   invoked..**.** 
11810 3c 64 6c 3e 0a 2a 2a 20 3c 64 74 3e 53 51 4c 49  <dl>.** <dt>SQLI
11820 54 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b  TE_DBCONFIG_LOOK
11830 41 53 49 44 45 3c 2f 64 74 3e 0a 2a 2a 20 3c 64  ASIDE</dt>.** <d
11840 64 3e 20 5e 54 68 69 73 20 6f 70 74 69 6f 6e 20  d> ^This option 
11850 74 61 6b 65 73 20 74 68 72 65 65 20 61 64 64 69  takes three addi
11860 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65 6e 74 73  tional arguments
11870 20 74 68 61 74 20 64 65 74 65 72 6d 69 6e 65 20   that determine 
11880 74 68 65 20 0a 2a 2a 20 5b 6c 6f 6f 6b 61 73 69  the .** [lookasi
11890 64 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  de memory alloca
118a0 74 6f 72 5d 20 63 6f 6e 66 69 67 75 72 61 74 69  tor] configurati
118b0 6f 6e 20 66 6f 72 20 74 68 65 20 5b 64 61 74 61  on for the [data
118c0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
118d0 2e 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20  ..** ^The first 
118e0 61 72 67 75 6d 65 6e 74 20 28 74 68 65 20 74 68  argument (the th
118f0 69 72 64 20 70 61 72 61 6d 65 74 65 72 20 74 6f  ird parameter to
11900 20 5b 73 71 6c 69 74 65 33 5f 64 62 5f 63 6f 6e   [sqlite3_db_con
11910 66 69 67 28 29 5d 20 69 73 20 61 0a 2a 2a 20 70  fig()] is a.** p
11920 6f 69 6e 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f  ointer to a memo
11930 72 79 20 62 75 66 66 65 72 20 74 6f 20 75 73 65  ry buffer to use
11940 20 66 6f 72 20 6c 6f 6f 6b 61 73 69 64 65 20 6d   for lookaside m
11950 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 54 68 65 20 66  emory..** ^The f
11960 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 61 66  irst argument af
11970 74 65 72 20 74 68 65 20 53 51 4c 49 54 45 5f 44  ter the SQLITE_D
11980 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41 53 49 44  BCONFIG_LOOKASID
11990 45 20 76 65 72 62 0a 2a 2a 20 6d 61 79 20 62 65  E verb.** may be
119a0 20 4e 55 4c 4c 20 69 6e 20 77 68 69 63 68 20 63   NULL in which c
119b0 61 73 65 20 53 51 4c 69 74 65 20 77 69 6c 6c 20  ase SQLite will 
119c0 61 6c 6c 6f 63 61 74 65 20 74 68 65 0a 2a 2a 20  allocate the.** 
119d0 6c 6f 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72  lookaside buffer
119e0 20 69 74 73 65 6c 66 20 75 73 69 6e 67 20 5b 73   itself using [s
119f0 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d  qlite3_malloc()]
11a00 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72  . ^The second ar
11a10 67 75 6d 65 6e 74 20 69 73 20 74 68 65 0a 2a 2a  gument is the.**
11a20 20 73 69 7a 65 20 6f 66 20 65 61 63 68 20 6c 6f   size of each lo
11a30 6f 6b 61 73 69 64 65 20 62 75 66 66 65 72 20 73  okaside buffer s
11a40 6c 6f 74 2e 20 20 5e 54 68 65 20 74 68 69 72 64  lot.  ^The third
11a50 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
11a60 20 6e 75 6d 62 65 72 20 6f 66 0a 2a 2a 20 73 6c   number of.** sl
11a70 6f 74 73 2e 20 20 54 68 65 20 73 69 7a 65 20 6f  ots.  The size o
11a80 66 20 74 68 65 20 62 75 66 66 65 72 20 69 6e 20  f the buffer in 
11a90 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  the first argume
11aa0 6e 74 20 6d 75 73 74 20 62 65 20 67 72 65 61 74  nt must be great
11ab0 65 72 20 74 68 61 6e 0a 2a 2a 20 6f 72 20 65 71  er than.** or eq
11ac0 75 61 6c 20 74 6f 20 74 68 65 20 70 72 6f 64 75  ual to the produ
11ad0 63 74 20 6f 66 20 74 68 65 20 73 65 63 6f 6e 64  ct of the second
11ae0 20 61 6e 64 20 74 68 69 72 64 20 61 72 67 75 6d   and third argum
11af0 65 6e 74 73 2e 20 20 54 68 65 20 62 75 66 66 65  ents.  The buffe
11b00 72 0a 2a 2a 20 6d 75 73 74 20 62 65 20 61 6c 69  r.** must be ali
11b10 67 6e 65 64 20 74 6f 20 61 6e 20 38 2d 62 79 74  gned to an 8-byt
11b20 65 20 62 6f 75 6e 64 61 72 79 2e 20 20 5e 49 66  e boundary.  ^If
11b30 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
11b40 6d 65 6e 74 20 74 6f 0a 2a 2a 20 53 51 4c 49 54  ment to.** SQLIT
11b50 45 5f 44 42 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  E_DBCONFIG_LOOKA
11b60 53 49 44 45 20 69 73 20 6e 6f 74 20 61 20 6d 75  SIDE is not a mu
11b70 6c 74 69 70 6c 65 20 6f 66 20 38 2c 20 69 74 20  ltiple of 8, it 
11b80 69 73 20 69 6e 74 65 72 6e 61 6c 6c 79 0a 2a 2a  is internally.**
11b90 20 72 6f 75 6e 64 65 64 20 64 6f 77 6e 20 74 6f   rounded down to
11ba0 20 74 68 65 20 6e 65 78 74 20 73 6d 61 6c 6c 65   the next smalle
11bb0 72 20 6d 75 6c 74 69 70 6c 65 20 6f 66 20 38 2e  r multiple of 8.
11bc0 20 20 5e 28 54 68 65 20 6c 6f 6f 6b 61 73 69 64    ^(The lookasid
11bd0 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20 63 6f 6e 66  e memory.** conf
11be0 69 67 75 72 61 74 69 6f 6e 20 66 6f 72 20 61 20  iguration for a 
11bf0 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
11c00 69 6f 6e 20 63 61 6e 20 6f 6e 6c 79 20 62 65 20  ion can only be 
11c10 63 68 61 6e 67 65 64 20 77 68 65 6e 20 74 68 61  changed when tha
11c20 74 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  t.** connection 
11c30 69 73 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79  is not currently
11c40 20 75 73 69 6e 67 20 6c 6f 6f 6b 61 73 69 64 65   using lookaside
11c50 20 6d 65 6d 6f 72 79 2c 20 6f 72 20 69 6e 20 6f   memory, or in o
11c60 74 68 65 72 20 77 6f 72 64 73 0a 2a 2a 20 77 68  ther words.** wh
11c70 65 6e 20 74 68 65 20 22 63 75 72 72 65 6e 74 20  en the "current 
11c80 76 61 6c 75 65 22 20 72 65 74 75 72 6e 65 64 20  value" returned 
11c90 62 79 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 64  by.** [sqlite3_d
11ca0 62 5f 73 74 61 74 75 73 5d 28 44 2c 5b 53 51 4c  b_status](D,[SQL
11cb0 49 54 45 5f 43 4f 4e 46 49 47 5f 4c 4f 4f 4b 41  ITE_CONFIG_LOOKA
11cc0 53 49 44 45 5d 2c 2e 2e 2e 29 20 69 73 20 7a 65  SIDE],...) is ze
11cd0 72 6f 2e 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d  ro..** Any attem
11ce0 70 74 20 74 6f 20 63 68 61 6e 67 65 20 74 68 65  pt to change the
11cf0 20 6c 6f 6f 6b 61 73 69 64 65 20 6d 65 6d 6f 72   lookaside memor
11d00 79 20 63 6f 6e 66 69 67 75 72 61 74 69 6f 6e 20  y configuration 
11d10 77 68 65 6e 20 6c 6f 6f 6b 61 73 69 64 65 0a 2a  when lookaside.*
11d20 2a 20 6d 65 6d 6f 72 79 20 69 73 20 69 6e 20 75  * memory is in u
11d30 73 65 20 6c 65 61 76 65 73 20 74 68 65 20 63 6f  se leaves the co
11d40 6e 66 69 67 75 72 61 74 69 6f 6e 20 75 6e 63 68  nfiguration unch
11d50 61 6e 67 65 64 20 61 6e 64 20 72 65 74 75 72 6e  anged and return
11d60 73 20 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42 55  s .** [SQLITE_BU
11d70 53 59 5d 2e 29 5e 3c 2f 64 64 3e 0a 2a 2a 0a 2a  SY].)^</dd>.**.*
11d80 2a 20 3c 64 74 3e 53 51 4c 49 54 45 5f 44 42 43  * <dt>SQLITE_DBC
11d90 4f 4e 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45  ONFIG_ENABLE_FKE
11da0 59 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 20 5e  Y</dt>.** <dd> ^
11db0 54 68 69 73 20 6f 70 74 69 6f 6e 20 69 73 20 75  This option is u
11dc0 73 65 64 20 74 6f 20 65 6e 61 62 6c 65 20 6f 72  sed to enable or
11dd0 20 64 69 73 61 62 6c 65 20 74 68 65 20 65 6e 66   disable the enf
11de0 6f 72 63 65 6d 65 6e 74 20 6f 66 0a 2a 2a 20 5b  orcement of.** [
11df0 66 6f 72 65 69 67 6e 20 6b 65 79 20 63 6f 6e 73  foreign key cons
11e00 74 72 61 69 6e 74 73 5d 2e 20 20 54 68 65 72 65  traints].  There
11e10 20 73 68 6f 75 6c 64 20 62 65 20 74 77 6f 20 61   should be two a
11e20 64 64 69 74 69 6f 6e 61 6c 20 61 72 67 75 6d 65  dditional argume
11e30 6e 74 73 2e 0a 2a 2a 20 54 68 65 20 66 69 72 73  nts..** The firs
11e40 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20 61 6e  t argument is an
11e50 20 69 6e 74 65 67 65 72 20 77 68 69 63 68 20 69   integer which i
11e60 73 20 30 20 74 6f 20 64 69 73 61 62 6c 65 20 46  s 0 to disable F
11e70 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 2c 0a 2a  K enforcement,.*
11e80 2a 20 70 6f 73 69 74 69 76 65 20 74 6f 20 65 6e  * positive to en
11e90 61 62 6c 65 20 46 4b 20 65 6e 66 6f 72 63 65 6d  able FK enforcem
11ea0 65 6e 74 20 6f 72 20 6e 65 67 61 74 69 76 65 20  ent or negative 
11eb0 74 6f 20 6c 65 61 76 65 20 46 4b 20 65 6e 66 6f  to leave FK enfo
11ec0 72 63 65 6d 65 6e 74 0a 2a 2a 20 75 6e 63 68 61  rcement.** uncha
11ed0 6e 67 65 64 2e 20 20 54 68 65 20 73 65 63 6f 6e  nged.  The secon
11ee0 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61  d parameter is a
11ef0 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 69   pointer to an i
11f00 6e 74 65 67 65 72 20 69 6e 74 6f 20 77 68 69 63  nteger into whic
11f10 68 0a 2a 2a 20 69 73 20 77 72 69 74 74 65 6e 20  h.** is written 
11f20 30 20 6f 72 20 31 20 74 6f 20 69 6e 64 69 63 61  0 or 1 to indica
11f30 74 65 20 77 68 65 74 68 65 72 20 46 4b 20 65 6e  te whether FK en
11f40 66 6f 72 63 65 6d 65 6e 74 20 69 73 20 6f 66 66  forcement is off
11f50 20 6f 72 20 6f 6e 0a 2a 2a 20 66 6f 6c 6c 6f 77   or on.** follow
11f60 69 6e 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20  ing this call.  
11f70 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
11f80 65 74 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55  eter may be a NU
11f90 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a  LL pointer, in.*
11fa0 2a 20 77 68 69 63 68 20 63 61 73 65 20 74 68 65  * which case the
11fb0 20 46 4b 20 65 6e 66 6f 72 63 65 6d 65 6e 74 20   FK enforcement 
11fc0 73 65 74 74 69 6e 67 20 69 73 20 6e 6f 74 20 72  setting is not r
11fd0 65 70 6f 72 74 65 64 20 62 61 63 6b 2e 20 3c 2f  eported back. </
11fe0 64 64 3e 0a 2a 2a 0a 2a 2a 20 3c 64 74 3e 53 51  dd>.**.** <dt>SQ
11ff0 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47 5f 45 4e  LITE_DBCONFIG_EN
12000 41 42 4c 45 5f 54 52 49 47 47 45 52 3c 2f 64 74  ABLE_TRIGGER</dt
12010 3e 0a 2a 2a 20 3c 64 64 3e 20 5e 54 68 69 73 20  >.** <dd> ^This 
12020 6f 70 74 69 6f 6e 20 69 73 20 75 73 65 64 20 74  option is used t
12030 6f 20 65 6e 61 62 6c 65 20 6f 72 20 64 69 73 61  o enable or disa
12040 62 6c 65 20 5b 43 52 45 41 54 45 20 54 52 49 47  ble [CREATE TRIG
12050 47 45 52 20 7c 20 74 72 69 67 67 65 72 73 5d 2e  GER | triggers].
12060 0a 2a 2a 20 54 68 65 72 65 20 73 68 6f 75 6c 64  .** There should
12070 20 62 65 20 74 77 6f 20 61 64 64 69 74 69 6f 6e   be two addition
12080 61 6c 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  al arguments..**
12090 20 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   The first argum
120a0 65 6e 74 20 69 73 20 61 6e 20 69 6e 74 65 67 65  ent is an intege
120b0 72 20 77 68 69 63 68 20 69 73 20 30 20 74 6f 20  r which is 0 to 
120c0 64 69 73 61 62 6c 65 20 74 72 69 67 67 65 72 73  disable triggers
120d0 2c 0a 2a 2a 20 70 6f 73 69 74 69 76 65 20 74 6f  ,.** positive to
120e0 20 65 6e 61 62 6c 65 20 74 72 69 67 67 65 72 73   enable triggers
120f0 20 6f 72 20 6e 65 67 61 74 69 76 65 20 74 6f 20   or negative to 
12100 6c 65 61 76 65 20 74 68 65 20 73 65 74 74 69 6e  leave the settin
12110 67 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20  g unchanged..** 
12120 54 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  The second param
12130 65 74 65 72 20 69 73 20 61 20 70 6f 69 6e 74 65  eter is a pointe
12140 72 20 74 6f 20 61 6e 20 69 6e 74 65 67 65 72 20  r to an integer 
12150 69 6e 74 6f 20 77 68 69 63 68 0a 2a 2a 20 69 73  into which.** is
12160 20 77 72 69 74 74 65 6e 20 30 20 6f 72 20 31 20   written 0 or 1 
12170 74 6f 20 69 6e 64 69 63 61 74 65 20 77 68 65 74  to indicate whet
12180 68 65 72 20 74 72 69 67 67 65 72 73 20 61 72 65  her triggers are
12190 20 64 69 73 61 62 6c 65 64 20 6f 72 20 65 6e 61   disabled or ena
121a0 62 6c 65 64 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  bled.** followin
121b0 67 20 74 68 69 73 20 63 61 6c 6c 2e 20 20 54 68  g this call.  Th
121c0 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
121d0 65 72 20 6d 61 79 20 62 65 20 61 20 4e 55 4c 4c  er may be a NULL
121e0 20 70 6f 69 6e 74 65 72 2c 20 69 6e 0a 2a 2a 20   pointer, in.** 
121f0 77 68 69 63 68 20 63 61 73 65 20 74 68 65 20 74  which case the t
12200 72 69 67 67 65 72 20 73 65 74 74 69 6e 67 20 69  rigger setting i
12210 73 20 6e 6f 74 20 72 65 70 6f 72 74 65 64 20 62  s not reported b
12220 61 63 6b 2e 20 3c 2f 64 64 3e 0a 2a 2a 0a 2a 2a  ack. </dd>.**.**
12230 20 3c 2f 64 6c 3e 0a 2a 2f 0a 23 64 65 66 69 6e   </dl>.*/.#defin
12240 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49  e SQLITE_DBCONFI
12250 47 5f 4c 4f 4f 4b 41 53 49 44 45 20 20 20 20 20  G_LOOKASIDE     
12260 20 20 31 30 30 31 20 20 2f 2a 20 76 6f 69 64 2a    1001  /* void*
12270 20 69 6e 74 20 69 6e 74 20 2a 2f 0a 23 64 65 66   int int */.#def
12280 69 6e 65 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e  ine SQLITE_DBCON
12290 46 49 47 5f 45 4e 41 42 4c 45 5f 46 4b 45 59 20  FIG_ENABLE_FKEY 
122a0 20 20 20 20 31 30 30 32 20 20 2f 2a 20 69 6e 74      1002  /* int
122b0 20 69 6e 74 2a 20 2a 2f 0a 23 64 65 66 69 6e 65   int* */.#define
122c0 20 53 51 4c 49 54 45 5f 44 42 43 4f 4e 46 49 47   SQLITE_DBCONFIG
122d0 5f 45 4e 41 42 4c 45 5f 54 52 49 47 47 45 52 20  _ENABLE_TRIGGER 
122e0 20 31 30 30 33 20 20 2f 2a 20 69 6e 74 20 69 6e   1003  /* int in
122f0 74 2a 20 2a 2f 0a 0a 0a 2f 2a 0a 2a 2a 20 43 41  t* */.../*.** CA
12300 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f  PI3REF: Enable O
12310 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e 64  r Disable Extend
12320 65 64 20 52 65 73 75 6c 74 20 43 6f 64 65 73 0a  ed Result Codes.
12330 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
12340 65 33 5f 65 78 74 65 6e 64 65 64 5f 72 65 73 75  e3_extended_resu
12350 6c 74 5f 63 6f 64 65 73 28 29 20 72 6f 75 74 69  lt_codes() routi
12360 6e 65 20 65 6e 61 62 6c 65 73 20 6f 72 20 64 69  ne enables or di
12370 73 61 62 6c 65 73 20 74 68 65 0a 2a 2a 20 5b 65  sables the.** [e
12380 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74 20 63  xtended result c
12390 6f 64 65 73 5d 20 66 65 61 74 75 72 65 20 6f 66  odes] feature of
123a0 20 53 51 4c 69 74 65 2e 20 5e 54 68 65 20 65 78   SQLite. ^The ex
123b0 74 65 6e 64 65 64 20 72 65 73 75 6c 74 0a 2a 2a  tended result.**
123c0 20 63 6f 64 65 73 20 61 72 65 20 64 69 73 61 62   codes are disab
123d0 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74 20 66  led by default f
123e0 6f 72 20 68 69 73 74 6f 72 69 63 61 6c 20 63 6f  or historical co
123f0 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a 2a 2f 0a  mpatibility..*/.
12400 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74 65  int sqlite3_exte
12410 6e 64 65 64 5f 72 65 73 75 6c 74 5f 63 6f 64 65  nded_result_code
12420 73 28 73 71 6c 69 74 65 33 2a 2c 20 69 6e 74 20  s(sqlite3*, int 
12430 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  onoff);../*.** C
12440 41 50 49 33 52 45 46 3a 20 4c 61 73 74 20 49 6e  API3REF: Last In
12450 73 65 72 74 20 52 6f 77 69 64 0a 2a 2a 0a 2a 2a  sert Rowid.**.**
12460 20 5e 45 61 63 68 20 65 6e 74 72 79 20 69 6e 20   ^Each entry in 
12470 61 6e 20 53 51 4c 69 74 65 20 74 61 62 6c 65 20  an SQLite table 
12480 68 61 73 20 61 20 75 6e 69 71 75 65 20 36 34 2d  has a unique 64-
12490 62 69 74 20 73 69 67 6e 65 64 0a 2a 2a 20 69 6e  bit signed.** in
124a0 74 65 67 65 72 20 6b 65 79 20 63 61 6c 6c 65 64  teger key called
124b0 20 74 68 65 20 5b 52 4f 57 49 44 20 7c 20 22 72   the [ROWID | "r
124c0 6f 77 69 64 22 5d 2e 20 5e 54 68 65 20 72 6f 77  owid"]. ^The row
124d0 69 64 20 69 73 20 61 6c 77 61 79 73 20 61 76 61  id is always ava
124e0 69 6c 61 62 6c 65 0a 2a 2a 20 61 73 20 61 6e 20  ilable.** as an 
124f0 75 6e 64 65 63 6c 61 72 65 64 20 63 6f 6c 75 6d  undeclared colum
12500 6e 20 6e 61 6d 65 64 20 52 4f 57 49 44 2c 20 4f  n named ROWID, O
12510 49 44 2c 20 6f 72 20 5f 52 4f 57 49 44 5f 20 61  ID, or _ROWID_ a
12520 73 20 6c 6f 6e 67 20 61 73 20 74 68 6f 73 65 0a  s long as those.
12530 2a 2a 20 6e 61 6d 65 73 20 61 72 65 20 6e 6f 74  ** names are not
12540 20 61 6c 73 6f 20 75 73 65 64 20 62 79 20 65 78   also used by ex
12550 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72 65  plicitly declare
12560 64 20 63 6f 6c 75 6d 6e 73 2e 20 5e 49 66 0a 2a  d columns. ^If.*
12570 2a 20 74 68 65 20 74 61 62 6c 65 20 68 61 73 20  * the table has 
12580 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 79 70 65  a column of type
12590 20 5b 49 4e 54 45 47 45 52 20 50 52 49 4d 41 52   [INTEGER PRIMAR
125a0 59 20 4b 45 59 5d 20 74 68 65 6e 20 74 68 61 74  Y KEY] then that
125b0 20 63 6f 6c 75 6d 6e 0a 2a 2a 20 69 73 20 61 6e   column.** is an
125c0 6f 74 68 65 72 20 61 6c 69 61 73 20 66 6f 72 20  other alias for 
125d0 74 68 65 20 72 6f 77 69 64 2e 0a 2a 2a 0a 2a 2a  the rowid..**.**
125e0 20 5e 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72   ^This routine r
125f0 65 74 75 72 6e 73 20 74 68 65 20 5b 72 6f 77 69  eturns the [rowi
12600 64 5d 20 6f 66 20 74 68 65 20 6d 6f 73 74 20 72  d] of the most r
12610 65 63 65 6e 74 0a 2a 2a 20 73 75 63 63 65 73 73  ecent.** success
12620 66 75 6c 20 5b 49 4e 53 45 52 54 5d 20 69 6e 74  ful [INSERT] int
12630 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20 66  o the database f
12640 72 6f 6d 20 74 68 65 20 5b 64 61 74 61 62 61 73  rom the [databas
12650 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a  e connection].**
12660 20 69 6e 20 74 68 65 20 66 69 72 73 74 20 61 72   in the first ar
12670 67 75 6d 65 6e 74 2e 20 20 5e 49 66 20 6e 6f 20  gument.  ^If no 
12680 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e 53 45  successful [INSE
12690 52 54 5d 73 0a 2a 2a 20 68 61 76 65 20 65 76 65  RT]s.** have eve
126a0 72 20 6f 63 63 75 72 72 65 64 20 6f 6e 20 74 68  r occurred on th
126b0 61 74 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  at database conn
126c0 65 63 74 69 6f 6e 2c 20 7a 65 72 6f 20 69 73 20  ection, zero is 
126d0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20  returned..**.** 
126e0 5e 28 49 66 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ^(If an [INSERT]
126f0 20 6f 63 63 75 72 73 20 77 69 74 68 69 6e 20 61   occurs within a
12700 20 74 72 69 67 67 65 72 2c 20 74 68 65 6e 20 74   trigger, then t
12710 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74 68  he [rowid] of th
12720 65 20 69 6e 73 65 72 74 65 64 0a 2a 2a 20 72 6f  e inserted.** ro
12730 77 20 69 73 20 72 65 74 75 72 6e 65 64 20 62 79  w is returned by
12740 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20 61 73   this routine as
12750 20 6c 6f 6e 67 20 61 73 20 74 68 65 20 74 72 69   long as the tri
12760 67 67 65 72 20 69 73 20 72 75 6e 6e 69 6e 67 2e  gger is running.
12770 0a 2a 2a 20 42 75 74 20 6f 6e 63 65 20 74 68 65  .** But once the
12780 20 74 72 69 67 67 65 72 20 74 65 72 6d 69 6e 61   trigger termina
12790 74 65 73 2c 20 74 68 65 20 76 61 6c 75 65 20 72  tes, the value r
127a0 65 74 75 72 6e 65 64 20 62 79 20 74 68 69 73 20  eturned by this 
127b0 72 6f 75 74 69 6e 65 0a 2a 2a 20 72 65 76 65 72  routine.** rever
127c0 74 73 20 74 6f 20 74 68 65 20 6c 61 73 74 20 76  ts to the last v
127d0 61 6c 75 65 20 69 6e 73 65 72 74 65 64 20 62 65  alue inserted be
127e0 66 6f 72 65 20 74 68 65 20 74 72 69 67 67 65 72  fore the trigger
127f0 20 66 69 72 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20   fired.)^.**.** 
12800 5e 41 6e 20 5b 49 4e 53 45 52 54 5d 20 74 68 61  ^An [INSERT] tha
12810 74 20 66 61 69 6c 73 20 64 75 65 20 74 6f 20 61  t fails due to a
12820 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f 6c   constraint viol
12830 61 74 69 6f 6e 20 69 73 20 6e 6f 74 20 61 0a 2a  ation is not a.*
12840 2a 20 73 75 63 63 65 73 73 66 75 6c 20 5b 49 4e  * successful [IN
12850 53 45 52 54 5d 20 61 6e 64 20 64 6f 65 73 20 6e  SERT] and does n
12860 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20 76 61  ot change the va
12870 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62 79 20  lue returned by 
12880 74 68 69 73 0a 2a 2a 20 72 6f 75 74 69 6e 65 2e  this.** routine.
12890 20 20 5e 54 68 75 73 20 49 4e 53 45 52 54 20 4f    ^Thus INSERT O
128a0 52 20 46 41 49 4c 2c 20 49 4e 53 45 52 54 20 4f  R FAIL, INSERT O
128b0 52 20 49 47 4e 4f 52 45 2c 20 49 4e 53 45 52 54  R IGNORE, INSERT
128c0 20 4f 52 20 52 4f 4c 4c 42 41 43 4b 2c 0a 2a 2a   OR ROLLBACK,.**
128d0 20 61 6e 64 20 49 4e 53 45 52 54 20 4f 52 20 41   and INSERT OR A
128e0 42 4f 52 54 20 6d 61 6b 65 20 6e 6f 20 63 68 61  BORT make no cha
128f0 6e 67 65 73 20 74 6f 20 74 68 65 20 72 65 74 75  nges to the retu
12900 72 6e 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73  rn value of this
12910 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 77 68 65 6e  .** routine when
12920 20 74 68 65 69 72 20 69 6e 73 65 72 74 69 6f 6e   their insertion
12930 20 66 61 69 6c 73 2e 20 20 5e 28 57 68 65 6e 20   fails.  ^(When 
12940 49 4e 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43  INSERT OR REPLAC
12950 45 0a 2a 2a 20 65 6e 63 6f 75 6e 74 65 72 73 20  E.** encounters 
12960 61 20 63 6f 6e 73 74 72 61 69 6e 74 20 76 69 6f  a constraint vio
12970 6c 61 74 69 6f 6e 2c 20 69 74 20 64 6f 65 73 20  lation, it does 
12980 6e 6f 74 20 66 61 69 6c 2e 20 20 54 68 65 0a 2a  not fail.  The.*
12990 2a 20 49 4e 53 45 52 54 20 63 6f 6e 74 69 6e 75  * INSERT continu
129a0 65 73 20 74 6f 20 63 6f 6d 70 6c 65 74 69 6f 6e  es to completion
129b0 20 61 66 74 65 72 20 64 65 6c 65 74 69 6e 67 20   after deleting 
129c0 72 6f 77 73 20 74 68 61 74 20 63 61 75 73 65 64  rows that caused
129d0 0a 2a 2a 20 74 68 65 20 63 6f 6e 73 74 72 61 69  .** the constrai
129e0 6e 74 20 70 72 6f 62 6c 65 6d 20 73 6f 20 49 4e  nt problem so IN
129f0 53 45 52 54 20 4f 52 20 52 45 50 4c 41 43 45 20  SERT OR REPLACE 
12a00 77 69 6c 6c 20 61 6c 77 61 79 73 20 63 68 61 6e  will always chan
12a10 67 65 0a 2a 2a 20 74 68 65 20 72 65 74 75 72 6e  ge.** the return
12a20 20 76 61 6c 75 65 20 6f 66 20 74 68 69 73 20 69   value of this i
12a30 6e 74 65 72 66 61 63 65 2e 29 5e 0a 2a 2a 0a 2a  nterface.)^.**.*
12a40 2a 20 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f  * ^For the purpo
12a50 73 65 73 20 6f 66 20 74 68 69 73 20 72 6f 75 74  ses of this rout
12a60 69 6e 65 2c 20 61 6e 20 5b 49 4e 53 45 52 54 5d  ine, an [INSERT]
12a70 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 74   is considered t
12a80 6f 0a 2a 2a 20 62 65 20 73 75 63 63 65 73 73 66  o.** be successf
12a90 75 6c 20 65 76 65 6e 20 69 66 20 69 74 20 69 73  ul even if it is
12aa0 20 73 75 62 73 65 71 75 65 6e 74 6c 79 20 72 6f   subsequently ro
12ab0 6c 6c 65 64 20 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a  lled back..**.**
12ac0 20 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20 69   This function i
12ad0 73 20 61 63 63 65 73 73 69 62 6c 65 20 74 6f 20  s accessible to 
12ae0 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 20 76  SQL statements v
12af0 69 61 20 74 68 65 0a 2a 2a 20 5b 6c 61 73 74 5f  ia the.** [last_
12b00 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 29 20 53  insert_rowid() S
12b10 51 4c 20 66 75 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a  QL function]..**
12b20 0a 2a 2a 20 49 66 20 61 20 73 65 70 61 72 61 74  .** If a separat
12b30 65 20 74 68 72 65 61 64 20 70 65 72 66 6f 72 6d  e thread perform
12b40 73 20 61 20 6e 65 77 20 5b 49 4e 53 45 52 54 5d  s a new [INSERT]
12b50 20 6f 6e 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20   on the same.** 
12b60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
12b70 69 6f 6e 20 77 68 69 6c 65 20 74 68 65 20 5b 73  ion while the [s
12b80 71 6c 69 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65  qlite3_last_inse
12b90 72 74 5f 72 6f 77 69 64 28 29 5d 0a 2a 2a 20 66  rt_rowid()].** f
12ba0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
12bb0 6e 67 20 61 6e 64 20 74 68 75 73 20 63 68 61 6e  ng and thus chan
12bc0 67 65 73 20 74 68 65 20 6c 61 73 74 20 69 6e 73  ges the last ins
12bd0 65 72 74 20 5b 72 6f 77 69 64 5d 2c 0a 2a 2a 20  ert [rowid],.** 
12be0 74 68 65 6e 20 74 68 65 20 76 61 6c 75 65 20 72  then the value r
12bf0 65 74 75 72 6e 65 64 20 62 79 20 5b 73 71 6c 69  eturned by [sqli
12c00 74 65 33 5f 6c 61 73 74 5f 69 6e 73 65 72 74 5f  te3_last_insert_
12c10 72 6f 77 69 64 28 29 5d 20 69 73 0a 2a 2a 20 75  rowid()] is.** u
12c20 6e 70 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64  npredictable and
12c30 20 6d 69 67 68 74 20 6e 6f 74 20 65 71 75 61 6c   might not equal
12c40 20 65 69 74 68 65 72 20 74 68 65 20 6f 6c 64 20   either the old 
12c50 6f 72 20 74 68 65 20 6e 65 77 0a 2a 2a 20 6c 61  or the new.** la
12c60 73 74 20 69 6e 73 65 72 74 20 5b 72 6f 77 69 64  st insert [rowid
12c70 5d 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e  ]..*/.sqlite3_in
12c80 74 36 34 20 73 71 6c 69 74 65 33 5f 6c 61 73 74  t64 sqlite3_last
12c90 5f 69 6e 73 65 72 74 5f 72 6f 77 69 64 28 73 71  _insert_rowid(sq
12ca0 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  lite3*);../*.** 
12cb0 43 41 50 49 33 52 45 46 3a 20 43 6f 75 6e 74 20  CAPI3REF: Count 
12cc0 54 68 65 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f  The Number Of Ro
12cd0 77 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a  ws Modified.**.*
12ce0 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e  * ^This function
12cf0 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d   returns the num
12d00 62 65 72 20 6f 66 20 64 61 74 61 62 61 73 65 20  ber of database 
12d10 72 6f 77 73 20 74 68 61 74 20 77 65 72 65 20 63  rows that were c
12d20 68 61 6e 67 65 64 0a 2a 2a 20 6f 72 20 69 6e 73  hanged.** or ins
12d30 65 72 74 65 64 20 6f 72 20 64 65 6c 65 74 65 64  erted or deleted
12d40 20 62 79 20 74 68 65 20 6d 6f 73 74 20 72 65 63   by the most rec
12d50 65 6e 74 6c 79 20 63 6f 6d 70 6c 65 74 65 64 20  ently completed 
12d60 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a  SQL statement.**
12d70 20 6f 6e 20 74 68 65 20 5b 64 61 74 61 62 61 73   on the [databas
12d80 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 73 70  e connection] sp
12d90 65 63 69 66 69 65 64 20 62 79 20 74 68 65 20 66  ecified by the f
12da0 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 2e 0a  irst parameter..
12db0 2a 2a 20 5e 28 4f 6e 6c 79 20 63 68 61 6e 67 65  ** ^(Only change
12dc0 73 20 74 68 61 74 20 61 72 65 20 64 69 72 65 63  s that are direc
12dd0 74 6c 79 20 73 70 65 63 69 66 69 65 64 20 62 79  tly specified by
12de0 20 74 68 65 20 5b 49 4e 53 45 52 54 5d 2c 20 5b   the [INSERT], [
12df0 55 50 44 41 54 45 5d 2c 0a 2a 2a 20 6f 72 20 5b  UPDATE],.** or [
12e00 44 45 4c 45 54 45 5d 20 73 74 61 74 65 6d 65 6e  DELETE] statemen
12e10 74 20 61 72 65 20 63 6f 75 6e 74 65 64 2e 20 20  t are counted.  
12e20 41 75 78 69 6c 69 61 72 79 20 63 68 61 6e 67 65  Auxiliary change
12e30 73 20 63 61 75 73 65 64 20 62 79 0a 2a 2a 20 74  s caused by.** t
12e40 72 69 67 67 65 72 73 20 6f 72 20 5b 66 6f 72 65  riggers or [fore
12e50 69 67 6e 20 6b 65 79 20 61 63 74 69 6f 6e 73 5d  ign key actions]
12e60 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
12e70 2e 29 5e 20 55 73 65 20 74 68 65 0a 2a 2a 20 5b  .)^ Use the.** [
12e80 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
12e90 61 6e 67 65 73 28 29 5d 20 66 75 6e 63 74 69 6f  anges()] functio
12ea0 6e 20 74 6f 20 66 69 6e 64 20 74 68 65 20 74 6f  n to find the to
12eb0 74 61 6c 20 6e 75 6d 62 65 72 20 6f 66 20 63 68  tal number of ch
12ec0 61 6e 67 65 73 0a 2a 2a 20 69 6e 63 6c 75 64 69  anges.** includi
12ed0 6e 67 20 63 68 61 6e 67 65 73 20 63 61 75 73 65  ng changes cause
12ee0 64 20 62 79 20 74 72 69 67 67 65 72 73 20 61 6e  d by triggers an
12ef0 64 20 66 6f 72 65 69 67 6e 20 6b 65 79 20 61 63  d foreign key ac
12f00 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 43 68  tions..**.** ^Ch
12f10 61 6e 67 65 73 20 74 6f 20 61 20 76 69 65 77 20  anges to a view 
12f20 74 68 61 74 20 61 72 65 20 73 69 6d 75 6c 61 74  that are simulat
12f30 65 64 20 62 79 20 61 6e 20 5b 49 4e 53 54 45 41  ed by an [INSTEA
12f40 44 20 4f 46 20 74 72 69 67 67 65 72 5d 0a 2a 2a  D OF trigger].**
12f50 20 61 72 65 20 6e 6f 74 20 63 6f 75 6e 74 65 64   are not counted
12f60 2e 20 20 4f 6e 6c 79 20 72 65 61 6c 20 74 61 62  .  Only real tab
12f70 6c 65 20 63 68 61 6e 67 65 73 20 61 72 65 20 63  le changes are c
12f80 6f 75 6e 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ounted..**.** ^(
12f90 41 20 22 72 6f 77 20 63 68 61 6e 67 65 22 20 69  A "row change" i
12fa0 73 20 61 20 63 68 61 6e 67 65 20 74 6f 20 61 20  s a change to a 
12fb0 73 69 6e 67 6c 65 20 72 6f 77 20 6f 66 20 61 20  single row of a 
12fc0 73 69 6e 67 6c 65 20 74 61 62 6c 65 0a 2a 2a 20  single table.** 
12fd0 63 61 75 73 65 64 20 62 79 20 61 6e 20 49 4e 53  caused by an INS
12fe0 45 52 54 2c 20 44 45 4c 45 54 45 2c 20 6f 72 20  ERT, DELETE, or 
12ff0 55 50 44 41 54 45 20 73 74 61 74 65 6d 65 6e 74  UPDATE statement
13000 2e 20 20 52 6f 77 73 20 74 68 61 74 0a 2a 2a 20  .  Rows that.** 
13010 61 72 65 20 63 68 61 6e 67 65 64 20 61 73 20 73  are changed as s
13020 69 64 65 20 65 66 66 65 63 74 73 20 6f 66 20 5b  ide effects of [
13030 52 45 50 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61  REPLACE] constra
13040 69 6e 74 20 72 65 73 6f 6c 75 74 69 6f 6e 2c 0a  int resolution,.
13050 2a 2a 20 72 6f 6c 6c 62 61 63 6b 2c 20 41 42 4f  ** rollback, ABO
13060 52 54 20 70 72 6f 63 65 73 73 69 6e 67 2c 20 5b  RT processing, [
13070 44 52 4f 50 20 54 41 42 4c 45 5d 2c 20 6f 72 20  DROP TABLE], or 
13080 62 79 20 61 6e 79 20 6f 74 68 65 72 0a 2a 2a 20  by any other.** 
13090 6d 65 63 68 61 6e 69 73 6d 73 20 64 6f 20 6e 6f  mechanisms do no
130a0 74 20 63 6f 75 6e 74 20 61 73 20 64 69 72 65 63  t count as direc
130b0 74 20 72 6f 77 20 63 68 61 6e 67 65 73 2e 29 5e  t row changes.)^
130c0 0a 2a 2a 0a 2a 2a 20 41 20 22 74 72 69 67 67 65  .**.** A "trigge
130d0 72 20 63 6f 6e 74 65 78 74 22 20 69 73 20 61 20  r context" is a 
130e0 73 63 6f 70 65 20 6f 66 20 65 78 65 63 75 74 69  scope of executi
130f0 6f 6e 20 74 68 61 74 20 62 65 67 69 6e 73 20 61  on that begins a
13100 6e 64 0a 2a 2a 20 65 6e 64 73 20 77 69 74 68 20  nd.** ends with 
13110 74 68 65 20 73 63 72 69 70 74 20 6f 66 20 61 20  the script of a 
13120 5b 43 52 45 41 54 45 20 54 52 49 47 47 45 52 20  [CREATE TRIGGER 
13130 7c 20 74 72 69 67 67 65 72 5d 2e 20 0a 2a 2a 20  | trigger]. .** 
13140 4d 6f 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65  Most SQL stateme
13150 6e 74 73 20 61 72 65 0a 2a 2a 20 65 76 61 6c 75  nts are.** evalu
13160 61 74 65 64 20 6f 75 74 73 69 64 65 20 6f 66 20  ated outside of 
13170 61 6e 79 20 74 72 69 67 67 65 72 2e 20 20 54 68  any trigger.  Th
13180 69 73 20 69 73 20 74 68 65 20 22 74 6f 70 20 6c  is is the "top l
13190 65 76 65 6c 22 0a 2a 2a 20 74 72 69 67 67 65 72  evel".** trigger
131a0 20 63 6f 6e 74 65 78 74 2e 20 20 49 66 20 61 20   context.  If a 
131b0 74 72 69 67 67 65 72 20 66 69 72 65 73 20 66 72  trigger fires fr
131c0 6f 6d 20 74 68 65 20 74 6f 70 20 6c 65 76 65 6c  om the top level
131d0 2c 20 61 0a 2a 2a 20 6e 65 77 20 74 72 69 67 67  , a.** new trigg
131e0 65 72 20 63 6f 6e 74 65 78 74 20 69 73 20 65 6e  er context is en
131f0 74 65 72 65 64 20 66 6f 72 20 74 68 65 20 64 75  tered for the du
13200 72 61 74 69 6f 6e 20 6f 66 20 74 68 61 74 20 6f  ration of that o
13210 6e 65 0a 2a 2a 20 74 72 69 67 67 65 72 2e 20 20  ne.** trigger.  
13220 53 75 62 74 72 69 67 67 65 72 73 20 63 72 65 61  Subtriggers crea
13230 74 65 20 73 75 62 63 6f 6e 74 65 78 74 73 20 66  te subcontexts f
13240 6f 72 20 74 68 65 69 72 20 64 75 72 61 74 69 6f  or their duratio
13250 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  n..**.** ^Callin
13260 67 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28  g [sqlite3_exec(
13270 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 73  )] or [sqlite3_s
13280 74 65 70 28 29 5d 20 72 65 63 75 72 73 69 76 65  tep()] recursive
13290 6c 79 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 63  ly does.** not c
132a0 72 65 61 74 65 20 61 20 6e 65 77 20 74 72 69 67  reate a new trig
132b0 67 65 72 20 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a  ger context..**.
132c0 2a 2a 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f  ** ^This functio
132d0 6e 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  n returns the nu
132e0 6d 62 65 72 20 6f 66 20 64 69 72 65 63 74 20 72  mber of direct r
132f0 6f 77 20 63 68 61 6e 67 65 73 20 69 6e 20 74 68  ow changes in th
13300 65 0a 2a 2a 20 6d 6f 73 74 20 72 65 63 65 6e 74  e.** most recent
13310 20 49 4e 53 45 52 54 2c 20 55 50 44 41 54 45 2c   INSERT, UPDATE,
13320 20 6f 72 20 44 45 4c 45 54 45 20 73 74 61 74 65   or DELETE state
13330 6d 65 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20  ment within the 
13340 73 61 6d 65 0a 2a 2a 20 74 72 69 67 67 65 72 20  same.** trigger 
13350 63 6f 6e 74 65 78 74 2e 0a 2a 2a 0a 2a 2a 20 5e  context..**.** ^
13360 54 68 75 73 2c 20 77 68 65 6e 20 63 61 6c 6c 65  Thus, when calle
13370 64 20 66 72 6f 6d 20 74 68 65 20 74 6f 70 20 6c  d from the top l
13380 65 76 65 6c 2c 20 74 68 69 73 20 66 75 6e 63 74  evel, this funct
13390 69 6f 6e 20 72 65 74 75 72 6e 73 20 74 68 65 0a  ion returns the.
133a0 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 63 68 61  ** number of cha
133b0 6e 67 65 73 20 69 6e 20 74 68 65 20 6d 6f 73 74  nges in the most
133c0 20 72 65 63 65 6e 74 20 49 4e 53 45 52 54 2c 20   recent INSERT, 
133d0 55 50 44 41 54 45 2c 20 6f 72 20 44 45 4c 45 54  UPDATE, or DELET
133e0 45 0a 2a 2a 20 74 68 61 74 20 61 6c 73 6f 20 6f  E.** that also o
133f0 63 63 75 72 72 65 64 20 61 74 20 74 68 65 20 74  ccurred at the t
13400 6f 70 20 6c 65 76 65 6c 2e 20 20 5e 28 57 69 74  op level.  ^(Wit
13410 68 69 6e 20 74 68 65 20 62 6f 64 79 20 6f 66 20  hin the body of 
13420 61 20 74 72 69 67 67 65 72 2c 0a 2a 2a 20 74 68  a trigger,.** th
13430 65 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65  e sqlite3_change
13440 73 28 29 20 69 6e 74 65 72 66 61 63 65 20 63 61  s() interface ca
13450 6e 20 62 65 20 63 61 6c 6c 65 64 20 74 6f 20 66  n be called to f
13460 69 6e 64 20 74 68 65 20 6e 75 6d 62 65 72 20 6f  ind the number o
13470 66 0a 2a 2a 20 63 68 61 6e 67 65 73 20 69 6e 20  f.** changes in 
13480 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 6c  the most recentl
13490 79 20 63 6f 6d 70 6c 65 74 65 64 20 49 4e 53 45  y completed INSE
134a0 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72 20 44  RT, UPDATE, or D
134b0 45 4c 45 54 45 0a 2a 2a 20 73 74 61 74 65 6d 65  ELETE.** stateme
134c0 6e 74 20 77 69 74 68 69 6e 20 74 68 65 20 62 6f  nt within the bo
134d0 64 79 20 6f 66 20 74 68 65 20 73 61 6d 65 20 74  dy of the same t
134e0 72 69 67 67 65 72 2e 0a 2a 2a 20 48 6f 77 65 76  rigger..** Howev
134f0 65 72 2c 20 74 68 65 20 6e 75 6d 62 65 72 20 72  er, the number r
13500 65 74 75 72 6e 65 64 20 64 6f 65 73 20 6e 6f 74  eturned does not
13510 20 69 6e 63 6c 75 64 65 20 63 68 61 6e 67 65 73   include changes
13520 0a 2a 2a 20 63 61 75 73 65 64 20 62 79 20 73 75  .** caused by su
13530 62 74 72 69 67 67 65 72 73 20 73 69 6e 63 65 20  btriggers since 
13540 74 68 6f 73 65 20 68 61 76 65 20 74 68 65 69 72  those have their
13550 20 6f 77 6e 20 63 6f 6e 74 65 78 74 2e 29 5e 0a   own context.)^.
13560 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74  **.** See also t
13570 68 65 20 5b 73 71 6c 69 74 65 33 5f 74 6f 74 61  he [sqlite3_tota
13580 6c 5f 63 68 61 6e 67 65 73 28 29 5d 20 69 6e 74  l_changes()] int
13590 65 72 66 61 63 65 2c 20 74 68 65 0a 2a 2a 20 5b  erface, the.** [
135a0 63 6f 75 6e 74 5f 63 68 61 6e 67 65 73 20 70 72  count_changes pr
135b0 61 67 6d 61 5d 2c 20 61 6e 64 20 74 68 65 20 5b  agma], and the [
135c0 63 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75  changes() SQL fu
135d0 6e 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49  nction]..**.** I
135e0 66 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72  f a separate thr
135f0 65 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65  ead makes change
13600 73 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61  s on the same da
13610 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
13620 6e 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69  n.** while [sqli
13630 74 65 33 5f 63 68 61 6e 67 65 73 28 29 5d 20 69  te3_changes()] i
13640 73 20 72 75 6e 6e 69 6e 67 20 74 68 65 6e 20 74  s running then t
13650 68 65 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65  he value returne
13660 64 0a 2a 2a 20 69 73 20 75 6e 70 72 65 64 69 63  d.** is unpredic
13670 74 61 62 6c 65 20 61 6e 64 20 6e 6f 74 20 6d 65  table and not me
13680 61 6e 69 6e 67 66 75 6c 2e 0a 2a 2f 0a 69 6e 74  aningful..*/.int
13690 20 73 71 6c 69 74 65 33 5f 63 68 61 6e 67 65 73   sqlite3_changes
136a0 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a  (sqlite3*);../*.
136b0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 54 6f 74  ** CAPI3REF: Tot
136c0 61 6c 20 4e 75 6d 62 65 72 20 4f 66 20 52 6f 77  al Number Of Row
136d0 73 20 4d 6f 64 69 66 69 65 64 0a 2a 2a 0a 2a 2a  s Modified.**.**
136e0 20 5e 54 68 69 73 20 66 75 6e 63 74 69 6f 6e 20   ^This function 
136f0 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62  returns the numb
13700 65 72 20 6f 66 20 72 6f 77 20 63 68 61 6e 67 65  er of row change
13710 73 20 63 61 75 73 65 64 20 62 79 20 5b 49 4e 53  s caused by [INS
13720 45 52 54 5d 2c 0a 2a 2a 20 5b 55 50 44 41 54 45  ERT],.** [UPDATE
13730 5d 20 6f 72 20 5b 44 45 4c 45 54 45 5d 20 73 74  ] or [DELETE] st
13740 61 74 65 6d 65 6e 74 73 20 73 69 6e 63 65 20 74  atements since t
13750 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
13760 6e 65 63 74 69 6f 6e 5d 20 77 61 73 20 6f 70 65  nection] was ope
13770 6e 65 64 2e 0a 2a 2a 20 5e 28 54 68 65 20 63 6f  ned..** ^(The co
13780 75 6e 74 20 72 65 74 75 72 6e 65 64 20 62 79 20  unt returned by 
13790 73 71 6c 69 74 65 33 5f 74 6f 74 61 6c 5f 63 68  sqlite3_total_ch
137a0 61 6e 67 65 73 28 29 20 69 6e 63 6c 75 64 65 73  anges() includes
137b0 20 61 6c 6c 20 63 68 61 6e 67 65 73 0a 2a 2a 20   all changes.** 
137c0 66 72 6f 6d 20 61 6c 6c 20 5b 43 52 45 41 54 45  from all [CREATE
137d0 20 54 52 49 47 47 45 52 20 7c 20 74 72 69 67 67   TRIGGER | trigg
137e0 65 72 5d 20 63 6f 6e 74 65 78 74 73 20 61 6e 64  er] contexts and
137f0 20 63 68 61 6e 67 65 73 20 6d 61 64 65 20 62 79   changes made by
13800 0a 2a 2a 20 5b 66 6f 72 65 69 67 6e 20 6b 65 79  .** [foreign key
13810 20 61 63 74 69 6f 6e 73 5d 2e 20 48 6f 77 65 76   actions]. Howev
13820 65 72 2c 0a 2a 2a 20 74 68 65 20 63 6f 75 6e 74  er,.** the count
13830 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75 64   does not includ
13840 65 20 63 68 61 6e 67 65 73 20 75 73 65 64 20 74  e changes used t
13850 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 5b 52 45 50  o implement [REP
13860 4c 41 43 45 5d 20 63 6f 6e 73 74 72 61 69 6e 74  LACE] constraint
13870 73 2c 0a 2a 2a 20 64 6f 20 72 6f 6c 6c 62 61 63  s,.** do rollbac
13880 6b 73 20 6f 72 20 41 42 4f 52 54 20 70 72 6f 63  ks or ABORT proc
13890 65 73 73 69 6e 67 2c 20 6f 72 20 5b 44 52 4f 50  essing, or [DROP
138a0 20 54 41 42 4c 45 5d 20 70 72 6f 63 65 73 73 69   TABLE] processi
138b0 6e 67 2e 20 20 54 68 65 0a 2a 2a 20 63 6f 75 6e  ng.  The.** coun
138c0 74 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63 6c 75  t does not inclu
138d0 64 65 20 72 6f 77 73 20 6f 66 20 76 69 65 77 73  de rows of views
138e0 20 74 68 61 74 20 66 69 72 65 20 61 6e 20 5b 49   that fire an [I
138f0 4e 53 54 45 41 44 20 4f 46 20 74 72 69 67 67 65  NSTEAD OF trigge
13900 72 5d 2c 0a 2a 2a 20 74 68 6f 75 67 68 20 69 66  r],.** though if
13910 20 74 68 65 20 49 4e 53 54 45 41 44 20 4f 46 20   the INSTEAD OF 
13920 74 72 69 67 67 65 72 20 6d 61 6b 65 73 20 63 68  trigger makes ch
13930 61 6e 67 65 73 20 6f 66 20 69 74 73 20 6f 77 6e  anges of its own
13940 2c 20 74 68 6f 73 65 20 63 68 61 6e 67 65 73 20  , those changes 
13950 0a 2a 2a 20 61 72 65 20 63 6f 75 6e 74 65 64 2e  .** are counted.
13960 29 5e 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  )^.** ^The sqlit
13970 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13980 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 6f 75 6e  () function coun
13990 74 73 20 74 68 65 20 63 68 61 6e 67 65 73 20 61  ts the changes a
139a0 73 20 73 6f 6f 6e 20 61 73 0a 2a 2a 20 74 68 65  s soon as.** the
139b0 20 73 74 61 74 65 6d 65 6e 74 20 74 68 61 74 20   statement that 
139c0 6d 61 6b 65 73 20 74 68 65 6d 20 69 73 20 63 6f  makes them is co
139d0 6d 70 6c 65 74 65 64 20 28 77 68 65 6e 20 74 68  mpleted (when th
139e0 65 20 73 74 61 74 65 6d 65 6e 74 20 68 61 6e 64  e statement hand
139f0 6c 65 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20  le.** is passed 
13a00 74 6f 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65  to [sqlite3_rese
13a10 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  t()] or [sqlite3
13a20 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 29 2e 0a 2a  _finalize()])..*
13a30 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 20 74 68  *.** See also th
13a40 65 20 5b 73 71 6c 69 74 65 33 5f 63 68 61 6e 67  e [sqlite3_chang
13a50 65 73 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2c  es()] interface,
13a60 20 74 68 65 0a 2a 2a 20 5b 63 6f 75 6e 74 5f 63   the.** [count_c
13a70 68 61 6e 67 65 73 20 70 72 61 67 6d 61 5d 2c 20  hanges pragma], 
13a80 61 6e 64 20 74 68 65 20 5b 74 6f 74 61 6c 5f 63  and the [total_c
13a90 68 61 6e 67 65 73 28 29 20 53 51 4c 20 66 75 6e  hanges() SQL fun
13aa0 63 74 69 6f 6e 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66  ction]..**.** If
13ab0 20 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65   a separate thre
13ac0 61 64 20 6d 61 6b 65 73 20 63 68 61 6e 67 65 73  ad makes changes
13ad0 20 6f 6e 20 74 68 65 20 73 61 6d 65 20 64 61 74   on the same dat
13ae0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
13af0 0a 2a 2a 20 77 68 69 6c 65 20 5b 73 71 6c 69 74  .** while [sqlit
13b00 65 33 5f 74 6f 74 61 6c 5f 63 68 61 6e 67 65 73  e3_total_changes
13b10 28 29 5d 20 69 73 20 72 75 6e 6e 69 6e 67 20 74  ()] is running t
13b20 68 65 6e 20 74 68 65 20 76 61 6c 75 65 0a 2a 2a  hen the value.**
13b30 20 72 65 74 75 72 6e 65 64 20 69 73 20 75 6e 70   returned is unp
13b40 72 65 64 69 63 74 61 62 6c 65 20 61 6e 64 20 6e  redictable and n
13b50 6f 74 20 6d 65 61 6e 69 6e 67 66 75 6c 2e 0a 2a  ot meaningful..*
13b60 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 74 6f  /.int sqlite3_to
13b70 74 61 6c 5f 63 68 61 6e 67 65 73 28 73 71 6c 69  tal_changes(sqli
13b80 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  te3*);../*.** CA
13b90 50 49 33 52 45 46 3a 20 49 6e 74 65 72 72 75 70  PI3REF: Interrup
13ba0 74 20 41 20 4c 6f 6e 67 2d 52 75 6e 6e 69 6e 67  t A Long-Running
13bb0 20 51 75 65 72 79 0a 2a 2a 0a 2a 2a 20 5e 54 68   Query.**.** ^Th
13bc0 69 73 20 66 75 6e 63 74 69 6f 6e 20 63 61 75 73  is function caus
13bd0 65 73 20 61 6e 79 20 70 65 6e 64 69 6e 67 20 64  es any pending d
13be0 61 74 61 62 61 73 65 20 6f 70 65 72 61 74 69 6f  atabase operatio
13bf0 6e 20 74 6f 20 61 62 6f 72 74 20 61 6e 64 0a 2a  n to abort and.*
13c00 2a 20 72 65 74 75 72 6e 20 61 74 20 69 74 73 20  * return at its 
13c10 65 61 72 6c 69 65 73 74 20 6f 70 70 6f 72 74 75  earliest opportu
13c20 6e 69 74 79 2e 20 54 68 69 73 20 72 6f 75 74 69  nity. This routi
13c30 6e 65 20 69 73 20 74 79 70 69 63 61 6c 6c 79 0a  ne is typically.
13c40 2a 2a 20 63 61 6c 6c 65 64 20 69 6e 20 72 65 73  ** called in res
13c50 70 6f 6e 73 65 20 74 6f 20 61 20 75 73 65 72 20  ponse to a user 
13c60 61 63 74 69 6f 6e 20 73 75 63 68 20 61 73 20 70  action such as p
13c70 72 65 73 73 69 6e 67 20 22 43 61 6e 63 65 6c 22  ressing "Cancel"
13c80 0a 2a 2a 20 6f 72 20 43 74 72 6c 2d 43 20 77 68  .** or Ctrl-C wh
13c90 65 72 65 20 74 68 65 20 75 73 65 72 20 77 61 6e  ere the user wan
13ca0 74 73 20 61 20 6c 6f 6e 67 20 71 75 65 72 79 20  ts a long query 
13cb0 6f 70 65 72 61 74 69 6f 6e 20 74 6f 20 68 61 6c  operation to hal
13cc0 74 0a 2a 2a 20 69 6d 6d 65 64 69 61 74 65 6c 79  t.** immediately
13cd0 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73 20 73  ..**.** ^It is s
13ce0 61 66 65 20 74 6f 20 63 61 6c 6c 20 74 68 69 73  afe to call this
13cf0 20 72 6f 75 74 69 6e 65 20 66 72 6f 6d 20 61 20   routine from a 
13d00 74 68 72 65 61 64 20 64 69 66 66 65 72 65 6e 74  thread different
13d10 20 66 72 6f 6d 20 74 68 65 0a 2a 2a 20 74 68 72   from the.** thr
13d20 65 61 64 20 74 68 61 74 20 69 73 20 63 75 72 72  ead that is curr
13d30 65 6e 74 6c 79 20 72 75 6e 6e 69 6e 67 20 74 68  ently running th
13d40 65 20 64 61 74 61 62 61 73 65 20 6f 70 65 72 61  e database opera
13d50 74 69 6f 6e 2e 20 20 42 75 74 20 69 74 0a 2a 2a  tion.  But it.**
13d60 20 69 73 20 6e 6f 74 20 73 61 66 65 20 74 6f 20   is not safe to 
13d70 63 61 6c 6c 20 74 68 69 73 20 72 6f 75 74 69 6e  call this routin
13d80 65 20 77 69 74 68 20 61 20 5b 64 61 74 61 62 61  e with a [databa
13d90 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74  se connection] t
13da0 68 61 74 0a 2a 2a 20 69 73 20 63 6c 6f 73 65 64  hat.** is closed
13db0 20 6f 72 20 6d 69 67 68 74 20 63 6c 6f 73 65 20   or might close 
13dc0 62 65 66 6f 72 65 20 73 71 6c 69 74 65 33 5f 69  before sqlite3_i
13dd0 6e 74 65 72 72 75 70 74 28 29 20 72 65 74 75 72  nterrupt() retur
13de0 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 61 6e  ns..**.** ^If an
13df0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 69   SQL operation i
13e00 73 20 76 65 72 79 20 6e 65 61 72 6c 79 20 66 69  s very nearly fi
13e10 6e 69 73 68 65 64 20 61 74 20 74 68 65 20 74 69  nished at the ti
13e20 6d 65 20 77 68 65 6e 0a 2a 2a 20 73 71 6c 69 74  me when.** sqlit
13e30 65 33 5f 69 6e 74 65 72 72 75 70 74 28 29 20 69  e3_interrupt() i
13e40 73 20 63 61 6c 6c 65 64 2c 20 74 68 65 6e 20 69  s called, then i
13e50 74 20 6d 69 67 68 74 20 6e 6f 74 20 68 61 76 65  t might not have
13e60 20 61 6e 20 6f 70 70 6f 72 74 75 6e 69 74 79 0a   an opportunity.
13e70 2a 2a 20 74 6f 20 62 65 20 69 6e 74 65 72 72 75  ** to be interru
13e80 70 74 65 64 20 61 6e 64 20 6d 69 67 68 74 20 63  pted and might c
13e90 6f 6e 74 69 6e 75 65 20 74 6f 20 63 6f 6d 70 6c  ontinue to compl
13ea0 65 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 41 6e  etion..**.** ^An
13eb0 20 53 51 4c 20 6f 70 65 72 61 74 69 6f 6e 20 74   SQL operation t
13ec0 68 61 74 20 69 73 20 69 6e 74 65 72 72 75 70 74  hat is interrupt
13ed0 65 64 20 77 69 6c 6c 20 72 65 74 75 72 6e 20 5b  ed will return [
13ee0 53 51 4c 49 54 45 5f 49 4e 54 45 52 52 55 50 54  SQLITE_INTERRUPT
13ef0 5d 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 69 6e  ]..** ^If the in
13f00 74 65 72 72 75 70 74 65 64 20 53 51 4c 20 6f 70  terrupted SQL op
13f10 65 72 61 74 69 6f 6e 20 69 73 20 61 6e 20 49 4e  eration is an IN
13f20 53 45 52 54 2c 20 55 50 44 41 54 45 2c 20 6f 72  SERT, UPDATE, or
13f30 20 44 45 4c 45 54 45 0a 2a 2a 20 74 68 61 74 20   DELETE.** that 
13f40 69 73 20 69 6e 73 69 64 65 20 61 6e 20 65 78 70  is inside an exp
13f50 6c 69 63 69 74 20 74 72 61 6e 73 61 63 74 69 6f  licit transactio
13f60 6e 2c 20 74 68 65 6e 20 74 68 65 20 65 6e 74 69  n, then the enti
13f70 72 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 0a 2a  re transaction.*
13f80 2a 20 77 69 6c 6c 20 62 65 20 72 6f 6c 6c 65 64  * will be rolled
13f90 20 62 61 63 6b 20 61 75 74 6f 6d 61 74 69 63 61   back automatica
13fa0 6c 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  lly..**.** ^The 
13fb0 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75 70  sqlite3_interrup
13fc0 74 28 44 29 20 63 61 6c 6c 20 69 73 20 69 6e 20  t(D) call is in 
13fd0 65 66 66 65 63 74 20 75 6e 74 69 6c 20 61 6c 6c  effect until all
13fe0 20 63 75 72 72 65 6e 74 6c 79 20 72 75 6e 6e 69   currently runni
13ff0 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  ng.** SQL statem
14000 65 6e 74 73 20 6f 6e 20 5b 64 61 74 61 62 61 73  ents on [databas
14010 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 20  e connection] D 
14020 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 41 6e 79 20  complete.  ^Any 
14030 6e 65 77 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  new SQL statemen
14040 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20 73  ts.** that are s
14050 74 61 72 74 65 64 20 61 66 74 65 72 20 74 68 65  tarted after the
14060 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72 72 75   sqlite3_interru
14070 70 74 28 29 20 63 61 6c 6c 20 61 6e 64 20 62 65  pt() call and be
14080 66 6f 72 65 20 74 68 65 20 0a 2a 2a 20 72 75 6e  fore the .** run
14090 6e 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 73 20  ning statements 
140a0 72 65 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65  reaches zero are
140b0 20 69 6e 74 65 72 72 75 70 74 65 64 20 61 73 20   interrupted as 
140c0 69 66 20 74 68 65 79 20 68 61 64 20 62 65 65 6e  if they had been
140d0 0a 2a 2a 20 72 75 6e 6e 69 6e 67 20 70 72 69 6f  .** running prio
140e0 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33  r to the sqlite3
140f0 5f 69 6e 74 65 72 72 75 70 74 28 29 20 63 61 6c  _interrupt() cal
14100 6c 2e 20 20 5e 4e 65 77 20 53 51 4c 20 73 74 61  l.  ^New SQL sta
14110 74 65 6d 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20  tements.** that 
14120 61 72 65 20 73 74 61 72 74 65 64 20 61 66 74 65  are started afte
14130 72 20 74 68 65 20 72 75 6e 6e 69 6e 67 20 73 74  r the running st
14140 61 74 65 6d 65 6e 74 20 63 6f 75 6e 74 20 72 65  atement count re
14150 61 63 68 65 73 20 7a 65 72 6f 20 61 72 65 0a 2a  aches zero are.*
14160 2a 20 6e 6f 74 20 65 66 66 65 63 74 65 64 20 62  * not effected b
14170 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f 69 6e  y the sqlite3_in
14180 74 65 72 72 75 70 74 28 29 2e 0a 2a 2a 20 5e 41  terrupt()..** ^A
14190 20 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33   call to sqlite3
141a0 5f 69 6e 74 65 72 72 75 70 74 28 44 29 20 74 68  _interrupt(D) th
141b0 61 74 20 6f 63 63 75 72 73 20 77 68 65 6e 20 74  at occurs when t
141c0 68 65 72 65 20 61 72 65 20 6e 6f 20 72 75 6e 6e  here are no runn
141d0 69 6e 67 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65  ing.** SQL state
141e0 6d 65 6e 74 73 20 69 73 20 61 20 6e 6f 2d 6f 70  ments is a no-op
141f0 20 61 6e 64 20 68 61 73 20 6e 6f 20 65 66 66 65   and has no effe
14200 63 74 20 6f 6e 20 53 51 4c 20 73 74 61 74 65 6d  ct on SQL statem
14210 65 6e 74 73 0a 2a 2a 20 74 68 61 74 20 61 72 65  ents.** that are
14220 20 73 74 61 72 74 65 64 20 61 66 74 65 72 20 74   started after t
14230 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  he sqlite3_inter
14240 72 75 70 74 28 29 20 63 61 6c 6c 20 72 65 74 75  rupt() call retu
14250 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68  rns..**.** If th
14260 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65  e database conne
14270 63 74 69 6f 6e 20 63 6c 6f 73 65 73 20 77 68 69  ction closes whi
14280 6c 65 20 5b 73 71 6c 69 74 65 33 5f 69 6e 74 65  le [sqlite3_inte
14290 72 72 75 70 74 28 29 5d 0a 2a 2a 20 69 73 20 72  rrupt()].** is r
142a0 75 6e 6e 69 6e 67 20 74 68 65 6e 20 62 61 64 20  unning then bad 
142b0 74 68 69 6e 67 73 20 77 69 6c 6c 20 6c 69 6b 65  things will like
142c0 6c 79 20 68 61 70 70 65 6e 2e 0a 2a 2f 0a 76 6f  ly happen..*/.vo
142d0 69 64 20 73 71 6c 69 74 65 33 5f 69 6e 74 65 72  id sqlite3_inter
142e0 72 75 70 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a  rupt(sqlite3*);.
142f0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
14300 20 44 65 74 65 72 6d 69 6e 65 20 49 66 20 41 6e   Determine If An
14310 20 53 51 4c 20 53 74 61 74 65 6d 65 6e 74 20 49   SQL Statement I
14320 73 20 43 6f 6d 70 6c 65 74 65 0a 2a 2a 0a 2a 2a  s Complete.**.**
14330 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20   These routines 
14340 61 72 65 20 75 73 65 66 75 6c 20 64 75 72 69 6e  are useful durin
14350 67 20 63 6f 6d 6d 61 6e 64 2d 6c 69 6e 65 20 69  g command-line i
14360 6e 70 75 74 20 74 6f 20 64 65 74 65 72 6d 69 6e  nput to determin
14370 65 20 69 66 20 74 68 65 0a 2a 2a 20 63 75 72 72  e if the.** curr
14380 65 6e 74 6c 79 20 65 6e 74 65 72 65 64 20 74 65  ently entered te
14390 78 74 20 73 65 65 6d 73 20 74 6f 20 66 6f 72 6d  xt seems to form
143a0 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
143b0 73 74 61 74 65 6d 65 6e 74 20 6f 72 0a 2a 2a 20  statement or.** 
143c0 69 66 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e  if additional in
143d0 70 75 74 20 69 73 20 6e 65 65 64 65 64 20 62 65  put is needed be
143e0 66 6f 72 65 20 73 65 6e 64 69 6e 67 20 74 68 65  fore sending the
143f0 20 74 65 78 74 20 69 6e 74 6f 0a 2a 2a 20 53 51   text into.** SQ
14400 4c 69 74 65 20 66 6f 72 20 70 61 72 73 69 6e 67  Lite for parsing
14410 2e 20 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  .  ^These routin
14420 65 73 20 72 65 74 75 72 6e 20 31 20 69 66 20 74  es return 1 if t
14430 68 65 20 69 6e 70 75 74 20 73 74 72 69 6e 67 0a  he input string.
14440 2a 2a 20 61 70 70 65 61 72 73 20 74 6f 20 62 65  ** appears to be
14450 20 61 20 63 6f 6d 70 6c 65 74 65 20 53 51 4c 20   a complete SQL 
14460 73 74 61 74 65 6d 65 6e 74 2e 20 20 5e 41 20 73  statement.  ^A s
14470 74 61 74 65 6d 65 6e 74 20 69 73 20 6a 75 64 67  tatement is judg
14480 65 64 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70  ed to be.** comp
14490 6c 65 74 65 20 69 66 20 69 74 20 65 6e 64 73 20  lete if it ends 
144a0 77 69 74 68 20 61 20 73 65 6d 69 63 6f 6c 6f 6e  with a semicolon
144b0 20 74 6f 6b 65 6e 20 61 6e 64 20 69 73 20 6e 6f   token and is no
144c0 74 20 61 20 70 72 65 66 69 78 20 6f 66 20 61 0a  t a prefix of a.
144d0 2a 2a 20 77 65 6c 6c 2d 66 6f 72 6d 65 64 20 43  ** well-formed C
144e0 52 45 41 54 45 20 54 52 49 47 47 45 52 20 73 74  REATE TRIGGER st
144f0 61 74 65 6d 65 6e 74 2e 20 20 5e 53 65 6d 69 63  atement.  ^Semic
14500 6f 6c 6f 6e 73 20 74 68 61 74 20 61 72 65 20 65  olons that are e
14510 6d 62 65 64 64 65 64 20 77 69 74 68 69 6e 0a 2a  mbedded within.*
14520 2a 20 73 74 72 69 6e 67 20 6c 69 74 65 72 61 6c  * string literal
14530 73 20 6f 72 20 71 75 6f 74 65 64 20 69 64 65 6e  s or quoted iden
14540 74 69 66 69 65 72 20 6e 61 6d 65 73 20 6f 72 20  tifier names or 
14550 63 6f 6d 6d 65 6e 74 73 20 61 72 65 20 6e 6f 74  comments are not
14560 0a 2a 2a 20 69 6e 64 65 70 65 6e 64 65 6e 74 20  .** independent 
14570 74 6f 6b 65 6e 73 20 28 74 68 65 79 20 61 72 65  tokens (they are
14580 20 70 61 72 74 20 6f 66 20 74 68 65 20 74 6f 6b   part of the tok
14590 65 6e 20 69 6e 20 77 68 69 63 68 20 74 68 65 79  en in which they
145a0 20 61 72 65 0a 2a 2a 20 65 6d 62 65 64 64 65 64   are.** embedded
145b0 29 20 61 6e 64 20 74 68 75 73 20 64 6f 20 6e 6f  ) and thus do no
145c0 74 20 63 6f 75 6e 74 20 61 73 20 61 20 73 74 61  t count as a sta
145d0 74 65 6d 65 6e 74 20 74 65 72 6d 69 6e 61 74 6f  tement terminato
145e0 72 2e 20 20 5e 57 68 69 74 65 73 70 61 63 65 0a  r.  ^Whitespace.
145f0 2a 2a 20 61 6e 64 20 63 6f 6d 6d 65 6e 74 73 20  ** and comments 
14600 74 68 61 74 20 66 6f 6c 6c 6f 77 20 74 68 65 20  that follow the 
14610 66 69 6e 61 6c 20 73 65 6d 69 63 6f 6c 6f 6e 20  final semicolon 
14620 61 72 65 20 69 67 6e 6f 72 65 64 2e 0a 2a 2a 0a  are ignored..**.
14630 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e  ** ^These routin
14640 65 73 20 72 65 74 75 72 6e 20 30 20 69 66 20 74  es return 0 if t
14650 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69 73 20  he statement is 
14660 69 6e 63 6f 6d 70 6c 65 74 65 2e 20 20 5e 49 66  incomplete.  ^If
14670 20 61 0a 2a 2a 20 6d 65 6d 6f 72 79 20 61 6c 6c   a.** memory all
14680 6f 63 61 74 69 6f 6e 20 66 61 69 6c 73 2c 20 74  ocation fails, t
14690 68 65 6e 20 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d  hen SQLITE_NOMEM
146a0 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
146b0 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69  .** ^These routi
146c0 6e 65 73 20 64 6f 20 6e 6f 74 20 70 61 72 73 65  nes do not parse
146d0 20 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65   the SQL stateme
146e0 6e 74 73 20 74 68 75 73 0a 2a 2a 20 77 69 6c 6c  nts thus.** will
146f0 20 6e 6f 74 20 64 65 74 65 63 74 20 73 79 6e 74   not detect synt
14700 61 63 74 69 63 61 6c 6c 79 20 69 6e 63 6f 72 72  actically incorr
14710 65 63 74 20 53 51 4c 2e 0a 2a 2a 0a 2a 2a 20 5e  ect SQL..**.** ^
14720 28 49 66 20 53 51 4c 69 74 65 20 68 61 73 20 6e  (If SQLite has n
14730 6f 74 20 62 65 65 6e 20 69 6e 69 74 69 61 6c 69  ot been initiali
14740 7a 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74  zed using [sqlit
14750 65 33 5f 69 6e 69 74 69 61 6c 69 7a 65 28 29 5d  e3_initialize()]
14760 20 70 72 69 6f 72 20 0a 2a 2a 20 74 6f 20 69 6e   prior .** to in
14770 76 6f 6b 69 6e 67 20 73 71 6c 69 74 65 33 5f 63  voking sqlite3_c
14780 6f 6d 70 6c 65 74 65 31 36 28 29 20 74 68 65 6e  omplete16() then
14790 20 73 71 6c 69 74 65 33 5f 69 6e 69 74 69 61 6c   sqlite3_initial
147a0 69 7a 65 28 29 20 69 73 20 69 6e 76 6f 6b 65 64  ize() is invoked
147b0 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
147c0 79 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6d  y by sqlite3_com
147d0 70 6c 65 74 65 31 36 28 29 2e 20 20 49 66 20 74  plete16().  If t
147e0 68 61 74 20 69 6e 69 74 69 61 6c 69 7a 61 74 69  hat initializati
147f0 6f 6e 20 66 61 69 6c 73 2c 0a 2a 2a 20 74 68 65  on fails,.** the
14800 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c  n the return val
14810 75 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f  ue from sqlite3_
14820 63 6f 6d 70 6c 65 74 65 31 36 28 29 20 77 69 6c  complete16() wil
14830 6c 20 62 65 20 6e 6f 6e 2d 7a 65 72 6f 0a 2a 2a  l be non-zero.**
14840 20 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77   regardless of w
14850 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
14860 65 20 69 6e 70 75 74 20 53 51 4c 20 69 73 20 63  e input SQL is c
14870 6f 6d 70 6c 65 74 65 2e 29 5e 0a 2a 2a 0a 2a 2a  omplete.)^.**.**
14880 20 54 68 65 20 69 6e 70 75 74 20 74 6f 20 5b 73   The input to [s
14890 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65 28  qlite3_complete(
148a0 29 5d 20 6d 75 73 74 20 62 65 20 61 20 7a 65 72  )] must be a zer
148b0 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
148c0 55 54 46 2d 38 20 73 74 72 69 6e 67 2e 0a 2a 2a  UTF-8 string..**
148d0 0a 2a 2a 20 54 68 65 20 69 6e 70 75 74 20 74 6f  .** The input to
148e0 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65   [sqlite3_comple
148f0 74 65 31 36 28 29 5d 20 6d 75 73 74 20 62 65 20  te16()] must be 
14900 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65  a zero-terminate
14910 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72 69  d.** UTF-16 stri
14920 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
14930 65 20 6f 72 64 65 72 2e 0a 2a 2f 0a 69 6e 74 20  e order..*/.int 
14940 73 71 6c 69 74 65 33 5f 63 6f 6d 70 6c 65 74 65  sqlite3_complete
14950 28 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  (const char *sql
14960 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  );.int sqlite3_c
14970 6f 6d 70 6c 65 74 65 31 36 28 63 6f 6e 73 74 20  omplete16(const 
14980 76 6f 69 64 20 2a 73 71 6c 29 3b 0a 0a 2f 2a 0a  void *sql);../*.
14990 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52 65 67  ** CAPI3REF: Reg
149a0 69 73 74 65 72 20 41 20 43 61 6c 6c 62 61 63 6b  ister A Callback
149b0 20 54 6f 20 48 61 6e 64 6c 65 20 53 51 4c 49 54   To Handle SQLIT
149c0 45 5f 42 55 53 59 20 45 72 72 6f 72 73 0a 2a 2a  E_BUSY Errors.**
149d0 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69 6e  .** ^This routin
149e0 65 20 73 65 74 73 20 61 20 63 61 6c 6c 62 61 63  e sets a callbac
149f0 6b 20 66 75 6e 63 74 69 6f 6e 20 74 68 61 74 20  k function that 
14a00 6d 69 67 68 74 20 62 65 20 69 6e 76 6f 6b 65 64  might be invoked
14a10 20 77 68 65 6e 65 76 65 72 0a 2a 2a 20 61 6e 20   whenever.** an 
14a20 61 74 74 65 6d 70 74 20 69 73 20 6d 61 64 65 20  attempt is made 
14a30 74 6f 20 6f 70 65 6e 20 61 20 64 61 74 61 62 61  to open a databa
14a40 73 65 20 74 61 62 6c 65 20 74 68 61 74 20 61 6e  se table that an
14a50 6f 74 68 65 72 20 74 68 72 65 61 64 0a 2a 2a 20  other thread.** 
14a60 6f 72 20 70 72 6f 63 65 73 73 20 68 61 73 20 6c  or process has l
14a70 6f 63 6b 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  ocked..**.** ^If
14a80 20 74 68 65 20 62 75 73 79 20 63 61 6c 6c 62 61   the busy callba
14a90 63 6b 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e  ck is NULL, then
14aa0 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20 6f   [SQLITE_BUSY] o
14ab0 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52 5f  r [SQLITE_IOERR_
14ac0 42 4c 4f 43 4b 45 44 5d 0a 2a 2a 20 69 73 20 72  BLOCKED].** is r
14ad0 65 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74  eturned immediat
14ae0 65 6c 79 20 75 70 6f 6e 20 65 6e 63 6f 75 6e 74  ely upon encount
14af0 65 72 69 6e 67 20 74 68 65 20 6c 6f 63 6b 2e 20  ering the lock. 
14b00 20 5e 49 66 20 74 68 65 20 62 75 73 79 20 63 61   ^If the busy ca
14b10 6c 6c 62 61 63 6b 0a 2a 2a 20 69 73 20 6e 6f 74  llback.** is not
14b20 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
14b30 63 61 6c 6c 62 61 63 6b 20 6d 69 67 68 74 20 62  callback might b
14b40 65 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 74  e invoked with t
14b50 77 6f 20 61 72 67 75 6d 65 6e 74 73 2e 0a 2a 2a  wo arguments..**
14b60 0a 2a 2a 20 5e 54 68 65 20 66 69 72 73 74 20 61  .** ^The first a
14b70 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20 62  rgument to the b
14b80 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 61  usy handler is a
14b90 20 63 6f 70 79 20 6f 66 20 74 68 65 20 76 6f 69   copy of the voi
14ba0 64 2a 20 70 6f 69 6e 74 65 72 20 77 68 69 63 68  d* pointer which
14bb0 0a 2a 2a 20 69 73 20 74 68 65 20 74 68 69 72 64  .** is the third
14bc0 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
14bd0 69 74 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65  ite3_busy_handle
14be0 72 28 29 2e 20 20 5e 54 68 65 20 73 65 63 6f 6e  r().  ^The secon
14bf0 64 20 61 72 67 75 6d 65 6e 74 20 74 6f 0a 2a 2a  d argument to.**
14c00 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
14c10 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68  r callback is th
14c20 65 20 6e 75 6d 62 65 72 20 6f 66 20 74 69 6d 65  e number of time
14c30 73 20 74 68 61 74 20 74 68 65 20 62 75 73 79 20  s that the busy 
14c40 68 61 6e 64 6c 65 72 20 68 61 73 0a 2a 2a 20 62  handler has.** b
14c50 65 65 6e 20 69 6e 76 6f 6b 65 64 20 66 6f 72 20  een invoked for 
14c60 74 68 69 73 20 6c 6f 63 6b 69 6e 67 20 65 76 65  this locking eve
14c70 6e 74 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20  nt.  ^If the.** 
14c80 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 72 65  busy callback re
14c90 74 75 72 6e 73 20 30 2c 20 74 68 65 6e 20 6e 6f  turns 0, then no
14ca0 20 61 64 64 69 74 69 6f 6e 61 6c 20 61 74 74 65   additional atte
14cb0 6d 70 74 73 20 61 72 65 20 6d 61 64 65 20 74 6f  mpts are made to
14cc0 0a 2a 2a 20 61 63 63 65 73 73 20 74 68 65 20 64  .** access the d
14cd0 61 74 61 62 61 73 65 20 61 6e 64 20 5b 53 51 4c  atabase and [SQL
14ce0 49 54 45 5f 42 55 53 59 5d 20 6f 72 20 5b 53 51  ITE_BUSY] or [SQ
14cf0 4c 49 54 45 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b  LITE_IOERR_BLOCK
14d00 45 44 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  ED] is returned.
14d10 0a 2a 2a 20 5e 49 66 20 74 68 65 20 63 61 6c 6c  .** ^If the call
14d20 62 61 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e  back returns non
14d30 2d 7a 65 72 6f 2c 20 74 68 65 6e 20 61 6e 6f 74  -zero, then anot
14d40 68 65 72 20 61 74 74 65 6d 70 74 0a 2a 2a 20 69  her attempt.** i
14d50 73 20 6d 61 64 65 20 74 6f 20 6f 70 65 6e 20 74  s made to open t
14d60 68 65 20 64 61 74 61 62 61 73 65 20 66 6f 72 20  he database for 
14d70 72 65 61 64 69 6e 67 20 61 6e 64 20 74 68 65 20  reading and the 
14d80 63 79 63 6c 65 20 72 65 70 65 61 74 73 2e 0a 2a  cycle repeats..*
14d90 2a 0a 2a 2a 20 54 68 65 20 70 72 65 73 65 6e 63  *.** The presenc
14da0 65 20 6f 66 20 61 20 62 75 73 79 20 68 61 6e 64  e of a busy hand
14db0 6c 65 72 20 64 6f 65 73 20 6e 6f 74 20 67 75 61  ler does not gua
14dc0 72 61 6e 74 65 65 20 74 68 61 74 20 69 74 20 77  rantee that it w
14dd0 69 6c 6c 20 62 65 20 69 6e 76 6f 6b 65 64 0a 2a  ill be invoked.*
14de0 2a 20 77 68 65 6e 20 74 68 65 72 65 20 69 73 20  * when there is 
14df0 6c 6f 63 6b 20 63 6f 6e 74 65 6e 74 69 6f 6e 2e  lock contention.
14e00 20 5e 49 66 20 53 51 4c 69 74 65 20 64 65 74 65   ^If SQLite dete
14e10 72 6d 69 6e 65 73 20 74 68 61 74 20 69 6e 76 6f  rmines that invo
14e20 6b 69 6e 67 20 74 68 65 20 62 75 73 79 0a 2a 2a  king the busy.**
14e30 20 68 61 6e 64 6c 65 72 20 63 6f 75 6c 64 20 72   handler could r
14e40 65 73 75 6c 74 20 69 6e 20 61 20 64 65 61 64 6c  esult in a deadl
14e50 6f 63 6b 2c 20 69 74 20 77 69 6c 6c 20 67 6f 20  ock, it will go 
14e60 61 68 65 61 64 20 61 6e 64 20 72 65 74 75 72 6e  ahead and return
14e70 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 0a 2a   [SQLITE_BUSY].*
14e80 2a 20 6f 72 20 5b 53 51 4c 49 54 45 5f 49 4f 45  * or [SQLITE_IOE
14e90 52 52 5f 42 4c 4f 43 4b 45 44 5d 20 69 6e 73 74  RR_BLOCKED] inst
14ea0 65 61 64 20 6f 66 20 69 6e 76 6f 6b 69 6e 67 20  ead of invoking 
14eb0 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72  the busy handler
14ec0 2e 0a 2a 2a 20 43 6f 6e 73 69 64 65 72 20 61 20  ..** Consider a 
14ed0 73 63 65 6e 61 72 69 6f 20 77 68 65 72 65 20 6f  scenario where o
14ee0 6e 65 20 70 72 6f 63 65 73 73 20 69 73 20 68 6f  ne process is ho
14ef0 6c 64 69 6e 67 20 61 20 72 65 61 64 20 6c 6f 63  lding a read loc
14f00 6b 20 74 68 61 74 0a 2a 2a 20 69 74 20 69 73 20  k that.** it is 
14f10 74 72 79 69 6e 67 20 74 6f 20 70 72 6f 6d 6f 74  trying to promot
14f20 65 20 74 6f 20 61 20 72 65 73 65 72 76 65 64 20  e to a reserved 
14f30 6c 6f 63 6b 20 61 6e 64 0a 2a 2a 20 61 20 73 65  lock and.** a se
14f40 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 69 73 20  cond process is 
14f50 68 6f 6c 64 69 6e 67 20 61 20 72 65 73 65 72 76  holding a reserv
14f60 65 64 20 6c 6f 63 6b 20 74 68 61 74 20 69 74 20  ed lock that it 
14f70 69 73 20 74 72 79 69 6e 67 0a 2a 2a 20 74 6f 20  is trying.** to 
14f80 70 72 6f 6d 6f 74 65 20 74 6f 20 61 6e 20 65 78  promote to an ex
14f90 63 6c 75 73 69 76 65 20 6c 6f 63 6b 2e 20 20 54  clusive lock.  T
14fa0 68 65 20 66 69 72 73 74 20 70 72 6f 63 65 73 73  he first process
14fb0 20 63 61 6e 6e 6f 74 20 70 72 6f 63 65 65 64 0a   cannot proceed.
14fc0 2a 2a 20 62 65 63 61 75 73 65 20 69 74 20 69 73  ** because it is
14fd0 20 62 6c 6f 63 6b 65 64 20 62 79 20 74 68 65 20   blocked by the 
14fe0 73 65 63 6f 6e 64 20 61 6e 64 20 74 68 65 20 73  second and the s
14ff0 65 63 6f 6e 64 20 70 72 6f 63 65 73 73 20 63 61  econd process ca
15000 6e 6e 6f 74 0a 2a 2a 20 70 72 6f 63 65 65 64 20  nnot.** proceed 
15010 62 65 63 61 75 73 65 20 69 74 20 69 73 20 62 6c  because it is bl
15020 6f 63 6b 65 64 20 62 79 20 74 68 65 20 66 69 72  ocked by the fir
15030 73 74 2e 20 20 49 66 20 62 6f 74 68 20 70 72 6f  st.  If both pro
15040 63 65 73 73 65 73 0a 2a 2a 20 69 6e 76 6f 6b 65  cesses.** invoke
15050 20 74 68 65 20 62 75 73 79 20 68 61 6e 64 6c 65   the busy handle
15060 72 73 2c 20 6e 65 69 74 68 65 72 20 77 69 6c 6c  rs, neither will
15070 20 6d 61 6b 65 20 61 6e 79 20 70 72 6f 67 72 65   make any progre
15080 73 73 2e 20 20 54 68 65 72 65 66 6f 72 65 2c 0a  ss.  Therefore,.
15090 2a 2a 20 53 51 4c 69 74 65 20 72 65 74 75 72 6e  ** SQLite return
150a0 73 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d 20  s [SQLITE_BUSY] 
150b0 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 70 72  for the first pr
150c0 6f 63 65 73 73 2c 20 68 6f 70 69 6e 67 20 74 68  ocess, hoping th
150d0 61 74 20 74 68 69 73 0a 2a 2a 20 77 69 6c 6c 20  at this.** will 
150e0 69 6e 64 75 63 65 20 74 68 65 20 66 69 72 73 74  induce the first
150f0 20 70 72 6f 63 65 73 73 20 74 6f 20 72 65 6c 65   process to rele
15100 61 73 65 20 69 74 73 20 72 65 61 64 20 6c 6f 63  ase its read loc
15110 6b 20 61 6e 64 20 61 6c 6c 6f 77 0a 2a 2a 20 74  k and allow.** t
15120 68 65 20 73 65 63 6f 6e 64 20 70 72 6f 63 65 73  he second proces
15130 73 20 74 6f 20 70 72 6f 63 65 65 64 2e 0a 2a 2a  s to proceed..**
15140 0a 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74  .** ^The default
15150 20 62 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 69   busy callback i
15160 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54  s NULL..**.** ^T
15170 68 65 20 5b 53 51 4c 49 54 45 5f 42 55 53 59 5d  he [SQLITE_BUSY]
15180 20 65 72 72 6f 72 20 69 73 20 63 6f 6e 76 65 72   error is conver
15190 74 65 64 20 74 6f 20 5b 53 51 4c 49 54 45 5f 49  ted to [SQLITE_I
151a0 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 0a 2a 2a  OERR_BLOCKED].**
151b0 20 77 68 65 6e 20 53 51 4c 69 74 65 20 69 73 20   when SQLite is 
151c0 69 6e 20 74 68 65 20 6d 69 64 64 6c 65 20 6f 66  in the middle of
151d0 20 61 20 6c 61 72 67 65 20 74 72 61 6e 73 61 63   a large transac
151e0 74 69 6f 6e 20 77 68 65 72 65 20 61 6c 6c 20 74  tion where all t
151f0 68 65 0a 2a 2a 20 63 68 61 6e 67 65 73 20 77 69  he.** changes wi
15200 6c 6c 20 6e 6f 74 20 66 69 74 20 69 6e 74 6f 20  ll not fit into 
15210 74 68 65 20 69 6e 2d 6d 65 6d 6f 72 79 20 63 61  the in-memory ca
15220 63 68 65 2e 20 20 53 51 4c 69 74 65 20 77 69 6c  che.  SQLite wil
15230 6c 0a 2a 2a 20 61 6c 72 65 61 64 79 20 68 6f 6c  l.** already hol
15240 64 20 61 20 52 45 53 45 52 56 45 44 20 6c 6f 63  d a RESERVED loc
15250 6b 20 6f 6e 20 74 68 65 20 64 61 74 61 62 61 73  k on the databas
15260 65 20 66 69 6c 65 2c 20 62 75 74 20 69 74 20 6e  e file, but it n
15270 65 65 64 73 0a 2a 2a 20 74 6f 20 70 72 6f 6d 6f  eeds.** to promo
15280 74 65 20 74 68 69 73 20 6c 6f 63 6b 20 74 6f 20  te this lock to 
15290 45 58 43 4c 55 53 49 56 45 20 73 6f 20 74 68 61  EXCLUSIVE so tha
152a0 74 20 69 74 20 63 61 6e 20 73 70 69 6c 6c 20 63  t it can spill c
152b0 61 63 68 65 0a 2a 2a 20 70 61 67 65 73 20 69 6e  ache.** pages in
152c0 74 6f 20 74 68 65 20 64 61 74 61 62 61 73 65 20  to the database 
152d0 66 69 6c 65 20 77 69 74 68 6f 75 74 20 68 61 72  file without har
152e0 6d 20 74 6f 20 63 6f 6e 63 75 72 72 65 6e 74 0a  m to concurrent.
152f0 2a 2a 20 72 65 61 64 65 72 73 2e 20 20 5e 49 66  ** readers.  ^If
15300 20 69 74 20 69 73 20 75 6e 61 62 6c 65 20 74 6f   it is unable to
15310 20 70 72 6f 6d 6f 74 65 20 74 68 65 20 6c 6f 63   promote the loc
15320 6b 2c 20 74 68 65 6e 20 74 68 65 20 69 6e 2d 6d  k, then the in-m
15330 65 6d 6f 72 79 0a 2a 2a 20 63 61 63 68 65 20 77  emory.** cache w
15340 69 6c 6c 20 62 65 20 6c 65 66 74 20 69 6e 20 61  ill be left in a
15350 6e 20 69 6e 63 6f 6e 73 69 73 74 65 6e 74 20 73  n inconsistent s
15360 74 61 74 65 20 61 6e 64 20 73 6f 20 74 68 65 20  tate and so the 
15370 65 72 72 6f 72 0a 2a 2a 20 63 6f 64 65 20 69 73  error.** code is
15380 20 70 72 6f 6d 6f 74 65 64 20 66 72 6f 6d 20 74   promoted from t
15390 68 65 20 72 65 6c 61 74 69 76 65 6c 79 20 62 65  he relatively be
153a0 6e 69 67 6e 20 5b 53 51 4c 49 54 45 5f 42 55 53  nign [SQLITE_BUS
153b0 59 5d 20 74 6f 0a 2a 2a 20 74 68 65 20 6d 6f 72  Y] to.** the mor
153c0 65 20 73 65 76 65 72 65 20 5b 53 51 4c 49 54 45  e severe [SQLITE
153d0 5f 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e  _IOERR_BLOCKED].
153e0 20 20 5e 54 68 69 73 20 65 72 72 6f 72 20 63 6f    ^This error co
153f0 64 65 20 70 72 6f 6d 6f 74 69 6f 6e 0a 2a 2a 20  de promotion.** 
15400 66 6f 72 63 65 73 20 61 6e 20 61 75 74 6f 6d 61  forces an automa
15410 74 69 63 20 72 6f 6c 6c 62 61 63 6b 20 6f 66 20  tic rollback of 
15420 74 68 65 20 63 68 61 6e 67 65 73 2e 20 20 53 65  the changes.  Se
15430 65 20 74 68 65 0a 2a 2a 20 3c 61 20 68 72 65 66  e the.** <a href
15440 3d 22 2f 63 76 73 74 72 61 63 2f 77 69 6b 69 3f  ="/cvstrac/wiki?
15450 70 3d 43 6f 72 72 75 70 74 69 6f 6e 46 6f 6c 6c  p=CorruptionFoll
15460 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72 22 3e  owingBusyError">
15470 0a 2a 2a 20 43 6f 72 72 75 70 74 69 6f 6e 46 6f  .** CorruptionFo
15480 6c 6c 6f 77 69 6e 67 42 75 73 79 45 72 72 6f 72  llowingBusyError
15490 3c 2f 61 3e 20 77 69 6b 69 20 70 61 67 65 20 66  </a> wiki page f
154a0 6f 72 20 61 20 64 69 73 63 75 73 73 69 6f 6e 20  or a discussion 
154b0 6f 66 20 77 68 79 0a 2a 2a 20 74 68 69 73 20 69  of why.** this i
154c0 73 20 69 6d 70 6f 72 74 61 6e 74 2e 0a 2a 2a 0a  s important..**.
154d0 2a 2a 20 5e 28 54 68 65 72 65 20 63 61 6e 20 6f  ** ^(There can o
154e0 6e 6c 79 20 62 65 20 61 20 73 69 6e 67 6c 65 20  nly be a single 
154f0 62 75 73 79 20 68 61 6e 64 6c 65 72 20 64 65 66  busy handler def
15500 69 6e 65 64 20 66 6f 72 20 65 61 63 68 0a 2a 2a  ined for each.**
15510 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
15520 63 74 69 6f 6e 5d 2e 20 20 53 65 74 74 69 6e 67  ction].  Setting
15530 20 61 20 6e 65 77 20 62 75 73 79 20 68 61 6e 64   a new busy hand
15540 6c 65 72 20 63 6c 65 61 72 73 20 61 6e 79 0a 2a  ler clears any.*
15550 2a 20 70 72 65 76 69 6f 75 73 6c 79 20 73 65 74  * previously set
15560 20 68 61 6e 64 6c 65 72 2e 29 5e 20 20 5e 4e 6f   handler.)^  ^No
15570 74 65 20 74 68 61 74 20 63 61 6c 6c 69 6e 67 20  te that calling 
15580 5b 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69  [sqlite3_busy_ti
15590 6d 65 6f 75 74 28 29 5d 0a 2a 2a 20 77 69 6c 6c  meout()].** will
155a0 20 61 6c 73 6f 20 73 65 74 20 6f 72 20 63 6c 65   also set or cle
155b0 61 72 20 74 68 65 20 62 75 73 79 20 68 61 6e 64  ar the busy hand
155c0 6c 65 72 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 62  ler..**.** The b
155d0 75 73 79 20 63 61 6c 6c 62 61 63 6b 20 73 68 6f  usy callback sho
155e0 75 6c 64 20 6e 6f 74 20 74 61 6b 65 20 61 6e 79  uld not take any
155f0 20 61 63 74 69 6f 6e 73 20 77 68 69 63 68 20 6d   actions which m
15600 6f 64 69 66 79 20 74 68 65 0a 2a 2a 20 64 61 74  odify the.** dat
15610 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
15620 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
15630 65 20 62 75 73 79 20 68 61 6e 64 6c 65 72 2e 20  e busy handler. 
15640 20 41 6e 79 20 73 75 63 68 20 61 63 74 69 6f 6e   Any such action
15650 73 0a 2a 2a 20 72 65 73 75 6c 74 20 69 6e 20 75  s.** result in u
15660 6e 64 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f  ndefined behavio
15670 72 2e 0a 2a 2a 20 0a 2a 2a 20 41 20 62 75 73 79  r..** .** A busy
15680 20 68 61 6e 64 6c 65 72 20 6d 75 73 74 20 6e 6f   handler must no
15690 74 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61  t close the data
156a0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a  base connection.
156b0 2a 2a 20 6f 72 20 5b 70 72 65 70 61 72 65 64 20  ** or [prepared 
156c0 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
156d0 69 6e 76 6f 6b 65 64 20 74 68 65 20 62 75 73 79  invoked the busy
156e0 20 68 61 6e 64 6c 65 72 2e 0a 2a 2f 0a 69 6e 74   handler..*/.int
156f0 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 68 61   sqlite3_busy_ha
15700 6e 64 6c 65 72 28 73 71 6c 69 74 65 33 2a 2c 20  ndler(sqlite3*, 
15710 69 6e 74 28 2a 29 28 76 6f 69 64 2a 2c 69 6e 74  int(*)(void*,int
15720 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a  ), void*);../*.*
15730 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65 74 20  * CAPI3REF: Set 
15740 41 20 42 75 73 79 20 54 69 6d 65 6f 75 74 0a 2a  A Busy Timeout.*
15750 2a 0a 2a 2a 20 5e 54 68 69 73 20 72 6f 75 74 69  *.** ^This routi
15760 6e 65 20 73 65 74 73 20 61 20 5b 73 71 6c 69 74  ne sets a [sqlit
15770 65 33 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 20  e3_busy_handler 
15780 7c 20 62 75 73 79 20 68 61 6e 64 6c 65 72 5d 20  | busy handler] 
15790 74 68 61 74 20 73 6c 65 65 70 73 0a 2a 2a 20 66  that sleeps.** f
157a0 6f 72 20 61 20 73 70 65 63 69 66 69 65 64 20 61  or a specified a
157b0 6d 6f 75 6e 74 20 6f 66 20 74 69 6d 65 20 77 68  mount of time wh
157c0 65 6e 20 61 20 74 61 62 6c 65 20 69 73 20 6c 6f  en a table is lo
157d0 63 6b 65 64 2e 20 20 5e 54 68 65 20 68 61 6e 64  cked.  ^The hand
157e0 6c 65 72 0a 2a 2a 20 77 69 6c 6c 20 73 6c 65 65  ler.** will slee
157f0 70 20 6d 75 6c 74 69 70 6c 65 20 74 69 6d 65 73  p multiple times
15800 20 75 6e 74 69 6c 20 61 74 20 6c 65 61 73 74 20   until at least 
15810 22 6d 73 22 20 6d 69 6c 6c 69 73 65 63 6f 6e 64  "ms" millisecond
15820 73 20 6f 66 20 73 6c 65 65 70 69 6e 67 0a 2a 2a  s of sleeping.**
15830 20 68 61 76 65 20 61 63 63 75 6d 75 6c 61 74 65   have accumulate
15840 64 2e 20 20 5e 41 66 74 65 72 20 61 74 20 6c 65  d.  ^After at le
15850 61 73 74 20 22 6d 73 22 20 6d 69 6c 6c 69 73 65  ast "ms" millise
15860 63 6f 6e 64 73 20 6f 66 20 73 6c 65 65 70 69 6e  conds of sleepin
15870 67 2c 0a 2a 2a 20 74 68 65 20 68 61 6e 64 6c 65  g,.** the handle
15880 72 20 72 65 74 75 72 6e 73 20 30 20 77 68 69 63  r returns 0 whic
15890 68 20 63 61 75 73 65 73 20 5b 73 71 6c 69 74 65  h causes [sqlite
158a0 33 5f 73 74 65 70 28 29 5d 20 74 6f 20 72 65 74  3_step()] to ret
158b0 75 72 6e 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 42  urn.** [SQLITE_B
158c0 55 53 59 5d 20 6f 72 20 5b 53 51 4c 49 54 45 5f  USY] or [SQLITE_
158d0 49 4f 45 52 52 5f 42 4c 4f 43 4b 45 44 5d 2e 0a  IOERR_BLOCKED]..
158e0 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e 67 20 74  **.** ^Calling t
158f0 68 69 73 20 72 6f 75 74 69 6e 65 20 77 69 74 68  his routine with
15900 20 61 6e 20 61 72 67 75 6d 65 6e 74 20 6c 65 73   an argument les
15910 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c 20  s than or equal 
15920 74 6f 20 7a 65 72 6f 0a 2a 2a 20 74 75 72 6e 73  to zero.** turns
15930 20 6f 66 66 20 61 6c 6c 20 62 75 73 79 20 68 61   off all busy ha
15940 6e 64 6c 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ndlers..**.** ^(
15950 54 68 65 72 65 20 63 61 6e 20 6f 6e 6c 79 20 62  There can only b
15960 65 20 61 20 73 69 6e 67 6c 65 20 62 75 73 79 20  e a single busy 
15970 68 61 6e 64 6c 65 72 20 66 6f 72 20 61 20 70 61  handler for a pa
15980 72 74 69 63 75 6c 61 72 0a 2a 2a 20 5b 64 61 74  rticular.** [dat
15990 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
159a0 5d 20 61 6e 79 20 61 6e 79 20 67 69 76 65 6e 20  ] any any given 
159b0 6d 6f 6d 65 6e 74 2e 20 20 49 66 20 61 6e 6f 74  moment.  If anot
159c0 68 65 72 20 62 75 73 79 20 68 61 6e 64 6c 65 72  her busy handler
159d0 0a 2a 2a 20 77 61 73 20 64 65 66 69 6e 65 64 20  .** was defined 
159e0 20 28 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33   (using [sqlite3
159f0 5f 62 75 73 79 5f 68 61 6e 64 6c 65 72 28 29 5d  _busy_handler()]
15a00 29 20 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69  ) prior to calli
15a10 6e 67 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74 69  ng.** this routi
15a20 6e 65 2c 20 74 68 61 74 20 6f 74 68 65 72 20 62  ne, that other b
15a30 75 73 79 20 68 61 6e 64 6c 65 72 20 69 73 20 63  usy handler is c
15a40 6c 65 61 72 65 64 2e 29 5e 0a 2a 2f 0a 69 6e 74  leared.)^.*/.int
15a50 20 73 71 6c 69 74 65 33 5f 62 75 73 79 5f 74 69   sqlite3_busy_ti
15a60 6d 65 6f 75 74 28 73 71 6c 69 74 65 33 2a 2c 20  meout(sqlite3*, 
15a70 69 6e 74 20 6d 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20  int ms);../*.** 
15a80 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 76 65 6e  CAPI3REF: Conven
15a90 69 65 6e 63 65 20 52 6f 75 74 69 6e 65 73 20 46  ience Routines F
15aa0 6f 72 20 52 75 6e 6e 69 6e 67 20 51 75 65 72 69  or Running Queri
15ab0 65 73 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73  es.**.** This is
15ac0 20 61 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66   a legacy interf
15ad0 61 63 65 20 74 68 61 74 20 69 73 20 70 72 65 73  ace that is pres
15ae0 65 72 76 65 64 20 66 6f 72 20 62 61 63 6b 77 61  erved for backwa
15af0 72 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74  rds compatibilit
15b00 79 2e 0a 2a 2a 20 55 73 65 20 6f 66 20 74 68 69  y..** Use of thi
15b10 73 20 69 6e 74 65 72 66 61 63 65 20 69 73 20 6e  s interface is n
15b20 6f 74 20 72 65 63 6f 6d 6d 65 6e 64 65 64 2e 0a  ot recommended..
15b30 2a 2a 0a 2a 2a 20 44 65 66 69 6e 69 74 69 6f 6e  **.** Definition
15b40 3a 20 41 20 3c 62 3e 72 65 73 75 6c 74 20 74 61  : A <b>result ta
15b50 62 6c 65 3c 2f 62 3e 20 69 73 20 6d 65 6d 6f 72  ble</b> is memor
15b60 79 20 64 61 74 61 20 73 74 72 75 63 74 75 72 65  y data structure
15b70 20 63 72 65 61 74 65 64 20 62 79 20 74 68 65 0a   created by the.
15b80 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 67 65 74 5f  ** [sqlite3_get_
15b90 74 61 62 6c 65 28 29 5d 20 69 6e 74 65 72 66 61  table()] interfa
15ba0 63 65 2e 20 20 41 20 72 65 73 75 6c 74 20 74 61  ce.  A result ta
15bb0 62 6c 65 20 72 65 63 6f 72 64 73 20 74 68 65 0a  ble records the.
15bc0 2a 2a 20 63 6f 6d 70 6c 65 74 65 20 71 75 65 72  ** complete quer
15bd0 79 20 72 65 73 75 6c 74 73 20 66 72 6f 6d 20 6f  y results from o
15be0 6e 65 20 6f 72 20 6d 6f 72 65 20 71 75 65 72 69  ne or more queri
15bf0 65 73 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61  es..**.** The ta
15c00 62 6c 65 20 63 6f 6e 63 65 70 74 75 61 6c 6c 79  ble conceptually
15c10 20 68 61 73 20 61 20 6e 75 6d 62 65 72 20 6f 66   has a number of
15c20 20 72 6f 77 73 20 61 6e 64 20 63 6f 6c 75 6d 6e   rows and column
15c30 73 2e 20 20 42 75 74 0a 2a 2a 20 74 68 65 73 65  s.  But.** these
15c40 20 6e 75 6d 62 65 72 73 20 61 72 65 20 6e 6f 74   numbers are not
15c50 20 70 61 72 74 20 6f 66 20 74 68 65 20 72 65 73   part of the res
15c60 75 6c 74 20 74 61 62 6c 65 20 69 74 73 65 6c 66  ult table itself
15c70 2e 20 20 54 68 65 73 65 0a 2a 2a 20 6e 75 6d 62  .  These.** numb
15c80 65 72 73 20 61 72 65 20 6f 62 74 61 69 6e 65 64  ers are obtained
15c90 20 73 65 70 61 72 61 74 65 6c 79 2e 20 20 4c 65   separately.  Le
15ca0 74 20 4e 20 62 65 20 74 68 65 20 6e 75 6d 62 65  t N be the numbe
15cb0 72 20 6f 66 20 72 6f 77 73 0a 2a 2a 20 61 6e 64  r of rows.** and
15cc0 20 4d 20 62 65 20 74 68 65 20 6e 75 6d 62 65 72   M be the number
15cd0 20 6f 66 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 0a   of columns..**.
15ce0 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62 6c  ** A result tabl
15cf0 65 20 69 73 20 61 6e 20 61 72 72 61 79 20 6f 66  e is an array of
15d00 20 70 6f 69 6e 74 65 72 73 20 74 6f 20 7a 65 72   pointers to zer
15d10 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20 55 54 46  o-terminated UTF
15d20 2d 38 20 73 74 72 69 6e 67 73 2e 0a 2a 2a 20 54  -8 strings..** T
15d30 68 65 72 65 20 61 72 65 20 28 4e 2b 31 29 2a 4d  here are (N+1)*M
15d40 20 65 6c 65 6d 65 6e 74 73 20 69 6e 20 74 68 65   elements in the
15d50 20 61 72 72 61 79 2e 20 20 54 68 65 20 66 69 72   array.  The fir
15d60 73 74 20 4d 20 70 6f 69 6e 74 65 72 73 20 70 6f  st M pointers po
15d70 69 6e 74 0a 2a 2a 20 74 6f 20 7a 65 72 6f 2d 74  int.** to zero-t
15d80 65 72 6d 69 6e 61 74 65 64 20 73 74 72 69 6e 67  erminated string
15d90 73 20 74 68 61 74 20 20 63 6f 6e 74 61 69 6e 20  s that  contain 
15da0 74 68 65 20 6e 61 6d 65 73 20 6f 66 20 74 68 65  the names of the
15db0 20 63 6f 6c 75 6d 6e 73 2e 0a 2a 2a 20 54 68 65   columns..** The
15dc0 20 72 65 6d 61 69 6e 69 6e 67 20 65 6e 74 72 69   remaining entri
15dd0 65 73 20 61 6c 6c 20 70 6f 69 6e 74 20 74 6f 20  es all point to 
15de0 71 75 65 72 79 20 72 65 73 75 6c 74 73 2e 20 20  query results.  
15df0 4e 55 4c 4c 20 76 61 6c 75 65 73 20 72 65 73 75  NULL values resu
15e00 6c 74 0a 2a 2a 20 69 6e 20 4e 55 4c 4c 20 70 6f  lt.** in NULL po
15e10 69 6e 74 65 72 73 2e 20 20 41 6c 6c 20 6f 74 68  inters.  All oth
15e20 65 72 20 76 61 6c 75 65 73 20 61 72 65 20 69 6e  er values are in
15e30 20 74 68 65 69 72 20 55 54 46 2d 38 20 7a 65 72   their UTF-8 zer
15e40 6f 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20  o-terminated.** 
15e50 73 74 72 69 6e 67 20 72 65 70 72 65 73 65 6e 74  string represent
15e60 61 74 69 6f 6e 20 61 73 20 72 65 74 75 72 6e 65  ation as returne
15e70 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
15e80 6c 75 6d 6e 5f 74 65 78 74 28 29 5d 2e 0a 2a 2a  lumn_text()]..**
15e90 0a 2a 2a 20 41 20 72 65 73 75 6c 74 20 74 61 62  .** A result tab
15ea0 6c 65 20 6d 69 67 68 74 20 63 6f 6e 73 69 73 74  le might consist
15eb0 20 6f 66 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 20   of one or more 
15ec0 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f  memory allocatio
15ed0 6e 73 2e 0a 2a 2a 20 49 74 20 69 73 20 6e 6f 74  ns..** It is not
15ee0 20 73 61 66 65 20 74 6f 20 70 61 73 73 20 61 20   safe to pass a 
15ef0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 64 69 72  result table dir
15f00 65 63 74 6c 79 20 74 6f 20 5b 73 71 6c 69 74 65  ectly to [sqlite
15f10 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 20 41 20  3_free()]..** A 
15f20 72 65 73 75 6c 74 20 74 61 62 6c 65 20 73 68 6f  result table sho
15f30 75 6c 64 20 62 65 20 64 65 61 6c 6c 6f 63 61 74  uld be deallocat
15f40 65 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65  ed using [sqlite
15f50 33 5f 66 72 65 65 5f 74 61 62 6c 65 28 29 5d 2e  3_free_table()].
15f60 0a 2a 2a 0a 2a 2a 20 5e 28 41 73 20 61 6e 20 65  .**.** ^(As an e
15f70 78 61 6d 70 6c 65 20 6f 66 20 74 68 65 20 72 65  xample of the re
15f80 73 75 6c 74 20 74 61 62 6c 65 20 66 6f 72 6d 61  sult table forma
15f90 74 2c 20 73 75 70 70 6f 73 65 20 61 20 71 75 65  t, suppose a que
15fa0 72 79 20 72 65 73 75 6c 74 0a 2a 2a 20 69 73 20  ry result.** is 
15fb0 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a  as follows:.**.*
15fc0 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70  * <blockquote><p
15fd0 72 65 3e 0a 2a 2a 20 20 20 20 20 20 20 20 4e 61  re>.**        Na
15fe0 6d 65 20 20 20 20 20 20 20 20 7c 20 41 67 65 0a  me        | Age.
15ff0 2a 2a 20 20 20 20 20 20 20 20 2d 2d 2d 2d 2d 2d  **        ------
16000 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d 2d  ----------------
16010 2d 0a 2a 2a 20 20 20 20 20 20 20 20 41 6c 69 63  -.**        Alic
16020 65 20 20 20 20 20 20 20 7c 20 34 33 0a 2a 2a 20  e       | 43.** 
16030 20 20 20 20 20 20 20 42 6f 62 20 20 20 20 20 20         Bob      
16040 20 20 20 7c 20 32 38 0a 2a 2a 20 20 20 20 20 20     | 28.**      
16050 20 20 43 69 6e 64 79 20 20 20 20 20 20 20 7c 20    Cindy       | 
16060 32 31 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c  21.** </pre></bl
16070 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20  ockquote>.**.** 
16080 54 68 65 72 65 20 61 72 65 20 74 77 6f 20 63 6f  There are two co
16090 6c 75 6d 6e 20 28 4d 3d 3d 32 29 20 61 6e 64 20  lumn (M==2) and 
160a0 74 68 72 65 65 20 72 6f 77 73 20 28 4e 3d 3d 33  three rows (N==3
160b0 29 2e 20 20 54 68 75 73 20 74 68 65 0a 2a 2a 20  ).  Thus the.** 
160c0 72 65 73 75 6c 74 20 74 61 62 6c 65 20 68 61 73  result table has
160d0 20 38 20 65 6e 74 72 69 65 73 2e 20 20 53 75 70   8 entries.  Sup
160e0 70 6f 73 65 20 74 68 65 20 72 65 73 75 6c 74 20  pose the result 
160f0 74 61 62 6c 65 20 69 73 20 73 74 6f 72 65 64 0a  table is stored.
16100 2a 2a 20 69 6e 20 61 6e 20 61 72 72 61 79 20 6e  ** in an array n
16110 61 6d 65 73 20 61 7a 52 65 73 75 6c 74 2e 20 20  ames azResult.  
16120 54 68 65 6e 20 61 7a 52 65 73 75 6c 74 20 68 6f  Then azResult ho
16130 6c 64 73 20 74 68 69 73 20 63 6f 6e 74 65 6e 74  lds this content
16140 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
16150 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 20 20  ote><pre>.**    
16160 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31      azResult&#91
16170 3b 30 5d 20 3d 20 22 4e 61 6d 65 22 3b 0a 2a 2a  ;0] = "Name";.**
16180 20 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74          azResult
16190 26 23 39 31 3b 31 5d 20 3d 20 22 41 67 65 22 3b  &#91;1] = "Age";
161a0 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65 73  .**        azRes
161b0 75 6c 74 26 23 39 31 3b 32 5d 20 3d 20 22 41 6c  ult&#91;2] = "Al
161c0 69 63 65 22 3b 0a 2a 2a 20 20 20 20 20 20 20 20  ice";.**        
161d0 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 33 5d 20  azResult&#91;3] 
161e0 3d 20 22 34 33 22 3b 0a 2a 2a 20 20 20 20 20 20  = "43";.**      
161f0 20 20 61 7a 52 65 73 75 6c 74 26 23 39 31 3b 34    azResult&#91;4
16200 5d 20 3d 20 22 42 6f 62 22 3b 0a 2a 2a 20 20 20  ] = "Bob";.**   
16210 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26 23 39       azResult&#9
16220 31 3b 35 5d 20 3d 20 22 32 38 22 3b 0a 2a 2a 20  1;5] = "28";.** 
16230 20 20 20 20 20 20 20 61 7a 52 65 73 75 6c 74 26         azResult&
16240 23 39 31 3b 36 5d 20 3d 20 22 43 69 6e 64 79 22  #91;6] = "Cindy"
16250 3b 0a 2a 2a 20 20 20 20 20 20 20 20 61 7a 52 65  ;.**        azRe
16260 73 75 6c 74 26 23 39 31 3b 37 5d 20 3d 20 22 32  sult&#91;7] = "2
16270 31 22 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c 2f 62  1";.** </pre></b
16280 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a 0a  lockquote>)^.**.
16290 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
162a0 67 65 74 5f 74 61 62 6c 65 28 29 20 66 75 6e 63  get_table() func
162b0 74 69 6f 6e 20 65 76 61 6c 75 61 74 65 73 20 6f  tion evaluates o
162c0 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a 20 73 65  ne or more.** se
162d0 6d 69 63 6f 6c 6f 6e 2d 73 65 70 61 72 61 74 65  micolon-separate
162e0 64 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 73  d SQL statements
162f0 20 69 6e 20 74 68 65 20 7a 65 72 6f 2d 74 65 72   in the zero-ter
16300 6d 69 6e 61 74 65 64 20 55 54 46 2d 38 0a 2a 2a  minated UTF-8.**
16310 20 73 74 72 69 6e 67 20 6f 66 20 69 74 73 20 32   string of its 2
16320 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61 6e 64  nd parameter and
16330 20 72 65 74 75 72 6e 73 20 61 20 72 65 73 75 6c   returns a resul
16340 74 20 74 61 62 6c 65 20 74 6f 20 74 68 65 0a 2a  t table to the.*
16350 2a 20 70 6f 69 6e 74 65 72 20 67 69 76 65 6e 20  * pointer given 
16360 69 6e 20 69 74 73 20 33 72 64 20 70 61 72 61 6d  in its 3rd param
16370 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 41 66 74 65  eter..**.** Afte
16380 72 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  r the applicatio
16390 6e 20 68 61 73 20 66 69 6e 69 73 68 65 64 20 77  n has finished w
163a0 69 74 68 20 74 68 65 20 72 65 73 75 6c 74 20 66  ith the result f
163b0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 67 65 74 5f  rom sqlite3_get_
163c0 74 61 62 6c 65 28 29 2c 0a 2a 2a 20 69 74 20 6d  table(),.** it m
163d0 75 73 74 20 70 61 73 73 20 74 68 65 20 72 65 73  ust pass the res
163e0 75 6c 74 20 74 61 62 6c 65 20 70 6f 69 6e 74 65  ult table pointe
163f0 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 66 72 65  r to sqlite3_fre
16400 65 5f 74 61 62 6c 65 28 29 20 69 6e 20 6f 72 64  e_table() in ord
16410 65 72 20 74 6f 0a 2a 2a 20 72 65 6c 65 61 73 65  er to.** release
16420 20 74 68 65 20 6d 65 6d 6f 72 79 20 74 68 61 74   the memory that
16430 20 77 61 73 20 6d 61 6c 6c 6f 63 65 64 2e 20 20   was malloced.  
16440 42 65 63 61 75 73 65 20 6f 66 20 74 68 65 20 77  Because of the w
16450 61 79 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74  ay the.** [sqlit
16460 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 20 68 61 70  e3_malloc()] hap
16470 70 65 6e 73 20 77 69 74 68 69 6e 20 73 71 6c 69  pens within sqli
16480 74 65 33 5f 67 65 74 5f 74 61 62 6c 65 28 29 2c  te3_get_table(),
16490 20 74 68 65 20 63 61 6c 6c 69 6e 67 0a 2a 2a 20   the calling.** 
164a0 66 75 6e 63 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  function must no
164b0 74 20 74 72 79 20 74 6f 20 63 61 6c 6c 20 5b 73  t try to call [s
164c0 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 64  qlite3_free()] d
164d0 69 72 65 63 74 6c 79 2e 20 20 4f 6e 6c 79 0a 2a  irectly.  Only.*
164e0 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 5f  * [sqlite3_free_
164f0 74 61 62 6c 65 28 29 5d 20 69 73 20 61 62 6c 65  table()] is able
16500 20 74 6f 20 72 65 6c 65 61 73 65 20 74 68 65 20   to release the 
16510 6d 65 6d 6f 72 79 20 70 72 6f 70 65 72 6c 79 20  memory properly 
16520 61 6e 64 20 73 61 66 65 6c 79 2e 0a 2a 2a 0a 2a  and safely..**.*
16530 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f 67 65  * The sqlite3_ge
16540 74 5f 74 61 62 6c 65 28 29 20 69 6e 74 65 72 66  t_table() interf
16550 61 63 65 20 69 73 20 69 6d 70 6c 65 6d 65 6e 74  ace is implement
16560 65 64 20 61 73 20 61 20 77 72 61 70 70 65 72 20  ed as a wrapper 
16570 61 72 6f 75 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74  around.** [sqlit
16580 65 33 5f 65 78 65 63 28 29 5d 2e 20 20 54 68 65  e3_exec()].  The
16590 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62   sqlite3_get_tab
165a0 6c 65 28 29 20 72 6f 75 74 69 6e 65 20 64 6f 65  le() routine doe
165b0 73 20 6e 6f 74 20 68 61 76 65 20 61 63 63 65 73  s not have acces
165c0 73 0a 2a 2a 20 74 6f 20 61 6e 79 20 69 6e 74 65  s.** to any inte
165d0 72 6e 61 6c 20 64 61 74 61 20 73 74 72 75 63 74  rnal data struct
165e0 75 72 65 73 20 6f 66 20 53 51 4c 69 74 65 2e 20  ures of SQLite. 
165f0 20 49 74 20 75 73 65 73 20 6f 6e 6c 79 20 74 68   It uses only th
16600 65 20 70 75 62 6c 69 63 0a 2a 2a 20 69 6e 74 65  e public.** inte
16610 72 66 61 63 65 20 64 65 66 69 6e 65 64 20 68 65  rface defined he
16620 72 65 2e 20 20 41 73 20 61 20 63 6f 6e 73 65 71  re.  As a conseq
16630 75 65 6e 63 65 2c 20 65 72 72 6f 72 73 20 74 68  uence, errors th
16640 61 74 20 6f 63 63 75 72 20 69 6e 20 74 68 65 0a  at occur in the.
16650 2a 2a 20 77 72 61 70 70 65 72 20 6c 61 79 65 72  ** wrapper layer
16660 20 6f 75 74 73 69 64 65 20 6f 66 20 74 68 65 20   outside of the 
16670 69 6e 74 65 72 6e 61 6c 20 5b 73 71 6c 69 74 65  internal [sqlite
16680 33 5f 65 78 65 63 28 29 5d 20 63 61 6c 6c 20 61  3_exec()] call a
16690 72 65 20 6e 6f 74 0a 2a 2a 20 72 65 66 6c 65 63  re not.** reflec
166a0 74 65 64 20 69 6e 20 73 75 62 73 65 71 75 65 6e  ted in subsequen
166b0 74 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69  t calls to [sqli
166c0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 6f  te3_errcode()] o
166d0 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  r.** [sqlite3_er
166e0 72 6d 73 67 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20  rmsg()]..*/.int 
166f0 73 71 6c 69 74 65 33 5f 67 65 74 5f 74 61 62 6c  sqlite3_get_tabl
16700 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62  e(.  sqlite3 *db
16710 2c 20 20 20 20 20 20 20 20 20 20 2f 2a 20 41 6e  ,          /* An
16720 20 6f 70 65 6e 20 64 61 74 61 62 61 73 65 20 2a   open database *
16730 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
16740 7a 53 71 6c 2c 20 20 20 20 20 2f 2a 20 53 51 4c  zSql,     /* SQL
16750 20 74 6f 20 62 65 20 65 76 61 6c 75 61 74 65 64   to be evaluated
16760 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a 2a 70 61   */.  char ***pa
16770 7a 52 65 73 75 6c 74 2c 20 20 20 20 2f 2a 20 52  zResult,    /* R
16780 65 73 75 6c 74 73 20 6f 66 20 74 68 65 20 71 75  esults of the qu
16790 65 72 79 20 2a 2f 0a 20 20 69 6e 74 20 2a 70 6e  ery */.  int *pn
167a0 52 6f 77 2c 20 20 20 20 20 20 20 20 20 20 20 2f  Row,           /
167b0 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73 75  * Number of resu
167c0 6c 74 20 72 6f 77 73 20 77 72 69 74 74 65 6e 20  lt rows written 
167d0 68 65 72 65 20 2a 2f 0a 20 20 69 6e 74 20 2a 70  here */.  int *p
167e0 6e 43 6f 6c 75 6d 6e 2c 20 20 20 20 20 20 20 20  nColumn,        
167f0 2f 2a 20 4e 75 6d 62 65 72 20 6f 66 20 72 65 73  /* Number of res
16800 75 6c 74 20 63 6f 6c 75 6d 6e 73 20 77 72 69 74  ult columns writ
16810 74 65 6e 20 68 65 72 65 20 2a 2f 0a 20 20 63 68  ten here */.  ch
16820 61 72 20 2a 2a 70 7a 45 72 72 6d 73 67 20 20 20  ar **pzErrmsg   
16830 20 20 20 20 2f 2a 20 45 72 72 6f 72 20 6d 73 67      /* Error msg
16840 20 77 72 69 74 74 65 6e 20 68 65 72 65 20 2a 2f   written here */
16850 0a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  .);.void sqlite3
16860 5f 66 72 65 65 5f 74 61 62 6c 65 28 63 68 61 72  _free_table(char
16870 20 2a 2a 72 65 73 75 6c 74 29 3b 0a 0a 2f 2a 0a   **result);../*.
16880 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 6f 72  ** CAPI3REF: For
16890 6d 61 74 74 65 64 20 53 74 72 69 6e 67 20 50 72  matted String Pr
168a0 69 6e 74 69 6e 67 20 46 75 6e 63 74 69 6f 6e 73  inting Functions
168b0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75  .**.** These rou
168c0 74 69 6e 65 73 20 61 72 65 20 77 6f 72 6b 2d 61  tines are work-a
168d0 6c 69 6b 65 73 20 6f 66 20 74 68 65 20 22 70 72  likes of the "pr
168e0 69 6e 74 66 28 29 22 20 66 61 6d 69 6c 79 20 6f  intf()" family o
168f0 66 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 66  f functions.** f
16900 72 6f 6d 20 74 68 65 20 73 74 61 6e 64 61 72 64  rom the standard
16910 20 43 20 6c 69 62 72 61 72 79 2e 0a 2a 2a 0a 2a   C library..**.*
16920 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
16930 70 72 69 6e 74 66 28 29 20 61 6e 64 20 73 71 6c  printf() and sql
16940 69 74 65 33 5f 76 6d 70 72 69 6e 74 66 28 29 20  ite3_vmprintf() 
16950 72 6f 75 74 69 6e 65 73 20 77 72 69 74 65 20 74  routines write t
16960 68 65 69 72 0a 2a 2a 20 72 65 73 75 6c 74 73 20  heir.** results 
16970 69 6e 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61  into memory obta
16980 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74  ined from [sqlit
16990 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2a  e3_malloc()]..**
169a0 20 54 68 65 20 73 74 72 69 6e 67 73 20 72 65 74   The strings ret
169b0 75 72 6e 65 64 20 62 79 20 74 68 65 73 65 20 74  urned by these t
169c0 77 6f 20 72 6f 75 74 69 6e 65 73 20 73 68 6f 75  wo routines shou
169d0 6c 64 20 62 65 0a 2a 2a 20 72 65 6c 65 61 73 65  ld be.** release
169e0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 66 72  d by [sqlite3_fr
169f0 65 65 28 29 5d 2e 20 20 5e 42 6f 74 68 20 72 6f  ee()].  ^Both ro
16a00 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 61 0a  utines return a.
16a10 2a 2a 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  ** NULL pointer 
16a20 69 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  if [sqlite3_mall
16a30 6f 63 28 29 5d 20 69 73 20 75 6e 61 62 6c 65 20  oc()] is unable 
16a40 74 6f 20 61 6c 6c 6f 63 61 74 65 20 65 6e 6f 75  to allocate enou
16a50 67 68 0a 2a 2a 20 6d 65 6d 6f 72 79 20 74 6f 20  gh.** memory to 
16a60 68 6f 6c 64 20 74 68 65 20 72 65 73 75 6c 74 69  hold the resulti
16a70 6e 67 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a 2a 2a  ng string..**.**
16a80 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33 5f 73   ^(The sqlite3_s
16a90 6e 70 72 69 6e 74 66 28 29 20 72 6f 75 74 69 6e  nprintf() routin
16aa0 65 20 69 73 20 73 69 6d 69 6c 61 72 20 74 6f 20  e is similar to 
16ab0 22 73 6e 70 72 69 6e 74 66 28 29 22 20 66 72 6f  "snprintf()" fro
16ac0 6d 0a 2a 2a 20 74 68 65 20 73 74 61 6e 64 61 72  m.** the standar
16ad0 64 20 43 20 6c 69 62 72 61 72 79 2e 20 20 54 68  d C library.  Th
16ae0 65 20 72 65 73 75 6c 74 20 69 73 20 77 72 69 74  e result is writ
16af0 74 65 6e 20 69 6e 74 6f 20 74 68 65 0a 2a 2a 20  ten into the.** 
16b00 62 75 66 66 65 72 20 73 75 70 70 6c 69 65 64 20  buffer supplied 
16b10 61 73 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61  as the second pa
16b20 72 61 6d 65 74 65 72 20 77 68 6f 73 65 20 73 69  rameter whose si
16b30 7a 65 20 69 73 20 67 69 76 65 6e 20 62 79 0a 2a  ze is given by.*
16b40 2a 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  * the first para
16b50 6d 65 74 65 72 2e 20 4e 6f 74 65 20 74 68 61 74  meter. Note that
16b60 20 74 68 65 20 6f 72 64 65 72 20 6f 66 20 74 68   the order of th
16b70 65 0a 2a 2a 20 66 69 72 73 74 20 74 77 6f 20 70  e.** first two p
16b80 61 72 61 6d 65 74 65 72 73 20 69 73 20 72 65 76  arameters is rev
16b90 65 72 73 65 64 20 66 72 6f 6d 20 73 6e 70 72 69  ersed from snpri
16ba0 6e 74 66 28 29 2e 29 5e 20 20 54 68 69 73 20 69  ntf().)^  This i
16bb0 73 20 61 6e 0a 2a 2a 20 68 69 73 74 6f 72 69 63  s an.** historic
16bc0 61 6c 20 61 63 63 69 64 65 6e 74 20 74 68 61 74  al accident that
16bd0 20 63 61 6e 6e 6f 74 20 62 65 20 66 69 78 65 64   cannot be fixed
16be0 20 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e   without breakin
16bf0 67 0a 2a 2a 20 62 61 63 6b 77 61 72 64 73 20 63  g.** backwards c
16c00 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 20 20 5e  ompatibility.  ^
16c10 28 4e 6f 74 65 20 61 6c 73 6f 20 74 68 61 74 20  (Note also that 
16c20 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
16c30 28 29 0a 2a 2a 20 72 65 74 75 72 6e 73 20 61 20  ().** returns a 
16c40 70 6f 69 6e 74 65 72 20 74 6f 20 69 74 73 20 62  pointer to its b
16c50 75 66 66 65 72 20 69 6e 73 74 65 61 64 20 6f 66  uffer instead of
16c60 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 0a 2a   the number of.*
16c70 2a 20 63 68 61 72 61 63 74 65 72 73 20 61 63 74  * characters act
16c80 75 61 6c 6c 79 20 77 72 69 74 74 65 6e 20 69 6e  ually written in
16c90 74 6f 20 74 68 65 20 62 75 66 66 65 72 2e 29 5e  to the buffer.)^
16ca0 20 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 0a    We admit that.
16cb0 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66  ** the number of
16cc0 20 63 68 61 72 61 63 74 65 72 73 20 77 72 69 74   characters writ
16cd0 74 65 6e 20 77 6f 75 6c 64 20 62 65 20 61 20 6d  ten would be a m
16ce0 6f 72 65 20 75 73 65 66 75 6c 20 72 65 74 75 72  ore useful retur
16cf0 6e 0a 2a 2a 20 76 61 6c 75 65 20 62 75 74 20 77  n.** value but w
16d00 65 20 63 61 6e 6e 6f 74 20 63 68 61 6e 67 65 20  e cannot change 
16d10 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
16d20 6f 6e 20 6f 66 20 73 71 6c 69 74 65 33 5f 73 6e  on of sqlite3_sn
16d30 70 72 69 6e 74 66 28 29 0a 2a 2a 20 6e 6f 77 20  printf().** now 
16d40 77 69 74 68 6f 75 74 20 62 72 65 61 6b 69 6e 67  without breaking
16d50 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 2e 0a   compatibility..
16d60 2a 2a 0a 2a 2a 20 5e 41 73 20 6c 6f 6e 67 20 61  **.** ^As long a
16d70 73 20 74 68 65 20 62 75 66 66 65 72 20 73 69 7a  s the buffer siz
16d80 65 20 69 73 20 67 72 65 61 74 65 72 20 74 68 61  e is greater tha
16d90 6e 20 7a 65 72 6f 2c 20 73 71 6c 69 74 65 33 5f  n zero, sqlite3_
16da0 73 6e 70 72 69 6e 74 66 28 29 0a 2a 2a 20 67 75  snprintf().** gu
16db0 61 72 61 6e 74 65 65 73 20 74 68 61 74 20 74 68  arantees that th
16dc0 65 20 62 75 66 66 65 72 20 69 73 20 61 6c 77 61  e buffer is alwa
16dd0 79 73 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  ys zero-terminat
16de0 65 64 2e 20 20 5e 54 68 65 20 66 69 72 73 74 0a  ed.  ^The first.
16df0 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 22 6e 22  ** parameter "n"
16e00 20 69 73 20 74 68 65 20 74 6f 74 61 6c 20 73 69   is the total si
16e10 7a 65 20 6f 66 20 74 68 65 20 62 75 66 66 65 72  ze of the buffer
16e20 2c 20 69 6e 63 6c 75 64 69 6e 67 20 73 70 61 63  , including spac
16e30 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20 7a 65 72  e for.** the zer
16e40 6f 20 74 65 72 6d 69 6e 61 74 6f 72 2e 20 20 53  o terminator.  S
16e50 6f 20 74 68 65 20 6c 6f 6e 67 65 73 74 20 73 74  o the longest st
16e60 72 69 6e 67 20 74 68 61 74 20 63 61 6e 20 62 65  ring that can be
16e70 20 63 6f 6d 70 6c 65 74 65 6c 79 0a 2a 2a 20 77   completely.** w
16e80 72 69 74 74 65 6e 20 77 69 6c 6c 20 62 65 20 6e  ritten will be n
16e90 2d 31 20 63 68 61 72 61 63 74 65 72 73 2e 0a 2a  -1 characters..*
16ea0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
16eb0 33 5f 76 73 6e 70 72 69 6e 74 66 28 29 20 72 6f  3_vsnprintf() ro
16ec0 75 74 69 6e 65 20 69 73 20 61 20 76 61 72 61 72  utine is a varar
16ed0 67 73 20 76 65 72 73 69 6f 6e 20 6f 66 20 73 71  gs version of sq
16ee0 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66 28 29  lite3_snprintf()
16ef0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f  ..**.** These ro
16f00 75 74 69 6e 65 73 20 61 6c 6c 20 69 6d 70 6c 65  utines all imple
16f10 6d 65 6e 74 20 73 6f 6d 65 20 61 64 64 69 74 69  ment some additi
16f20 6f 6e 61 6c 20 66 6f 72 6d 61 74 74 69 6e 67 0a  onal formatting.
16f30 2a 2a 20 6f 70 74 69 6f 6e 73 20 74 68 61 74 20  ** options that 
16f40 61 72 65 20 75 73 65 66 75 6c 20 66 6f 72 20 63  are useful for c
16f50 6f 6e 73 74 72 75 63 74 69 6e 67 20 53 51 4c 20  onstructing SQL 
16f60 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 20 41  statements..** A
16f70 6c 6c 20 6f 66 20 74 68 65 20 75 73 75 61 6c 20  ll of the usual 
16f80 70 72 69 6e 74 66 28 29 20 66 6f 72 6d 61 74 74  printf() formatt
16f90 69 6e 67 20 6f 70 74 69 6f 6e 73 20 61 70 70 6c  ing options appl
16fa0 79 2e 20 20 49 6e 20 61 64 64 69 74 69 6f 6e 2c  y.  In addition,
16fb0 20 74 68 65 72 65 0a 2a 2a 20 69 73 20 61 72 65   there.** is are
16fc0 20 22 25 71 22 2c 20 22 25 51 22 2c 20 61 6e 64   "%q", "%Q", and
16fd0 20 22 25 7a 22 20 6f 70 74 69 6f 6e 73 2e 0a 2a   "%z" options..*
16fe0 2a 0a 2a 2a 20 5e 28 54 68 65 20 25 71 20 6f 70  *.** ^(The %q op
16ff0 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69 6b 65 20  tion works like 
17000 25 73 20 69 6e 20 74 68 61 74 20 69 74 20 73 75  %s in that it su
17010 62 73 74 69 74 75 74 65 73 20 61 20 6e 75 6c 6c  bstitutes a null
17020 2d 74 65 72 6d 69 6e 61 74 65 64 0a 2a 2a 20 73  -terminated.** s
17030 74 72 69 6e 67 20 66 72 6f 6d 20 74 68 65 20 61  tring from the a
17040 72 67 75 6d 65 6e 74 20 6c 69 73 74 2e 20 20 42  rgument list.  B
17050 75 74 20 25 71 20 61 6c 73 6f 20 64 6f 75 62 6c  ut %q also doubl
17060 65 73 20 65 76 65 72 79 20 27 5c 27 27 20 63 68  es every '\'' ch
17070 61 72 61 63 74 65 72 2e 0a 2a 2a 20 25 71 20 69  aracter..** %q i
17080 73 20 64 65 73 69 67 6e 65 64 20 66 6f 72 20 75  s designed for u
17090 73 65 20 69 6e 73 69 64 65 20 61 20 73 74 72 69  se inside a stri
170a0 6e 67 20 6c 69 74 65 72 61 6c 2e 29 5e 20 20 42  ng literal.)^  B
170b0 79 20 64 6f 75 62 6c 69 6e 67 20 65 61 63 68 20  y doubling each 
170c0 27 5c 27 27 0a 2a 2a 20 63 68 61 72 61 63 74 65  '\''.** characte
170d0 72 20 69 74 20 65 73 63 61 70 65 73 20 74 68 61  r it escapes tha
170e0 74 20 63 68 61 72 61 63 74 65 72 20 61 6e 64 20  t character and 
170f0 61 6c 6c 6f 77 73 20 69 74 20 74 6f 20 62 65 20  allows it to be 
17100 69 6e 73 65 72 74 65 64 20 69 6e 74 6f 0a 2a 2a  inserted into.**
17110 20 74 68 65 20 73 74 72 69 6e 67 2e 0a 2a 2a 0a   the string..**.
17120 2a 2a 20 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20  ** For example, 
17130 61 73 73 75 6d 65 20 74 68 65 20 73 74 72 69 6e  assume the strin
17140 67 20 76 61 72 69 61 62 6c 65 20 7a 54 65 78 74  g variable zText
17150 20 63 6f 6e 74 61 69 6e 73 20 74 65 78 74 20 61   contains text a
17160 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a  s follows:.**.**
17170 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72   <blockquote><pr
17180 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a 54 65  e>.**  char *zTe
17190 78 74 20 3d 20 22 49 74 27 73 20 61 20 68 61 70  xt = "It's a hap
171a0 70 79 20 64 61 79 21 22 3b 0a 2a 2a 20 3c 2f 70  py day!";.** </p
171b0 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  re></blockquote>
171c0 0a 2a 2a 0a 2a 2a 20 4f 6e 65 20 63 61 6e 20 75  .**.** One can u
171d0 73 65 20 74 68 69 73 20 74 65 78 74 20 69 6e 20  se this text in 
171e0 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
171f0 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a 2a 0a   as follows:.**.
17200 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c  ** <blockquote><
17210 70 72 65 3e 0a 2a 2a 20 20 63 68 61 72 20 2a 7a  pre>.**  char *z
17220 53 51 4c 20 3d 20 73 71 6c 69 74 65 33 5f 6d 70  SQL = sqlite3_mp
17230 72 69 6e 74 66 28 22 49 4e 53 45 52 54 20 49 4e  rintf("INSERT IN
17240 54 4f 20 74 61 62 6c 65 20 56 41 4c 55 45 53 28  TO table VALUES(
17250 27 25 71 27 29 22 2c 20 7a 54 65 78 74 29 3b 0a  '%q')", zText);.
17260 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78 65 63  **  sqlite3_exec
17270 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20 30 2c  (db, zSQL, 0, 0,
17280 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33   0);.**  sqlite3
17290 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a 2a 20  _free(zSQL);.** 
172a0 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f  </pre></blockquo
172b0 74 65 3e 0a 2a 2a 0a 2a 2a 20 42 65 63 61 75 73  te>.**.** Becaus
172c0 65 20 74 68 65 20 25 71 20 66 6f 72 6d 61 74 20  e the %q format 
172d0 73 74 72 69 6e 67 20 69 73 20 75 73 65 64 2c 20  string is used, 
172e0 74 68 65 20 27 5c 27 27 20 63 68 61 72 61 63 74  the '\'' charact
172f0 65 72 20 69 6e 20 7a 54 65 78 74 0a 2a 2a 20 69  er in zText.** i
17300 73 20 65 73 63 61 70 65 64 20 61 6e 64 20 74 68  s escaped and th
17310 65 20 53 51 4c 20 67 65 6e 65 72 61 74 65 64 20  e SQL generated 
17320 69 73 20 61 73 20 66 6f 6c 6c 6f 77 73 3a 0a 2a  is as follows:.*
17330 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f 74 65  *.** <blockquote
17340 3e 3c 70 72 65 3e 0a 2a 2a 20 20 49 4e 53 45 52  ><pre>.**  INSER
17350 54 20 49 4e 54 4f 20 74 61 62 6c 65 31 20 56 41  T INTO table1 VA
17360 4c 55 45 53 28 27 49 74 27 27 73 20 61 20 68 61  LUES('It''s a ha
17370 70 70 79 20 64 61 79 21 27 29 0a 2a 2a 20 3c 2f  ppy day!').** </
17380 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65  pre></blockquote
17390 3e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 69 73 20  >.**.** This is 
173a0 63 6f 72 72 65 63 74 2e 20 20 48 61 64 20 77 65  correct.  Had we
173b0 20 75 73 65 64 20 25 73 20 69 6e 73 74 65 61 64   used %s instead
173c0 20 6f 66 20 25 71 2c 20 74 68 65 20 67 65 6e 65   of %q, the gene
173d0 72 61 74 65 64 20 53 51 4c 0a 2a 2a 20 77 6f 75  rated SQL.** wou
173e0 6c 64 20 68 61 76 65 20 6c 6f 6f 6b 65 64 20 6c  ld have looked l
173f0 69 6b 65 20 74 68 69 73 3a 0a 2a 2a 0a 2a 2a 20  ike this:.**.** 
17400 3c 62 6c 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65  <blockquote><pre
17410 3e 0a 2a 2a 20 20 49 4e 53 45 52 54 20 49 4e 54  >.**  INSERT INT
17420 4f 20 74 61 62 6c 65 31 20 56 41 4c 55 45 53 28  O table1 VALUES(
17430 27 49 74 27 73 20 61 20 68 61 70 70 79 20 64 61  'It's a happy da
17440 79 21 27 29 3b 0a 2a 2a 20 3c 2f 70 72 65 3e 3c  y!');.** </pre><
17450 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 0a  /blockquote>.**.
17460 2a 2a 20 54 68 69 73 20 73 65 63 6f 6e 64 20 65  ** This second e
17470 78 61 6d 70 6c 65 20 69 73 20 61 6e 20 53 51 4c  xample is an SQL
17480 20 73 79 6e 74 61 78 20 65 72 72 6f 72 2e 20 20   syntax error.  
17490 41 73 20 61 20 67 65 6e 65 72 61 6c 20 72 75 6c  As a general rul
174a0 65 20 79 6f 75 20 73 68 6f 75 6c 64 0a 2a 2a 20  e you should.** 
174b0 61 6c 77 61 79 73 20 75 73 65 20 25 71 20 69 6e  always use %q in
174c0 73 74 65 61 64 20 6f 66 20 25 73 20 77 68 65 6e  stead of %s when
174d0 20 69 6e 73 65 72 74 69 6e 67 20 74 65 78 74 20   inserting text 
174e0 69 6e 74 6f 20 61 20 73 74 72 69 6e 67 20 6c 69  into a string li
174f0 74 65 72 61 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54  teral..**.** ^(T
17500 68 65 20 25 51 20 6f 70 74 69 6f 6e 20 77 6f 72  he %Q option wor
17510 6b 73 20 6c 69 6b 65 20 25 71 20 65 78 63 65 70  ks like %q excep
17520 74 20 69 74 20 61 6c 73 6f 20 61 64 64 73 20 73  t it also adds s
17530 69 6e 67 6c 65 20 71 75 6f 74 65 73 20 61 72 6f  ingle quotes aro
17540 75 6e 64 0a 2a 2a 20 74 68 65 20 6f 75 74 73 69  und.** the outsi
17550 64 65 20 6f 66 20 74 68 65 20 74 6f 74 61 6c 20  de of the total 
17560 73 74 72 69 6e 67 2e 20 20 41 64 64 69 74 69 6f  string.  Additio
17570 6e 61 6c 6c 79 2c 20 69 66 20 74 68 65 20 70 61  nally, if the pa
17580 72 61 6d 65 74 65 72 20 69 6e 20 74 68 65 0a 2a  rameter in the.*
17590 2a 20 61 72 67 75 6d 65 6e 74 20 6c 69 73 74 20  * argument list 
175a0 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  is a NULL pointe
175b0 72 2c 20 25 51 20 73 75 62 73 74 69 74 75 74 65  r, %Q substitute
175c0 73 20 74 68 65 20 74 65 78 74 20 22 4e 55 4c 4c  s the text "NULL
175d0 22 20 28 77 69 74 68 6f 75 74 0a 2a 2a 20 73 69  " (without.** si
175e0 6e 67 6c 65 20 71 75 6f 74 65 73 29 2e 29 5e 20  ngle quotes).)^ 
175f0 20 53 6f 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65   So, for example
17600 2c 20 6f 6e 65 20 63 6f 75 6c 64 20 73 61 79 3a  , one could say:
17610 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75 6f  .**.** <blockquo
17620 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 20 63 68 61  te><pre>.**  cha
17630 72 20 2a 7a 53 51 4c 20 3d 20 73 71 6c 69 74 65  r *zSQL = sqlite
17640 33 5f 6d 70 72 69 6e 74 66 28 22 49 4e 53 45 52  3_mprintf("INSER
17650 54 20 49 4e 54 4f 20 74 61 62 6c 65 20 56 41 4c  T INTO table VAL
17660 55 45 53 28 25 51 29 22 2c 20 7a 54 65 78 74 29  UES(%Q)", zText)
17670 3b 0a 2a 2a 20 20 73 71 6c 69 74 65 33 5f 65 78  ;.**  sqlite3_ex
17680 65 63 28 64 62 2c 20 7a 53 51 4c 2c 20 30 2c 20  ec(db, zSQL, 0, 
17690 30 2c 20 30 29 3b 0a 2a 2a 20 20 73 71 6c 69 74  0, 0);.**  sqlit
176a0 65 33 5f 66 72 65 65 28 7a 53 51 4c 29 3b 0a 2a  e3_free(zSQL);.*
176b0 2a 20 3c 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71  * </pre></blockq
176c0 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  uote>.**.** The 
176d0 63 6f 64 65 20 61 62 6f 76 65 20 77 69 6c 6c 20  code above will 
176e0 72 65 6e 64 65 72 20 61 20 63 6f 72 72 65 63 74  render a correct
176f0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 69   SQL statement i
17700 6e 20 74 68 65 20 7a 53 51 4c 0a 2a 2a 20 76 61  n the zSQL.** va
17710 72 69 61 62 6c 65 20 65 76 65 6e 20 69 66 20 74  riable even if t
17720 68 65 20 7a 54 65 78 74 20 76 61 72 69 61 62 6c  he zText variabl
17730 65 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  e is a NULL poin
17740 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 65  ter..**.** ^(The
17750 20 22 25 7a 22 20 66 6f 72 6d 61 74 74 69 6e 67   "%z" formatting
17760 20 6f 70 74 69 6f 6e 20 77 6f 72 6b 73 20 6c 69   option works li
17770 6b 65 20 22 25 73 22 20 62 75 74 20 77 69 74 68  ke "%s" but with
17780 20 74 68 65 0a 2a 2a 20 61 64 64 69 74 69 6f 6e   the.** addition
17790 20 74 68 61 74 20 61 66 74 65 72 20 74 68 65 20   that after the 
177a0 73 74 72 69 6e 67 20 68 61 73 20 62 65 65 6e 20  string has been 
177b0 72 65 61 64 20 61 6e 64 20 63 6f 70 69 65 64 20  read and copied 
177c0 69 6e 74 6f 0a 2a 2a 20 74 68 65 20 72 65 73 75  into.** the resu
177d0 6c 74 2c 20 5b 73 71 6c 69 74 65 33 5f 66 72 65  lt, [sqlite3_fre
177e0 65 28 29 5d 20 69 73 20 63 61 6c 6c 65 64 20 6f  e()] is called o
177f0 6e 20 74 68 65 20 69 6e 70 75 74 20 73 74 72 69  n the input stri
17800 6e 67 2e 29 5e 0a 2a 2f 0a 63 68 61 72 20 2a 73  ng.)^.*/.char *s
17810 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28 63  qlite3_mprintf(c
17820 6f 6e 73 74 20 63 68 61 72 2a 2c 2e 2e 2e 29 3b  onst char*,...);
17830 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 76  .char *sqlite3_v
17840 6d 70 72 69 6e 74 66 28 63 6f 6e 73 74 20 63 68  mprintf(const ch
17850 61 72 2a 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 63  ar*, va_list);.c
17860 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 73 6e 70  har *sqlite3_snp
17870 72 69 6e 74 66 28 69 6e 74 2c 63 68 61 72 2a 2c  rintf(int,char*,
17880 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 2e 2e 2e  const char*, ...
17890 29 3b 0a 63 68 61 72 20 2a 73 71 6c 69 74 65 33  );.char *sqlite3
178a0 5f 76 73 6e 70 72 69 6e 74 66 28 69 6e 74 2c 63  _vsnprintf(int,c
178b0 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a  har*,const char*
178c0 2c 20 76 61 5f 6c 69 73 74 29 3b 0a 0a 2f 2a 0a  , va_list);../*.
178d0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4d 65 6d  ** CAPI3REF: Mem
178e0 6f 72 79 20 41 6c 6c 6f 63 61 74 69 6f 6e 20 53  ory Allocation S
178f0 75 62 73 79 73 74 65 6d 0a 2a 2a 0a 2a 2a 20 54  ubsystem.**.** T
17900 68 65 20 53 51 4c 69 74 65 20 63 6f 72 65 20 75  he SQLite core u
17910 73 65 73 20 74 68 65 73 65 20 74 68 72 65 65 20  ses these three 
17920 72 6f 75 74 69 6e 65 73 20 66 6f 72 20 61 6c 6c  routines for all
17930 20 6f 66 20 69 74 73 20 6f 77 6e 0a 2a 2a 20 69   of its own.** i
17940 6e 74 65 72 6e 61 6c 20 6d 65 6d 6f 72 79 20 61  nternal memory a
17950 6c 6c 6f 63 61 74 69 6f 6e 20 6e 65 65 64 73 2e  llocation needs.
17960 20 22 43 6f 72 65 22 20 69 6e 20 74 68 65 20 70   "Core" in the p
17970 72 65 76 69 6f 75 73 20 73 65 6e 74 65 6e 63 65  revious sentence
17980 0a 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 69 6e 63  .** does not inc
17990 6c 75 64 65 20 6f 70 65 72 61 74 69 6e 67 2d 73  lude operating-s
179a0 79 73 74 65 6d 20 73 70 65 63 69 66 69 63 20 56  ystem specific V
179b0 46 53 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f  FS implementatio
179c0 6e 2e 20 20 54 68 65 0a 2a 2a 20 57 69 6e 64 6f  n.  The.** Windo
179d0 77 73 20 56 46 53 20 75 73 65 73 20 6e 61 74 69  ws VFS uses nati
179e0 76 65 20 6d 61 6c 6c 6f 63 28 29 20 61 6e 64 20  ve malloc() and 
179f0 66 72 65 65 28 29 20 66 6f 72 20 73 6f 6d 65 20  free() for some 
17a00 6f 70 65 72 61 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a  operations..**.*
17a10 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 6d  * ^The sqlite3_m
17a20 61 6c 6c 6f 63 28 29 20 72 6f 75 74 69 6e 65 20  alloc() routine 
17a30 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
17a40 72 20 74 6f 20 61 20 62 6c 6f 63 6b 0a 2a 2a 20  r to a block.** 
17a50 6f 66 20 6d 65 6d 6f 72 79 20 61 74 20 6c 65 61  of memory at lea
17a60 73 74 20 4e 20 62 79 74 65 73 20 69 6e 20 6c 65  st N bytes in le
17a70 6e 67 74 68 2c 20 77 68 65 72 65 20 4e 20 69 73  ngth, where N is
17a80 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 2e 0a   the parameter..
17a90 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 6d  ** ^If sqlite3_m
17aa0 61 6c 6c 6f 63 28 29 20 69 73 20 75 6e 61 62 6c  alloc() is unabl
17ab0 65 20 74 6f 20 6f 62 74 61 69 6e 20 73 75 66 66  e to obtain suff
17ac0 69 63 69 65 6e 74 20 66 72 65 65 0a 2a 2a 20 6d  icient free.** m
17ad0 65 6d 6f 72 79 2c 20 69 74 20 72 65 74 75 72 6e  emory, it return
17ae0 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  s a NULL pointer
17af0 2e 20 20 5e 49 66 20 74 68 65 20 70 61 72 61 6d  .  ^If the param
17b00 65 74 65 72 20 4e 20 74 6f 0a 2a 2a 20 73 71 6c  eter N to.** sql
17b10 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 69 73  ite3_malloc() is
17b20 20 7a 65 72 6f 20 6f 72 20 6e 65 67 61 74 69 76   zero or negativ
17b30 65 20 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 6d  e then sqlite3_m
17b40 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73 0a  alloc() returns.
17b50 2a 2a 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65  ** a NULL pointe
17b60 72 2e 0a 2a 2a 0a 2a 2a 20 5e 43 61 6c 6c 69 6e  r..**.** ^Callin
17b70 67 20 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29  g sqlite3_free()
17b80 20 77 69 74 68 20 61 20 70 6f 69 6e 74 65 72 20   with a pointer 
17b90 70 72 65 76 69 6f 75 73 6c 79 20 72 65 74 75 72  previously retur
17ba0 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74 65  ned.** by sqlite
17bb0 33 5f 6d 61 6c 6c 6f 63 28 29 20 6f 72 20 73 71  3_malloc() or sq
17bc0 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20  lite3_realloc() 
17bd0 72 65 6c 65 61 73 65 73 20 74 68 61 74 20 6d 65  releases that me
17be0 6d 6f 72 79 20 73 6f 0a 2a 2a 20 74 68 61 74 20  mory so.** that 
17bf0 69 74 20 6d 69 67 68 74 20 62 65 20 72 65 75 73  it might be reus
17c00 65 64 2e 20 20 5e 54 68 65 20 73 71 6c 69 74 65  ed.  ^The sqlite
17c10 33 5f 66 72 65 65 28 29 20 72 6f 75 74 69 6e 65  3_free() routine
17c20 20 69 73 0a 2a 2a 20 61 20 6e 6f 2d 6f 70 20 69   is.** a no-op i
17c30 66 20 69 73 20 63 61 6c 6c 65 64 20 77 69 74 68  f is called with
17c40 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2e   a NULL pointer.
17c50 20 20 50 61 73 73 69 6e 67 20 61 20 4e 55 4c 4c    Passing a NULL
17c60 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 73   pointer.** to s
17c70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 20 69 73  qlite3_free() is
17c80 20 68 61 72 6d 6c 65 73 73 2e 20 20 41 66 74 65   harmless.  Afte
17c90 72 20 62 65 69 6e 67 20 66 72 65 65 64 2c 20 6d  r being freed, m
17ca0 65 6d 6f 72 79 0a 2a 2a 20 73 68 6f 75 6c 64 20  emory.** should 
17cb0 6e 65 69 74 68 65 72 20 62 65 20 72 65 61 64 20  neither be read 
17cc0 6e 6f 72 20 77 72 69 74 74 65 6e 2e 20 20 45 76  nor written.  Ev
17cd0 65 6e 20 72 65 61 64 69 6e 67 20 70 72 65 76 69  en reading previ
17ce0 6f 75 73 6c 79 20 66 72 65 65 64 0a 2a 2a 20 6d  ously freed.** m
17cf0 65 6d 6f 72 79 20 6d 69 67 68 74 20 72 65 73 75  emory might resu
17d00 6c 74 20 69 6e 20 61 20 73 65 67 6d 65 6e 74 61  lt in a segmenta
17d10 74 69 6f 6e 20 66 61 75 6c 74 20 6f 72 20 6f 74  tion fault or ot
17d20 68 65 72 20 73 65 76 65 72 65 20 65 72 72 6f 72  her severe error
17d30 2e 0a 2a 2a 20 4d 65 6d 6f 72 79 20 63 6f 72 72  ..** Memory corr
17d40 75 70 74 69 6f 6e 2c 20 61 20 73 65 67 6d 65 6e  uption, a segmen
17d50 74 61 74 69 6f 6e 20 66 61 75 6c 74 2c 20 6f 72  tation fault, or
17d60 20 6f 74 68 65 72 20 73 65 76 65 72 65 20 65 72   other severe er
17d70 72 6f 72 0a 2a 2a 20 6d 69 67 68 74 20 72 65 73  ror.** might res
17d80 75 6c 74 20 69 66 20 73 71 6c 69 74 65 33 5f 66  ult if sqlite3_f
17d90 72 65 65 28 29 20 69 73 20 63 61 6c 6c 65 64 20  ree() is called 
17da0 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
17db0 70 6f 69 6e 74 65 72 20 74 68 61 74 0a 2a 2a 20  pointer that.** 
17dc0 77 61 73 20 6e 6f 74 20 6f 62 74 61 69 6e 65 64  was not obtained
17dd0 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 6d 61   from sqlite3_ma
17de0 6c 6c 6f 63 28 29 20 6f 72 20 73 71 6c 69 74 65  lloc() or sqlite
17df0 33 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 0a  3_realloc()..**.
17e00 2a 2a 20 5e 28 54 68 65 20 73 71 6c 69 74 65 33  ** ^(The sqlite3
17e10 5f 72 65 61 6c 6c 6f 63 28 29 20 69 6e 74 65 72  _realloc() inter
17e20 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74 6f  face attempts to
17e30 20 72 65 73 69 7a 65 20 61 0a 2a 2a 20 70 72 69   resize a.** pri
17e40 6f 72 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  or memory alloca
17e50 74 69 6f 6e 20 74 6f 20 62 65 20 61 74 20 6c 65  tion to be at le
17e60 61 73 74 20 4e 20 62 79 74 65 73 2c 20 77 68 65  ast N bytes, whe
17e70 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 73  re N is the.** s
17e80 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  econd parameter.
17e90 20 20 54 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c    The memory all
17ea0 6f 63 61 74 69 6f 6e 20 74 6f 20 62 65 20 72 65  ocation to be re
17eb0 73 69 7a 65 64 20 69 73 20 74 68 65 20 66 69 72  sized is the fir
17ec0 73 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 2e  st.** parameter.
17ed0 29 5e 20 5e 20 49 66 20 74 68 65 20 66 69 72 73  )^ ^ If the firs
17ee0 74 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73  t parameter to s
17ef0 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29  qlite3_realloc()
17f00 0a 2a 2a 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  .** is a NULL po
17f10 69 6e 74 65 72 20 74 68 65 6e 20 69 74 73 20 62  inter then its b
17f20 65 68 61 76 69 6f 72 20 69 73 20 69 64 65 6e 74  ehavior is ident
17f30 69 63 61 6c 20 74 6f 20 63 61 6c 6c 69 6e 67 0a  ical to calling.
17f40 2a 2a 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f  ** sqlite3_mallo
17f50 63 28 4e 29 20 77 68 65 72 65 20 4e 20 69 73 20  c(N) where N is 
17f60 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d  the second param
17f70 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
17f80 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e 49  realloc()..** ^I
17f90 66 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72  f the second par
17fa0 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65  ameter to sqlite
17fb0 33 5f 72 65 61 6c 6c 6f 63 28 29 20 69 73 20 7a  3_realloc() is z
17fc0 65 72 6f 20 6f 72 0a 2a 2a 20 6e 65 67 61 74 69  ero or.** negati
17fd0 76 65 20 74 68 65 6e 20 74 68 65 20 62 65 68 61  ve then the beha
17fe0 76 69 6f 72 20 69 73 20 65 78 61 63 74 6c 79 20  vior is exactly 
17ff0 74 68 65 20 73 61 6d 65 20 61 73 20 63 61 6c 6c  the same as call
18000 69 6e 67 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 66  ing.** sqlite3_f
18010 72 65 65 28 50 29 20 77 68 65 72 65 20 50 20 69  ree(P) where P i
18020 73 20 74 68 65 20 66 69 72 73 74 20 70 61 72 61  s the first para
18030 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
18040 5f 72 65 61 6c 6c 6f 63 28 29 2e 0a 2a 2a 20 5e  _realloc()..** ^
18050 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f 63 28  sqlite3_realloc(
18060 29 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e  ) returns a poin
18070 74 65 72 20 74 6f 20 61 20 6d 65 6d 6f 72 79 20  ter to a memory 
18080 61 6c 6c 6f 63 61 74 69 6f 6e 0a 2a 2a 20 6f 66  allocation.** of
18090 20 61 74 20 6c 65 61 73 74 20 4e 20 62 79 74 65   at least N byte
180a0 73 20 69 6e 20 73 69 7a 65 20 6f 72 20 4e 55 4c  s in size or NUL
180b0 4c 20 69 66 20 73 75 66 66 69 63 69 65 6e 74 20  L if sufficient 
180c0 6d 65 6d 6f 72 79 20 69 73 20 75 6e 61 76 61 69  memory is unavai
180d0 6c 61 62 6c 65 2e 0a 2a 2a 20 5e 49 66 20 4d 20  lable..** ^If M 
180e0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 20 74  is the size of t
180f0 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
18100 69 6f 6e 2c 20 74 68 65 6e 20 6d 69 6e 28 4e 2c  ion, then min(N,
18110 4d 29 20 62 79 74 65 73 0a 2a 2a 20 6f 66 20 74  M) bytes.** of t
18120 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74  he prior allocat
18130 69 6f 6e 20 61 72 65 20 63 6f 70 69 65 64 20 69  ion are copied i
18140 6e 74 6f 20 74 68 65 20 62 65 67 69 6e 6e 69 6e  nto the beginnin
18150 67 20 6f 66 20 62 75 66 66 65 72 20 72 65 74 75  g of buffer retu
18160 72 6e 65 64 0a 2a 2a 20 62 79 20 73 71 6c 69 74  rned.** by sqlit
18170 65 33 5f 72 65 61 6c 6c 6f 63 28 29 20 61 6e 64  e3_realloc() and
18180 20 74 68 65 20 70 72 69 6f 72 20 61 6c 6c 6f 63   the prior alloc
18190 61 74 69 6f 6e 20 69 73 20 66 72 65 65 64 2e 0a  ation is freed..
181a0 2a 2a 20 5e 49 66 20 73 71 6c 69 74 65 33 5f 72  ** ^If sqlite3_r
181b0 65 61 6c 6c 6f 63 28 29 20 72 65 74 75 72 6e 73  ealloc() returns
181c0 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 74 68 65 20   NULL, then the 
181d0 70 72 69 6f 72 20 61 6c 6c 6f 63 61 74 69 6f 6e  prior allocation
181e0 0a 2a 2a 20 69 73 20 6e 6f 74 20 66 72 65 65 64  .** is not freed
181f0 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d  ..**.** ^The mem
18200 6f 72 79 20 72 65 74 75 72 6e 65 64 20 62 79 20  ory returned by 
18210 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29  sqlite3_malloc()
18220 20 61 6e 64 20 73 71 6c 69 74 65 33 5f 72 65 61   and sqlite3_rea
18230 6c 6c 6f 63 28 29 0a 2a 2a 20 69 73 20 61 6c 77  lloc().** is alw
18240 61 79 73 20 61 6c 69 67 6e 65 64 20 74 6f 20 61  ays aligned to a
18250 74 20 6c 65 61 73 74 20 61 6e 20 38 20 62 79 74  t least an 8 byt
18260 65 20 62 6f 75 6e 64 61 72 79 2c 20 6f 72 20 74  e boundary, or t
18270 6f 20 61 0a 2a 2a 20 34 20 62 79 74 65 20 62 6f  o a.** 4 byte bo
18280 75 6e 64 61 72 79 20 69 66 20 74 68 65 20 5b 53  undary if the [S
18290 51 4c 49 54 45 5f 34 5f 42 59 54 45 5f 41 4c 49  QLITE_4_BYTE_ALI
182a0 47 4e 45 44 5f 4d 41 4c 4c 4f 43 5d 20 63 6f 6d  GNED_MALLOC] com
182b0 70 69 6c 65 2d 74 69 6d 65 0a 2a 2a 20 6f 70 74  pile-time.** opt
182c0 69 6f 6e 20 69 73 20 75 73 65 64 2e 0a 2a 2a 0a  ion is used..**.
182d0 2a 2a 20 49 6e 20 53 51 4c 69 74 65 20 76 65 72  ** In SQLite ver
182e0 73 69 6f 6e 20 33 2e 35 2e 30 20 61 6e 64 20 33  sion 3.5.0 and 3
182f0 2e 35 2e 31 2c 20 69 74 20 77 61 73 20 70 6f 73  .5.1, it was pos
18300 73 69 62 6c 65 20 74 6f 20 64 65 66 69 6e 65 0a  sible to define.
18310 2a 2a 20 74 68 65 20 53 51 4c 49 54 45 5f 4f 4d  ** the SQLITE_OM
18320 49 54 5f 4d 45 4d 4f 52 59 5f 41 4c 4c 4f 43 41  IT_MEMORY_ALLOCA
18330 54 49 4f 4e 20 77 68 69 63 68 20 77 6f 75 6c 64  TION which would
18340 20 63 61 75 73 65 20 74 68 65 20 62 75 69 6c 74   cause the built
18350 2d 69 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65 6e 74  -in.** implement
18360 61 74 69 6f 6e 20 6f 66 20 74 68 65 73 65 20 72  ation of these r
18370 6f 75 74 69 6e 65 73 20 74 6f 20 62 65 20 6f 6d  outines to be om
18380 69 74 74 65 64 2e 20 20 54 68 61 74 20 63 61 70  itted.  That cap
18390 61 62 69 6c 69 74 79 0a 2a 2a 20 69 73 20 6e 6f  ability.** is no
183a0 20 6c 6f 6e 67 65 72 20 70 72 6f 76 69 64 65 64   longer provided
183b0 2e 20 20 4f 6e 6c 79 20 62 75 69 6c 74 2d 69 6e  .  Only built-in
183c0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 6f   memory allocato
183d0 72 73 20 63 61 6e 20 62 65 20 75 73 65 64 2e 0a  rs can be used..
183e0 2a 2a 0a 2a 2a 20 54 68 65 20 57 69 6e 64 6f 77  **.** The Window
183f0 73 20 4f 53 20 69 6e 74 65 72 66 61 63 65 20 6c  s OS interface l
18400 61 79 65 72 20 63 61 6c 6c 73 0a 2a 2a 20 74 68  ayer calls.** th
18410 65 20 73 79 73 74 65 6d 20 6d 61 6c 6c 6f 63 28  e system malloc(
18420 29 20 61 6e 64 20 66 72 65 65 28 29 20 64 69 72  ) and free() dir
18430 65 63 74 6c 79 20 77 68 65 6e 20 63 6f 6e 76 65  ectly when conve
18440 72 74 69 6e 67 0a 2a 2a 20 66 69 6c 65 6e 61 6d  rting.** filenam
18450 65 73 20 62 65 74 77 65 65 6e 20 74 68 65 20 55  es between the U
18460 54 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 75 73  TF-8 encoding us
18470 65 64 20 62 79 20 53 51 4c 69 74 65 0a 2a 2a 20  ed by SQLite.** 
18480 61 6e 64 20 77 68 61 74 65 76 65 72 20 66 69 6c  and whatever fil
18490 65 6e 61 6d 65 20 65 6e 63 6f 64 69 6e 67 20 69  ename encoding i
184a0 73 20 75 73 65 64 20 62 79 20 74 68 65 20 70 61  s used by the pa
184b0 72 74 69 63 75 6c 61 72 20 57 69 6e 64 6f 77 73  rticular Windows
184c0 0a 2a 2a 20 69 6e 73 74 61 6c 6c 61 74 69 6f 6e  .** installation
184d0 2e 20 20 4d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61  .  Memory alloca
184e0 74 69 6f 6e 20 65 72 72 6f 72 73 20 61 72 65 20  tion errors are 
184f0 64 65 74 65 63 74 65 64 2c 20 62 75 74 0a 2a 2a  detected, but.**
18500 20 74 68 65 79 20 61 72 65 20 72 65 70 6f 72 74   they are report
18510 65 64 20 62 61 63 6b 20 61 73 20 5b 53 51 4c 49  ed back as [SQLI
18520 54 45 5f 43 41 4e 54 4f 50 45 4e 5d 20 6f 72 0a  TE_CANTOPEN] or.
18530 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52 52  ** [SQLITE_IOERR
18540 5d 20 72 61 74 68 65 72 20 74 68 61 6e 20 5b 53  ] rather than [S
18550 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 0a 2a 2a  QLITE_NOMEM]..**
18560 0a 2a 2a 20 54 68 65 20 70 6f 69 6e 74 65 72 20  .** The pointer 
18570 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 5b 73 71  arguments to [sq
18580 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 61 6e  lite3_free()] an
18590 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c  d [sqlite3_reall
185a0 6f 63 28 29 5d 0a 2a 2a 20 6d 75 73 74 20 62 65  oc()].** must be
185b0 20 65 69 74 68 65 72 20 4e 55 4c 4c 20 6f 72 20   either NULL or 
185c0 65 6c 73 65 20 70 6f 69 6e 74 65 72 73 20 6f 62  else pointers ob
185d0 74 61 69 6e 65 64 20 66 72 6f 6d 20 61 20 70 72  tained from a pr
185e0 69 6f 72 0a 2a 2a 20 69 6e 76 6f 63 61 74 69 6f  ior.** invocatio
185f0 6e 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61  n of [sqlite3_ma
18600 6c 6c 6f 63 28 29 5d 20 6f 72 20 5b 73 71 6c 69  lloc()] or [sqli
18610 74 65 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 20 74  te3_realloc()] t
18620 68 61 74 20 68 61 76 65 0a 2a 2a 20 6e 6f 74 20  hat have.** not 
18630 79 65 74 20 62 65 65 6e 20 72 65 6c 65 61 73 65  yet been release
18640 64 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 70 70  d..**.** The app
18650 6c 69 63 61 74 69 6f 6e 20 6d 75 73 74 20 6e 6f  lication must no
18660 74 20 72 65 61 64 20 6f 72 20 77 72 69 74 65 20  t read or write 
18670 61 6e 79 20 70 61 72 74 20 6f 66 0a 2a 2a 20 61  any part of.** a
18680 20 62 6c 6f 63 6b 20 6f 66 20 6d 65 6d 6f 72 79   block of memory
18690 20 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65   after it has be
186a0 65 6e 20 72 65 6c 65 61 73 65 64 20 75 73 69 6e  en released usin
186b0 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72  g.** [sqlite3_fr
186c0 65 65 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  ee()] or [sqlite
186d0 33 5f 72 65 61 6c 6c 6f 63 28 29 5d 2e 0a 2a 2f  3_realloc()]..*/
186e0 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 6d  .void *sqlite3_m
186f0 61 6c 6c 6f 63 28 69 6e 74 29 3b 0a 76 6f 69 64  alloc(int);.void
18700 20 2a 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   *sqlite3_reallo
18710 63 28 76 6f 69 64 2a 2c 20 69 6e 74 29 3b 0a 76  c(void*, int);.v
18720 6f 69 64 20 73 71 6c 69 74 65 33 5f 66 72 65 65  oid sqlite3_free
18730 28 76 6f 69 64 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20  (void*);../*.** 
18740 43 41 50 49 33 52 45 46 3a 20 4d 65 6d 6f 72 79  CAPI3REF: Memory
18750 20 41 6c 6c 6f 63 61 74 6f 72 20 53 74 61 74 69   Allocator Stati
18760 73 74 69 63 73 0a 2a 2a 0a 2a 2a 20 53 51 4c 69  stics.**.** SQLi
18770 74 65 20 70 72 6f 76 69 64 65 73 20 74 68 65 73  te provides thes
18780 65 20 74 77 6f 20 69 6e 74 65 72 66 61 63 65 73  e two interfaces
18790 20 66 6f 72 20 72 65 70 6f 72 74 69 6e 67 20 6f   for reporting o
187a0 6e 20 74 68 65 20 73 74 61 74 75 73 0a 2a 2a 20  n the status.** 
187b0 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33 5f  of the [sqlite3_
187c0 6d 61 6c 6c 6f 63 28 29 5d 2c 20 5b 73 71 6c 69  malloc()], [sqli
187d0 74 65 33 5f 66 72 65 65 28 29 5d 2c 20 61 6e 64  te3_free()], and
187e0 20 5b 73 71 6c 69 74 65 33 5f 72 65 61 6c 6c 6f   [sqlite3_reallo
187f0 63 28 29 5d 0a 2a 2a 20 72 6f 75 74 69 6e 65 73  c()].** routines
18800 2c 20 77 68 69 63 68 20 66 6f 72 6d 20 74 68 65  , which form the
18810 20 62 75 69 6c 74 2d 69 6e 20 6d 65 6d 6f 72 79   built-in memory
18820 20 61 6c 6c 6f 63 61 74 69 6f 6e 20 73 75 62 73   allocation subs
18830 79 73 74 65 6d 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ystem..**.** ^Th
18840 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  e [sqlite3_memor
18850 79 5f 75 73 65 64 28 29 5d 20 72 6f 75 74 69 6e  y_used()] routin
18860 65 20 72 65 74 75 72 6e 73 20 74 68 65 20 6e 75  e returns the nu
18870 6d 62 65 72 20 6f 66 20 62 79 74 65 73 0a 2a 2a  mber of bytes.**
18880 20 6f 66 20 6d 65 6d 6f 72 79 20 63 75 72 72 65   of memory curre
18890 6e 74 6c 79 20 6f 75 74 73 74 61 6e 64 69 6e 67  ntly outstanding
188a0 20 28 6d 61 6c 6c 6f 63 65 64 20 62 75 74 20 6e   (malloced but n
188b0 6f 74 20 66 72 65 65 64 29 2e 0a 2a 2a 20 5e 54  ot freed)..** ^T
188c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6d 65 6d 6f  he [sqlite3_memo
188d0 72 79 5f 68 69 67 68 77 61 74 65 72 28 29 5d 20  ry_highwater()] 
188e0 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20  routine returns 
188f0 74 68 65 20 6d 61 78 69 6d 75 6d 0a 2a 2a 20 76  the maximum.** v
18900 61 6c 75 65 20 6f 66 20 5b 73 71 6c 69 74 65 33  alue of [sqlite3
18910 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20  _memory_used()] 
18920 73 69 6e 63 65 20 74 68 65 20 68 69 67 68 2d 77  since the high-w
18930 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 77 61 73  ater mark.** was
18940 20 6c 61 73 74 20 72 65 73 65 74 2e 20 20 5e 54   last reset.  ^T
18950 68 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e  he values return
18960 65 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ed by [sqlite3_m
18970 65 6d 6f 72 79 5f 75 73 65 64 28 29 5d 20 61 6e  emory_used()] an
18980 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  d.** [sqlite3_me
18990 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
189a0 5d 20 69 6e 63 6c 75 64 65 20 61 6e 79 20 6f 76  ] include any ov
189b0 65 72 68 65 61 64 0a 2a 2a 20 61 64 64 65 64 20  erhead.** added 
189c0 62 79 20 53 51 4c 69 74 65 20 69 6e 20 69 74 73  by SQLite in its
189d0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20   implementation 
189e0 6f 66 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c  of [sqlite3_mall
189f0 6f 63 28 29 5d 2c 0a 2a 2a 20 62 75 74 20 6e 6f  oc()],.** but no
18a00 74 20 6f 76 65 72 68 65 61 64 20 61 64 64 65 64  t overhead added
18a10 20 62 79 20 74 68 65 20 61 6e 79 20 75 6e 64 65   by the any unde
18a20 72 6c 79 69 6e 67 20 73 79 73 74 65 6d 20 6c 69  rlying system li
18a30 62 72 61 72 79 0a 2a 2a 20 72 6f 75 74 69 6e 65  brary.** routine
18a40 73 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f  s that [sqlite3_
18a50 6d 61 6c 6c 6f 63 28 29 5d 20 6d 61 79 20 63 61  malloc()] may ca
18a60 6c 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d  ll..**.** ^The m
18a70 65 6d 6f 72 79 20 68 69 67 68 2d 77 61 74 65 72  emory high-water
18a80 20 6d 61 72 6b 20 69 73 20 72 65 73 65 74 20 74   mark is reset t
18a90 6f 20 74 68 65 20 63 75 72 72 65 6e 74 20 76 61  o the current va
18aa0 6c 75 65 20 6f 66 0a 2a 2a 20 5b 73 71 6c 69 74  lue of.** [sqlit
18ab0 65 33 5f 6d 65 6d 6f 72 79 5f 75 73 65 64 28 29  e3_memory_used()
18ac0 5d 20 69 66 20 61 6e 64 20 6f 6e 6c 79 20 69 66  ] if and only if
18ad0 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 20 74   the parameter t
18ae0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 65  o.** [sqlite3_me
18af0 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28 29  mory_highwater()
18b00 5d 20 69 73 20 74 72 75 65 2e 20 20 5e 54 68 65  ] is true.  ^The
18b10 20 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 0a   value returned.
18b20 2a 2a 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 6d  ** by [sqlite3_m
18b30 65 6d 6f 72 79 5f 68 69 67 68 77 61 74 65 72 28  emory_highwater(
18b40 31 29 5d 20 69 73 20 74 68 65 20 68 69 67 68 2d  1)] is the high-
18b50 77 61 74 65 72 20 6d 61 72 6b 0a 2a 2a 20 70 72  water mark.** pr
18b60 69 6f 72 20 74 6f 20 74 68 65 20 72 65 73 65 74  ior to the reset
18b70 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f 69 6e 74  ..*/.sqlite3_int
18b80 36 34 20 73 71 6c 69 74 65 33 5f 6d 65 6d 6f 72  64 sqlite3_memor
18b90 79 5f 75 73 65 64 28 76 6f 69 64 29 3b 0a 73 71  y_used(void);.sq
18ba0 6c 69 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69  lite3_int64 sqli
18bb0 74 65 33 5f 6d 65 6d 6f 72 79 5f 68 69 67 68 77  te3_memory_highw
18bc0 61 74 65 72 28 69 6e 74 20 72 65 73 65 74 46 6c  ater(int resetFl
18bd0 61 67 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  ag);../*.** CAPI
18be0 33 52 45 46 3a 20 50 73 65 75 64 6f 2d 52 61 6e  3REF: Pseudo-Ran
18bf0 64 6f 6d 20 4e 75 6d 62 65 72 20 47 65 6e 65 72  dom Number Gener
18c00 61 74 6f 72 0a 2a 2a 0a 2a 2a 20 53 51 4c 69 74  ator.**.** SQLit
18c10 65 20 63 6f 6e 74 61 69 6e 73 20 61 20 68 69 67  e contains a hig
18c20 68 2d 71 75 61 6c 69 74 79 20 70 73 65 75 64 6f  h-quality pseudo
18c30 2d 72 61 6e 64 6f 6d 20 6e 75 6d 62 65 72 20 67  -random number g
18c40 65 6e 65 72 61 74 6f 72 20 28 50 52 4e 47 29 20  enerator (PRNG) 
18c50 75 73 65 64 20 74 6f 0a 2a 2a 20 73 65 6c 65 63  used to.** selec
18c60 74 20 72 61 6e 64 6f 6d 20 5b 52 4f 57 49 44 20  t random [ROWID 
18c70 7c 20 52 4f 57 49 44 73 5d 20 77 68 65 6e 20 69  | ROWIDs] when i
18c80 6e 73 65 72 74 69 6e 67 20 6e 65 77 20 72 65 63  nserting new rec
18c90 6f 72 64 73 20 69 6e 74 6f 20 61 20 74 61 62 6c  ords into a tabl
18ca0 65 20 74 68 61 74 0a 2a 2a 20 61 6c 72 65 61 64  e that.** alread
18cb0 79 20 75 73 65 73 20 74 68 65 20 6c 61 72 67 65  y uses the large
18cc0 73 74 20 70 6f 73 73 69 62 6c 65 20 5b 52 4f 57  st possible [ROW
18cd0 49 44 5d 2e 20 20 54 68 65 20 50 52 4e 47 20 69  ID].  The PRNG i
18ce0 73 20 61 6c 73 6f 20 75 73 65 64 20 66 6f 72 0a  s also used for.
18cf0 2a 2a 20 74 68 65 20 62 75 69 6c 64 2d 69 6e 20  ** the build-in 
18d00 72 61 6e 64 6f 6d 28 29 20 61 6e 64 20 72 61 6e  random() and ran
18d10 64 6f 6d 62 6c 6f 62 28 29 20 53 51 4c 20 66 75  domblob() SQL fu
18d20 6e 63 74 69 6f 6e 73 2e 20 20 54 68 69 73 20 69  nctions.  This i
18d30 6e 74 65 72 66 61 63 65 20 61 6c 6c 6f 77 73 0a  nterface allows.
18d40 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** applications 
18d50 74 6f 20 61 63 63 65 73 73 20 74 68 65 20 73 61  to access the sa
18d60 6d 65 20 50 52 4e 47 20 66 6f 72 20 6f 74 68 65  me PRNG for othe
18d70 72 20 70 75 72 70 6f 73 65 73 2e 0a 2a 2a 0a 2a  r purposes..**.*
18d80 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20 74 68 69  * ^A call to thi
18d90 73 20 72 6f 75 74 69 6e 65 20 73 74 6f 72 65 73  s routine stores
18da0 20 4e 20 62 79 74 65 73 20 6f 66 20 72 61 6e 64   N bytes of rand
18db0 6f 6d 6e 65 73 73 20 69 6e 74 6f 20 62 75 66 66  omness into buff
18dc0 65 72 20 50 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  er P..**.** ^The
18dd0 20 66 69 72 73 74 20 74 69 6d 65 20 74 68 69 73   first time this
18de0 20 72 6f 75 74 69 6e 65 20 69 73 20 69 6e 76 6f   routine is invo
18df0 6b 65 64 20 28 65 69 74 68 65 72 20 69 6e 74 65  ked (either inte
18e00 72 6e 61 6c 6c 79 20 6f 72 20 62 79 0a 2a 2a 20  rnally or by.** 
18e10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 29  the application)
18e20 20 74 68 65 20 50 52 4e 47 20 69 73 20 73 65 65   the PRNG is see
18e30 64 65 64 20 75 73 69 6e 67 20 72 61 6e 64 6f 6d  ded using random
18e40 6e 65 73 73 20 6f 62 74 61 69 6e 65 64 0a 2a 2a  ness obtained.**
18e50 20 66 72 6f 6d 20 74 68 65 20 78 52 61 6e 64 6f   from the xRando
18e60 6d 6e 65 73 73 20 6d 65 74 68 6f 64 20 6f 66 20  mness method of 
18e70 74 68 65 20 64 65 66 61 75 6c 74 20 5b 73 71 6c  the default [sql
18e80 69 74 65 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74  ite3_vfs] object
18e90 2e 0a 2a 2a 20 5e 4f 6e 20 61 6c 6c 20 73 75 62  ..** ^On all sub
18ea0 73 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69  sequent invocati
18eb0 6f 6e 73 2c 20 74 68 65 20 70 73 65 75 64 6f 2d  ons, the pseudo-
18ec0 72 61 6e 64 6f 6d 6e 65 73 73 20 69 73 20 67 65  randomness is ge
18ed0 6e 65 72 61 74 65 64 0a 2a 2a 20 69 6e 74 65 72  nerated.** inter
18ee0 6e 61 6c 6c 79 20 61 6e 64 20 77 69 74 68 6f 75  nally and withou
18ef0 74 20 72 65 63 6f 75 72 73 65 20 74 6f 20 74 68  t recourse to th
18f00 65 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20  e [sqlite3_vfs] 
18f10 78 52 61 6e 64 6f 6d 6e 65 73 73 0a 2a 2a 20 6d  xRandomness.** m
18f20 65 74 68 6f 64 2e 0a 2a 2f 0a 76 6f 69 64 20 73  ethod..*/.void s
18f30 71 6c 69 74 65 33 5f 72 61 6e 64 6f 6d 6e 65 73  qlite3_randomnes
18f40 73 28 69 6e 74 20 4e 2c 20 76 6f 69 64 20 2a 50  s(int N, void *P
18f50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
18f60 45 46 3a 20 43 6f 6d 70 69 6c 65 2d 54 69 6d 65  EF: Compile-Time
18f70 20 41 75 74 68 6f 72 69 7a 61 74 69 6f 6e 20 43   Authorization C
18f80 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e  allbacks.**.** ^
18f90 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 67  This routine reg
18fa0 69 73 74 65 72 73 20 61 6e 20 61 75 74 68 6f 72  isters an author
18fb0 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 77 69  izer callback wi
18fc0 74 68 20 61 20 70 61 72 74 69 63 75 6c 61 72 0a  th a particular.
18fd0 2a 2a 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  ** [database con
18fe0 6e 65 63 74 69 6f 6e 5d 2c 20 73 75 70 70 6c 69  nection], suppli
18ff0 65 64 20 69 6e 20 74 68 65 20 66 69 72 73 74 20  ed in the first 
19000 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
19010 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19020 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65 64  lback is invoked
19030 20 61 73 20 53 51 4c 20 73 74 61 74 65 6d 65 6e   as SQL statemen
19040 74 73 20 61 72 65 20 62 65 69 6e 67 20 63 6f 6d  ts are being com
19050 70 69 6c 65 64 0a 2a 2a 20 62 79 20 5b 73 71 6c  piled.** by [sql
19060 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d 20  ite3_prepare()] 
19070 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 20  or its variants 
19080 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19090 5f 76 32 28 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69  _v2()],.** [sqli
190a0 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d  te3_prepare16()]
190b0 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 70 72   and [sqlite3_pr
190c0 65 70 61 72 65 31 36 5f 76 32 28 29 5d 2e 20 20  epare16_v2()].  
190d0 5e 41 74 20 76 61 72 69 6f 75 73 0a 2a 2a 20 70  ^At various.** p
190e0 6f 69 6e 74 73 20 64 75 72 69 6e 67 20 74 68 65  oints during the
190f0 20 63 6f 6d 70 69 6c 61 74 69 6f 6e 20 70 72 6f   compilation pro
19100 63 65 73 73 2c 20 61 73 20 6c 6f 67 69 63 20 69  cess, as logic i
19110 73 20 62 65 69 6e 67 20 63 72 65 61 74 65 64 0a  s being created.
19120 2a 2a 20 74 6f 20 70 65 72 66 6f 72 6d 20 76 61  ** to perform va
19130 72 69 6f 75 73 20 61 63 74 69 6f 6e 73 2c 20 74  rious actions, t
19140 68 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61  he authorizer ca
19150 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76 6f 6b 65  llback is invoke
19160 64 20 74 6f 0a 2a 2a 20 73 65 65 20 69 66 20 74  d to.** see if t
19170 68 6f 73 65 20 61 63 74 69 6f 6e 73 20 61 72 65  hose actions are
19180 20 61 6c 6c 6f 77 65 64 2e 20 20 5e 54 68 65 20   allowed.  ^The 
19190 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
191a0 61 63 6b 20 73 68 6f 75 6c 64 0a 2a 2a 20 72 65  ack should.** re
191b0 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d  turn [SQLITE_OK]
191c0 20 74 6f 20 61 6c 6c 6f 77 20 74 68 65 20 61 63   to allow the ac
191d0 74 69 6f 6e 2c 20 5b 53 51 4c 49 54 45 5f 49 47  tion, [SQLITE_IG
191e0 4e 4f 52 45 5d 20 74 6f 20 64 69 73 61 6c 6c 6f  NORE] to disallo
191f0 77 20 74 68 65 0a 2a 2a 20 73 70 65 63 69 66 69  w the.** specifi
19200 63 20 61 63 74 69 6f 6e 20 62 75 74 20 61 6c 6c  c action but all
19210 6f 77 20 74 68 65 20 53 51 4c 20 73 74 61 74 65  ow the SQL state
19220 6d 65 6e 74 20 74 6f 20 63 6f 6e 74 69 6e 75 65  ment to continue
19230 20 74 6f 20 62 65 0a 2a 2a 20 63 6f 6d 70 69 6c   to be.** compil
19240 65 64 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44  ed, or [SQLITE_D
19250 45 4e 59 5d 20 74 6f 20 63 61 75 73 65 20 74 68  ENY] to cause th
19260 65 20 65 6e 74 69 72 65 20 53 51 4c 20 73 74 61  e entire SQL sta
19270 74 65 6d 65 6e 74 20 74 6f 20 62 65 0a 2a 2a 20  tement to be.** 
19280 72 65 6a 65 63 74 65 64 20 77 69 74 68 20 61 6e  rejected with an
19290 20 65 72 72 6f 72 2e 20 20 5e 49 66 20 74 68 65   error.  ^If the
192a0 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c   authorizer call
192b0 62 61 63 6b 20 72 65 74 75 72 6e 73 0a 2a 2a 20  back returns.** 
192c0 61 6e 79 20 76 61 6c 75 65 20 6f 74 68 65 72 20  any value other 
192d0 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f 49 47 4e  than [SQLITE_IGN
192e0 4f 52 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 4b  ORE], [SQLITE_OK
192f0 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 44 45  ], or [SQLITE_DE
19300 4e 59 5d 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20  NY].** then the 
19310 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
19320 5f 76 32 28 29 5d 20 6f 72 20 65 71 75 69 76 61  _v2()] or equiva
19330 6c 65 6e 74 20 63 61 6c 6c 20 74 68 61 74 20 74  lent call that t
19340 72 69 67 67 65 72 65 64 0a 2a 2a 20 74 68 65 20  riggered.** the 
19350 61 75 74 68 6f 72 69 7a 65 72 20 77 69 6c 6c 20  authorizer will 
19360 66 61 69 6c 20 77 69 74 68 20 61 6e 20 65 72 72  fail with an err
19370 6f 72 20 6d 65 73 73 61 67 65 2e 0a 2a 2a 0a 2a  or message..**.*
19380 2a 20 57 68 65 6e 20 74 68 65 20 63 61 6c 6c 62  * When the callb
19390 61 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c  ack returns [SQL
193a0 49 54 45 5f 4f 4b 5d 2c 20 74 68 61 74 20 6d 65  ITE_OK], that me
193b0 61 6e 73 20 74 68 65 20 6f 70 65 72 61 74 69 6f  ans the operatio
193c0 6e 0a 2a 2a 20 72 65 71 75 65 73 74 65 64 20 69  n.** requested i
193d0 73 20 6f 6b 2e 20 20 5e 57 68 65 6e 20 74 68 65  s ok.  ^When the
193e0 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72 6e   callback return
193f0 73 20 5b 53 51 4c 49 54 45 5f 44 45 4e 59 5d 2c  s [SQLITE_DENY],
19400 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   the.** [sqlite3
19410 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f  _prepare_v2()] o
19420 72 20 65 71 75 69 76 61 6c 65 6e 74 20 63 61 6c  r equivalent cal
19430 6c 20 74 68 61 74 20 74 72 69 67 67 65 72 65 64  l that triggered
19440 20 74 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a   the.** authoriz
19450 65 72 20 77 69 6c 6c 20 66 61 69 6c 20 77 69 74  er will fail wit
19460 68 20 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61  h an error messa
19470 67 65 20 65 78 70 6c 61 69 6e 69 6e 67 20 74 68  ge explaining th
19480 61 74 0a 2a 2a 20 61 63 63 65 73 73 20 69 73 20  at.** access is 
19490 64 65 6e 69 65 64 2e 20 0a 2a 2a 0a 2a 2a 20 5e  denied. .**.** ^
194a0 54 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  The first parame
194b0 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68 6f  ter to the autho
194c0 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20 69  rizer callback i
194d0 73 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20  s a copy of the 
194e0 74 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74  third.** paramet
194f0 65 72 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  er to the sqlite
19500 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65 72  3_set_authorizer
19510 28 29 20 69 6e 74 65 72 66 61 63 65 2e 20 5e 54  () interface. ^T
19520 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
19530 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 63 61  ter.** to the ca
19540 6c 6c 62 61 63 6b 20 69 73 20 61 6e 20 69 6e 74  llback is an int
19550 65 67 65 72 20 5b 53 51 4c 49 54 45 5f 43 4f 50  eger [SQLITE_COP
19560 59 20 7c 20 61 63 74 69 6f 6e 20 63 6f 64 65 5d  Y | action code]
19570 20 74 68 61 74 20 73 70 65 63 69 66 69 65 73 0a   that specifies.
19580 2a 2a 20 74 68 65 20 70 61 72 74 69 63 75 6c 61  ** the particula
19590 72 20 61 63 74 69 6f 6e 20 74 6f 20 62 65 20 61  r action to be a
195a0 75 74 68 6f 72 69 7a 65 64 2e 20 5e 54 68 65 20  uthorized. ^The 
195b0 74 68 69 72 64 20 74 68 72 6f 75 67 68 20 73 69  third through si
195c0 78 74 68 20 70 61 72 61 6d 65 74 65 72 73 0a 2a  xth parameters.*
195d0 2a 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  * to the callbac
195e0 6b 20 61 72 65 20 7a 65 72 6f 2d 74 65 72 6d 69  k are zero-termi
195f0 6e 61 74 65 64 20 73 74 72 69 6e 67 73 20 74 68  nated strings th
19600 61 74 20 63 6f 6e 74 61 69 6e 20 61 64 64 69 74  at contain addit
19610 69 6f 6e 61 6c 0a 2a 2a 20 64 65 74 61 69 6c 73  ional.** details
19620 20 61 62 6f 75 74 20 74 68 65 20 61 63 74 69 6f   about the actio
19630 6e 20 74 6f 20 62 65 20 61 75 74 68 6f 72 69 7a  n to be authoriz
19640 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68  ed..**.** ^If th
19650 65 20 61 63 74 69 6f 6e 20 63 6f 64 65 20 69 73  e action code is
19660 20 5b 53 51 4c 49 54 45 5f 52 45 41 44 5d 0a 2a   [SQLITE_READ].*
19670 2a 20 61 6e 64 20 74 68 65 20 63 61 6c 6c 62 61  * and the callba
19680 63 6b 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49  ck returns [SQLI
19690 54 45 5f 49 47 4e 4f 52 45 5d 20 74 68 65 6e 20  TE_IGNORE] then 
196a0 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
196b0 20 73 74 61 74 65 6d 65 6e 74 5d 20 73 74 61 74   statement] stat
196c0 65 6d 65 6e 74 20 69 73 20 63 6f 6e 73 74 72 75  ement is constru
196d0 63 74 65 64 20 74 6f 20 73 75 62 73 74 69 74 75  cted to substitu
196e0 74 65 0a 2a 2a 20 61 20 4e 55 4c 4c 20 76 61 6c  te.** a NULL val
196f0 75 65 20 69 6e 20 70 6c 61 63 65 20 6f 66 20 74  ue in place of t
19700 68 65 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20  he table column 
19710 74 68 61 74 20 77 6f 75 6c 64 20 68 61 76 65 0a  that would have.
19720 2a 2a 20 62 65 65 6e 20 72 65 61 64 20 69 66 20  ** been read if 
19730 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 68 61 64 20  [SQLITE_OK] had 
19740 62 65 65 6e 20 72 65 74 75 72 6e 65 64 2e 20 20  been returned.  
19750 54 68 65 20 5b 53 51 4c 49 54 45 5f 49 47 4e 4f  The [SQLITE_IGNO
19760 52 45 5d 0a 2a 2a 20 72 65 74 75 72 6e 20 63 61  RE].** return ca
19770 6e 20 62 65 20 75 73 65 64 20 74 6f 20 64 65 6e  n be used to den
19780 79 20 61 6e 20 75 6e 74 72 75 73 74 65 64 20 75  y an untrusted u
19790 73 65 72 20 61 63 63 65 73 73 20 74 6f 20 69 6e  ser access to in
197a0 64 69 76 69 64 75 61 6c 0a 2a 2a 20 63 6f 6c 75  dividual.** colu
197b0 6d 6e 73 20 6f 66 20 61 20 74 61 62 6c 65 2e 0a  mns of a table..
197c0 2a 2a 20 5e 49 66 20 74 68 65 20 61 63 74 69 6f  ** ^If the actio
197d0 6e 20 63 6f 64 65 20 69 73 20 5b 53 51 4c 49 54  n code is [SQLIT
197e0 45 5f 44 45 4c 45 54 45 5d 20 61 6e 64 20 74 68  E_DELETE] and th
197f0 65 20 63 61 6c 6c 62 61 63 6b 20 72 65 74 75 72  e callback retur
19800 6e 73 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 49 47  ns.** [SQLITE_IG
19810 4e 4f 52 45 5d 20 74 68 65 6e 20 74 68 65 20 5b  NORE] then the [
19820 44 45 4c 45 54 45 5d 20 6f 70 65 72 61 74 69 6f  DELETE] operatio
19830 6e 20 70 72 6f 63 65 65 64 73 20 62 75 74 20 74  n proceeds but t
19840 68 65 0a 2a 2a 20 5b 74 72 75 6e 63 61 74 65 20  he.** [truncate 
19850 6f 70 74 69 6d 69 7a 61 74 69 6f 6e 5d 20 69 73  optimization] is
19860 20 64 69 73 61 62 6c 65 64 20 61 6e 64 20 61 6c   disabled and al
19870 6c 20 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74  l rows are delet
19880 65 64 20 69 6e 64 69 76 69 64 75 61 6c 6c 79 2e  ed individually.
19890 0a 2a 2a 0a 2a 2a 20 41 6e 20 61 75 74 68 6f 72  .**.** An author
198a0 69 7a 65 72 20 69 73 20 75 73 65 64 20 77 68 65  izer is used whe
198b0 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
198c0 72 65 20 7c 20 70 72 65 70 61 72 69 6e 67 5d 0a  re | preparing].
198d0 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  ** SQL statement
198e0 73 20 66 72 6f 6d 20 61 6e 20 75 6e 74 72 75 73  s from an untrus
198f0 74 65 64 20 73 6f 75 72 63 65 2c 20 74 6f 20 65  ted source, to e
19900 6e 73 75 72 65 20 74 68 61 74 20 74 68 65 20 53  nsure that the S
19910 51 4c 20 73 74 61 74 65 6d 65 6e 74 73 0a 2a 2a  QL statements.**
19920 20 64 6f 20 6e 6f 74 20 74 72 79 20 74 6f 20 61   do not try to a
19930 63 63 65 73 73 20 64 61 74 61 20 74 68 65 79 20  ccess data they 
19940 61 72 65 20 6e 6f 74 20 61 6c 6c 6f 77 65 64 20  are not allowed 
19950 74 6f 20 73 65 65 2c 20 6f 72 20 74 68 61 74 20  to see, or that 
19960 74 68 65 79 20 64 6f 20 6e 6f 74 0a 2a 2a 20 74  they do not.** t
19970 72 79 20 74 6f 20 65 78 65 63 75 74 65 20 6d 61  ry to execute ma
19980 6c 69 63 69 6f 75 73 20 73 74 61 74 65 6d 65 6e  licious statemen
19990 74 73 20 74 68 61 74 20 64 61 6d 61 67 65 20 74  ts that damage t
199a0 68 65 20 64 61 74 61 62 61 73 65 2e 20 20 46 6f  he database.  Fo
199b0 72 0a 2a 2a 20 65 78 61 6d 70 6c 65 2c 20 61 6e  r.** example, an
199c0 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 61 79   application may
199d0 20 61 6c 6c 6f 77 20 61 20 75 73 65 72 20 74 6f   allow a user to
199e0 20 65 6e 74 65 72 20 61 72 62 69 74 72 61 72 79   enter arbitrary
199f0 0a 2a 2a 20 53 51 4c 20 71 75 65 72 69 65 73 20  .** SQL queries 
19a00 66 6f 72 20 65 76 61 6c 75 61 74 69 6f 6e 20 62  for evaluation b
19a10 79 20 61 20 64 61 74 61 62 61 73 65 2e 20 20 42  y a database.  B
19a20 75 74 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  ut the applicati
19a30 6f 6e 20 64 6f 65 73 0a 2a 2a 20 6e 6f 74 20 77  on does.** not w
19a40 61 6e 74 20 74 68 65 20 75 73 65 72 20 74 6f 20  ant the user to 
19a50 62 65 20 61 62 6c 65 20 74 6f 20 6d 61 6b 65 20  be able to make 
19a60 61 72 62 69 74 72 61 72 79 20 63 68 61 6e 67 65  arbitrary change
19a70 73 20 74 6f 20 74 68 65 0a 2a 2a 20 64 61 74 61  s to the.** data
19a80 62 61 73 65 2e 20 20 41 6e 20 61 75 74 68 6f 72  base.  An author
19a90 69 7a 65 72 20 63 6f 75 6c 64 20 74 68 65 6e 20  izer could then 
19aa0 62 65 20 70 75 74 20 69 6e 20 70 6c 61 63 65 20  be put in place 
19ab0 77 68 69 6c 65 20 74 68 65 0a 2a 2a 20 75 73 65  while the.** use
19ac0 72 2d 65 6e 74 65 72 65 64 20 53 51 4c 20 69 73  r-entered SQL is
19ad0 20 62 65 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   being [sqlite3_
19ae0 70 72 65 70 61 72 65 20 7c 20 70 72 65 70 61 72  prepare | prepar
19af0 65 64 5d 20 74 68 61 74 0a 2a 2a 20 64 69 73 61  ed] that.** disa
19b00 6c 6c 6f 77 73 20 65 76 65 72 79 74 68 69 6e 67  llows everything
19b10 20 65 78 63 65 70 74 20 5b 53 45 4c 45 43 54 5d   except [SELECT]
19b20 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a 2a 2a 0a   statements..**.
19b30 2a 2a 20 41 70 70 6c 69 63 61 74 69 6f 6e 73 20  ** Applications 
19b40 74 68 61 74 20 6e 65 65 64 20 74 6f 20 70 72 6f  that need to pro
19b50 63 65 73 73 20 53 51 4c 20 66 72 6f 6d 20 75 6e  cess SQL from un
19b60 74 72 75 73 74 65 64 20 73 6f 75 72 63 65 73 0a  trusted sources.
19b70 2a 2a 20 6d 69 67 68 74 20 61 6c 73 6f 20 63 6f  ** might also co
19b80 6e 73 69 64 65 72 20 6c 6f 77 65 72 69 6e 67 20  nsider lowering 
19b90 72 65 73 6f 75 72 63 65 20 6c 69 6d 69 74 73 20  resource limits 
19ba0 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c  using [sqlite3_l
19bb0 69 6d 69 74 28 29 5d 0a 2a 2a 20 61 6e 64 20 6c  imit()].** and l
19bc0 69 6d 69 74 69 6e 67 20 64 61 74 61 62 61 73 65  imiting database
19bd0 20 73 69 7a 65 20 75 73 69 6e 67 20 74 68 65 20   size using the 
19be0 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74 5d  [max_page_count]
19bf0 20 5b 50 52 41 47 4d 41 5d 0a 2a 2a 20 69 6e 20   [PRAGMA].** in 
19c00 61 64 64 69 74 69 6f 6e 20 74 6f 20 75 73 69 6e  addition to usin
19c10 67 20 61 6e 20 61 75 74 68 6f 72 69 7a 65 72 2e  g an authorizer.
19c20 0a 2a 2a 0a 2a 2a 20 5e 28 4f 6e 6c 79 20 61 20  .**.** ^(Only a 
19c30 73 69 6e 67 6c 65 20 61 75 74 68 6f 72 69 7a 65  single authorize
19c40 72 20 63 61 6e 20 62 65 20 69 6e 20 70 6c 61 63  r can be in plac
19c50 65 20 6f 6e 20 61 20 64 61 74 61 62 61 73 65 20  e on a database 
19c60 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a 2a 20 61 74  connection.** at
19c70 20 61 20 74 69 6d 65 2e 20 20 45 61 63 68 20 63   a time.  Each c
19c80 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 73  all to sqlite3_s
19c90 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 20 6f 76  et_authorizer ov
19ca0 65 72 72 69 64 65 73 20 74 68 65 0a 2a 2a 20 70  errides the.** p
19cb0 72 65 76 69 6f 75 73 20 63 61 6c 6c 2e 29 5e 20  revious call.)^ 
19cc0 20 5e 44 69 73 61 62 6c 65 20 74 68 65 20 61 75   ^Disable the au
19cd0 74 68 6f 72 69 7a 65 72 20 62 79 20 69 6e 73 74  thorizer by inst
19ce0 61 6c 6c 69 6e 67 20 61 20 4e 55 4c 4c 20 63 61  alling a NULL ca
19cf0 6c 6c 62 61 63 6b 2e 0a 2a 2a 20 54 68 65 20 61  llback..** The a
19d00 75 74 68 6f 72 69 7a 65 72 20 69 73 20 64 69 73  uthorizer is dis
19d10 61 62 6c 65 64 20 62 79 20 64 65 66 61 75 6c 74  abled by default
19d20 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 61 75 74 68  ..**.** The auth
19d30 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 20  orizer callback 
19d40 6d 75 73 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74  must not do anyt
19d50 68 69 6e 67 20 74 68 61 74 20 77 69 6c 6c 20 6d  hing that will m
19d60 6f 64 69 66 79 0a 2a 2a 20 74 68 65 20 64 61 74  odify.** the dat
19d70 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
19d80 20 74 68 61 74 20 69 6e 76 6f 6b 65 64 20 74 68   that invoked th
19d90 65 20 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c  e authorizer cal
19da0 6c 62 61 63 6b 2e 0a 2a 2a 20 4e 6f 74 65 20 74  lback..** Note t
19db0 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  hat [sqlite3_pre
19dc0 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20 5b  pare_v2()] and [
19dd0 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20  sqlite3_step()] 
19de0 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65 69  both modify thei
19df0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
19e00 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74 68  nnections for th
19e10 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d 6f  e meaning of "mo
19e20 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70 61  dify" in this pa
19e30 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20 5e  ragraph..**.** ^
19e40 57 68 65 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72  When [sqlite3_pr
19e50 65 70 61 72 65 5f 76 32 28 29 5d 20 69 73 20 75  epare_v2()] is u
19e60 73 65 64 20 74 6f 20 70 72 65 70 61 72 65 20 61  sed to prepare a
19e70 20 73 74 61 74 65 6d 65 6e 74 2c 20 74 68 65 0a   statement, the.
19e80 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 6d 69 67  ** statement mig
19e90 68 74 20 62 65 20 72 65 2d 70 72 65 70 61 72 65  ht be re-prepare
19ea0 64 20 64 75 72 69 6e 67 20 5b 73 71 6c 69 74 65  d during [sqlite
19eb0 33 5f 73 74 65 70 28 29 5d 20 64 75 65 20 74 6f  3_step()] due to
19ec0 20 61 20 0a 2a 2a 20 73 63 68 65 6d 61 20 63 68   a .** schema ch
19ed0 61 6e 67 65 2e 20 20 48 65 6e 63 65 2c 20 74 68  ange.  Hence, th
19ee0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 73 68  e application sh
19ef0 6f 75 6c 64 20 65 6e 73 75 72 65 20 74 68 61 74  ould ensure that
19f00 20 74 68 65 0a 2a 2a 20 63 6f 72 72 65 63 74 20   the.** correct 
19f10 61 75 74 68 6f 72 69 7a 65 72 20 63 61 6c 6c 62  authorizer callb
19f20 61 63 6b 20 72 65 6d 61 69 6e 73 20 69 6e 20 70  ack remains in p
19f30 6c 61 63 65 20 64 75 72 69 6e 67 20 74 68 65 20  lace during the 
19f40 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
19f50 2e 0a 2a 2a 0a 2a 2a 20 5e 4e 6f 74 65 20 74 68  ..**.** ^Note th
19f60 61 74 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  at the authorize
19f70 72 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  r callback is in
19f80 76 6f 6b 65 64 20 6f 6e 6c 79 20 64 75 72 69 6e  voked only durin
19f90 67 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 70 72  g.** [sqlite3_pr
19fa0 65 70 61 72 65 28 29 5d 20 6f 72 20 69 74 73 20  epare()] or its 
19fb0 76 61 72 69 61 6e 74 73 2e 20 20 41 75 74 68 6f  variants.  Autho
19fc0 72 69 7a 61 74 69 6f 6e 20 69 73 20 6e 6f 74 0a  rization is not.
19fd0 2a 2a 20 70 65 72 66 6f 72 6d 65 64 20 64 75 72  ** performed dur
19fe0 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20 65 76  ing statement ev
19ff0 61 6c 75 61 74 69 6f 6e 20 69 6e 20 5b 73 71 6c  aluation in [sql
1a000 69 74 65 33 5f 73 74 65 70 28 29 5d 2c 20 75 6e  ite3_step()], un
1a010 6c 65 73 73 0a 2a 2a 20 61 73 20 73 74 61 74 65  less.** as state
1a020 64 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  d in the previou
1a030 73 20 70 61 72 61 67 72 61 70 68 2c 20 73 71 6c  s paragraph, sql
1a040 69 74 65 33 5f 73 74 65 70 28 29 20 69 6e 76 6f  ite3_step() invo
1a050 6b 65 73 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70  kes.** sqlite3_p
1a060 72 65 70 61 72 65 5f 76 32 28 29 20 74 6f 20 72  repare_v2() to r
1a070 65 70 72 65 70 61 72 65 20 61 20 73 74 61 74 65  eprepare a state
1a080 6d 65 6e 74 20 61 66 74 65 72 20 61 20 73 63 68  ment after a sch
1a090 65 6d 61 20 63 68 61 6e 67 65 2e 0a 2a 2f 0a 69  ema change..*/.i
1a0a0 6e 74 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  nt sqlite3_set_a
1a0b0 75 74 68 6f 72 69 7a 65 72 28 0a 20 20 73 71 6c  uthorizer(.  sql
1a0c0 69 74 65 33 2a 2c 0a 20 20 69 6e 74 20 28 2a 78  ite3*,.  int (*x
1a0d0 41 75 74 68 29 28 76 6f 69 64 2a 2c 69 6e 74 2c  Auth)(void*,int,
1a0e0 63 6f 6e 73 74 20 63 68 61 72 2a 2c 63 6f 6e 73  const char*,cons
1a0f0 74 20 63 68 61 72 2a 2c 63 6f 6e 73 74 20 63 68  t char*,const ch
1a100 61 72 2a 2c 63 6f 6e 73 74 20 63 68 61 72 2a 29  ar*,const char*)
1a110 2c 0a 20 20 76 6f 69 64 20 2a 70 55 73 65 72 44  ,.  void *pUserD
1a120 61 74 61 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ata.);../*.** CA
1a130 50 49 33 52 45 46 3a 20 41 75 74 68 6f 72 69 7a  PI3REF: Authoriz
1a140 65 72 20 52 65 74 75 72 6e 20 43 6f 64 65 73 0a  er Return Codes.
1a150 2a 2a 0a 2a 2a 20 54 68 65 20 5b 73 71 6c 69 74  **.** The [sqlit
1a160 65 33 5f 73 65 74 5f 61 75 74 68 6f 72 69 7a 65  e3_set_authorize
1a170 72 20 7c 20 61 75 74 68 6f 72 69 7a 65 72 20 63  r | authorizer c
1a180 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e  allback function
1a190 5d 20 6d 75 73 74 0a 2a 2a 20 72 65 74 75 72 6e  ] must.** return
1a1a0 20 65 69 74 68 65 72 20 5b 53 51 4c 49 54 45 5f   either [SQLITE_
1a1b0 4f 4b 5d 20 6f 72 20 6f 6e 65 20 6f 66 20 74 68  OK] or one of th
1a1c0 65 73 65 20 74 77 6f 20 63 6f 6e 73 74 61 6e 74  ese two constant
1a1d0 73 20 69 6e 20 6f 72 64 65 72 0a 2a 2a 20 74 6f  s in order.** to
1a1e0 20 73 69 67 6e 61 6c 20 53 51 4c 69 74 65 20 77   signal SQLite w
1a1f0 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68  hether or not th
1a200 65 20 61 63 74 69 6f 6e 20 69 73 20 70 65 72 6d  e action is perm
1a210 69 74 74 65 64 2e 20 20 53 65 65 20 74 68 65 0a  itted.  See the.
1a220 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 65 74 5f  ** [sqlite3_set_
1a230 61 75 74 68 6f 72 69 7a 65 72 20 7c 20 61 75 74  authorizer | aut
1a240 68 6f 72 69 7a 65 72 20 64 6f 63 75 6d 65 6e 74  horizer document
1a250 61 74 69 6f 6e 5d 20 66 6f 72 20 61 64 64 69 74  ation] for addit
1a260 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f 72 6d 61  ional.** informa
1a270 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74 65  tion..**.** Note
1a280 20 74 68 61 74 20 53 51 4c 49 54 45 5f 49 47 4e   that SQLITE_IGN
1a290 4f 52 45 20 69 73 20 61 6c 73 6f 20 75 73 65 64  ORE is also used
1a2a0 20 61 73 20 61 20 5b 53 51 4c 49 54 45 5f 52 4f   as a [SQLITE_RO
1a2b0 4c 4c 42 41 43 4b 20 7c 20 72 65 74 75 72 6e 20  LLBACK | return 
1a2c0 63 6f 64 65 5d 0a 2a 2a 20 66 72 6f 6d 20 74 68  code].** from th
1a2d0 65 20 5b 73 71 6c 69 74 65 33 5f 76 74 61 62 5f  e [sqlite3_vtab_
1a2e0 6f 6e 5f 63 6f 6e 66 6c 69 63 74 28 29 5d 20 69  on_conflict()] i
1a2f0 6e 74 65 72 66 61 63 65 2e 0a 2a 2f 0a 23 64 65  nterface..*/.#de
1a300 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 45 4e 59  fine SQLITE_DENY
1a310 20 20 20 31 20 20 20 2f 2a 20 41 62 6f 72 74 20     1   /* Abort 
1a320 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
1a330 74 20 77 69 74 68 20 61 6e 20 65 72 72 6f 72 20  t with an error 
1a340 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a350 45 5f 49 47 4e 4f 52 45 20 32 20 20 20 2f 2a 20  E_IGNORE 2   /* 
1a360 44 6f 6e 27 74 20 61 6c 6c 6f 77 20 61 63 63 65  Don't allow acce
1a370 73 73 2c 20 62 75 74 20 64 6f 6e 27 74 20 67 65  ss, but don't ge
1a380 6e 65 72 61 74 65 20 61 6e 20 65 72 72 6f 72 20  nerate an error 
1a390 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
1a3a0 45 46 3a 20 41 75 74 68 6f 72 69 7a 65 72 20 41  EF: Authorizer A
1a3b0 63 74 69 6f 6e 20 43 6f 64 65 73 0a 2a 2a 0a 2a  ction Codes.**.*
1a3c0 2a 20 54 68 65 20 5b 73 71 6c 69 74 65 33 5f 73  * The [sqlite3_s
1a3d0 65 74 5f 61 75 74 68 6f 72 69 7a 65 72 28 29 5d  et_authorizer()]
1a3e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69 73   interface regis
1a3f0 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b 20  ters a callback 
1a400 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 74 68 61 74  function.** that
1a410 20 69 73 20 69 6e 76 6f 6b 65 64 20 74 6f 20 61   is invoked to a
1a420 75 74 68 6f 72 69 7a 65 20 63 65 72 74 61 69 6e  uthorize certain
1a430 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 61   SQL statement a
1a440 63 74 69 6f 6e 73 2e 20 20 54 68 65 0a 2a 2a 20  ctions.  The.** 
1a450 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72  second parameter
1a460 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63 6b   to the callback
1a470 20 69 73 20 61 6e 20 69 6e 74 65 67 65 72 20 63   is an integer c
1a480 6f 64 65 20 74 68 61 74 20 73 70 65 63 69 66 69  ode that specifi
1a490 65 73 0a 2a 2a 20 77 68 61 74 20 61 63 74 69 6f  es.** what actio
1a4a0 6e 20 69 73 20 62 65 69 6e 67 20 61 75 74 68 6f  n is being autho
1a4b0 72 69 7a 65 64 2e 20 20 54 68 65 73 65 20 61 72  rized.  These ar
1a4c0 65 20 74 68 65 20 69 6e 74 65 67 65 72 20 61 63  e the integer ac
1a4d0 74 69 6f 6e 20 63 6f 64 65 73 20 74 68 61 74 0a  tion codes that.
1a4e0 2a 2a 20 74 68 65 20 61 75 74 68 6f 72 69 7a 65  ** the authorize
1a4f0 72 20 63 61 6c 6c 62 61 63 6b 20 6d 61 79 20 62  r callback may b
1a500 65 20 70 61 73 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  e passed..**.** 
1a510 54 68 65 73 65 20 61 63 74 69 6f 6e 20 63 6f 64  These action cod
1a520 65 20 76 61 6c 75 65 73 20 73 69 67 6e 69 66 79  e values signify
1a530 20 77 68 61 74 20 6b 69 6e 64 20 6f 66 20 6f 70   what kind of op
1a540 65 72 61 74 69 6f 6e 20 69 73 20 74 6f 20 62 65  eration is to be
1a550 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 64 2e 20  .** authorized. 
1a560 20 54 68 65 20 33 72 64 20 61 6e 64 20 34 74 68   The 3rd and 4th
1a570 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74   parameters to t
1a580 68 65 20 61 75 74 68 6f 72 69 7a 61 74 69 6f 6e  he authorization
1a590 0a 2a 2a 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e  .** callback fun
1a5a0 63 74 69 6f 6e 20 77 69 6c 6c 20 62 65 20 70 61  ction will be pa
1a5b0 72 61 6d 65 74 65 72 73 20 6f 72 20 4e 55 4c 4c  rameters or NULL
1a5c0 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20 77 68   depending on wh
1a5d0 69 63 68 20 6f 66 20 74 68 65 73 65 0a 2a 2a 20  ich of these.** 
1a5e0 63 6f 64 65 73 20 69 73 20 75 73 65 64 20 61 73  codes is used as
1a5f0 20 74 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61   the second para
1a600 6d 65 74 65 72 2e 20 20 5e 28 54 68 65 20 35 74  meter.  ^(The 5t
1a610 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
1a620 68 65 0a 2a 2a 20 61 75 74 68 6f 72 69 7a 65 72  he.** authorizer
1a630 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 74 68 65   callback is the
1a640 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61 74   name of the dat
1a650 61 62 61 73 65 20 28 22 6d 61 69 6e 22 2c 20 22  abase ("main", "
1a660 74 65 6d 70 22 2c 0a 2a 2a 20 65 74 63 2e 29 20  temp",.** etc.) 
1a670 69 66 20 61 70 70 6c 69 63 61 62 6c 65 2e 29 5e  if applicable.)^
1a680 20 20 5e 54 68 65 20 36 74 68 20 70 61 72 61 6d    ^The 6th param
1a690 65 74 65 72 20 74 6f 20 74 68 65 20 61 75 74 68  eter to the auth
1a6a0 6f 72 69 7a 65 72 20 63 61 6c 6c 62 61 63 6b 0a  orizer callback.
1a6b0 2a 2a 20 69 73 20 74 68 65 20 6e 61 6d 65 20 6f  ** is the name o
1a6c0 66 20 74 68 65 20 69 6e 6e 65 72 2d 6d 6f 73 74  f the inner-most
1a6d0 20 74 72 69 67 67 65 72 20 6f 72 20 76 69 65 77   trigger or view
1a6e0 20 74 68 61 74 20 69 73 20 72 65 73 70 6f 6e 73   that is respons
1a6f0 69 62 6c 65 20 66 6f 72 0a 2a 2a 20 74 68 65 20  ible for.** the 
1a700 61 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 6f  access attempt o
1a710 72 20 4e 55 4c 4c 20 69 66 20 74 68 69 73 20 61  r NULL if this a
1a720 63 63 65 73 73 20 61 74 74 65 6d 70 74 20 69 73  ccess attempt is
1a730 20 64 69 72 65 63 74 6c 79 20 66 72 6f 6d 0a 2a   directly from.*
1a740 2a 20 74 6f 70 2d 6c 65 76 65 6c 20 53 51 4c 20  * top-level SQL 
1a750 63 6f 64 65 2e 0a 2a 2f 0a 2f 2a 2a 2a 2a 2a 2a  code..*/./******
1a760 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a770 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a 2a  ****************
1a780 2a 2a 2a 2a 2a 20 33 72 64 20 2a 2a 2a 2a 2a 2a  ***** 3rd ******
1a790 2a 2a 2a 2a 2a 2a 20 34 74 68 20 2a 2a 2a 2a 2a  ****** 4th *****
1a7a0 2a 2a 2a 2a 2a 2a 2f 0a 23 64 65 66 69 6e 65 20  ******/.#define 
1a7b0 53 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 49 4e  SQLITE_CREATE_IN
1a7c0 44 45 58 20 20 20 20 20 20 20 20 20 20 31 20 20  DEX          1  
1a7d0 20 2f 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20   /* Index Name  
1a7e0 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20      Table Name  
1a7f0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1a800 51 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 41 42  QLITE_CREATE_TAB
1a810 4c 45 20 20 20 20 20 20 20 20 20 20 32 20 20 20  LE          2   
1a820 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1a830 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1a840 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1a850 4c 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50  LITE_CREATE_TEMP
1a860 5f 49 4e 44 45 58 20 20 20 20 20 33 20 20 20 2f  _INDEX     3   /
1a870 2a 20 49 6e 64 65 78 20 4e 61 6d 65 20 20 20 20  * Index Name    
1a880 20 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20    Table Name    
1a890 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c    */.#define SQL
1a8a0 49 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f  ITE_CREATE_TEMP_
1a8b0 54 41 42 4c 45 20 20 20 20 20 34 20 20 20 2f 2a  TABLE     4   /*
1a8c0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1a8d0 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20   NULL           
1a8e0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1a8f0 54 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 54  TE_CREATE_TEMP_T
1a900 52 49 47 47 45 52 20 20 20 35 20 20 20 2f 2a 20  RIGGER   5   /* 
1a910 54 72 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20  Trigger Name    
1a920 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20  Table Name      
1a930 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1a940 45 5f 43 52 45 41 54 45 5f 54 45 4d 50 5f 56 49  E_CREATE_TEMP_VI
1a950 45 57 20 20 20 20 20 20 36 20 20 20 2f 2a 20 56  EW      6   /* V
1a960 69 65 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e  iew Name       N
1a970 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1a980 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1a990 5f 43 52 45 41 54 45 5f 54 52 49 47 47 45 52 20  _CREATE_TRIGGER 
1a9a0 20 20 20 20 20 20 20 37 20 20 20 2f 2a 20 54 72         7   /* Tr
1a9b0 69 67 67 65 72 20 4e 61 6d 65 20 20 20 20 54 61  igger Name    Ta
1a9c0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f  ble Name      */
1a9d0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1a9e0 43 52 45 41 54 45 5f 56 49 45 57 20 20 20 20 20  CREATE_VIEW     
1a9f0 20 20 20 20 20 20 38 20 20 20 2f 2a 20 56 69 65        8   /* Vie
1aa00 77 20 4e 61 6d 65 20 20 20 20 20 20 20 4e 55 4c  w Name       NUL
1aa10 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1aa20 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1aa30 45 4c 45 54 45 20 20 20 20 20 20 20 20 20 20 20  ELETE           
1aa40 20 20 20 20 20 39 20 20 20 2f 2a 20 54 61 62 6c       9   /* Tabl
1aa50 65 20 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c  e Name      NULL
1aa60 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1aa70 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52  define SQLITE_DR
1aa80 4f 50 5f 49 4e 44 45 58 20 20 20 20 20 20 20 20  OP_INDEX        
1aa90 20 20 20 31 30 20 20 20 2f 2a 20 49 6e 64 65 78     10   /* Index
1aaa0 20 4e 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65   Name      Table
1aab0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1aac0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f  efine SQLITE_DRO
1aad0 50 5f 54 41 42 4c 45 20 20 20 20 20 20 20 20 20  P_TABLE         
1aae0 20 20 31 31 20 20 20 2f 2a 20 54 61 62 6c 65 20    11   /* Table 
1aaf0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1ab00 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1ab10 66 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50  fine SQLITE_DROP
1ab20 5f 54 45 4d 50 5f 49 4e 44 45 58 20 20 20 20 20  _TEMP_INDEX     
1ab30 20 31 32 20 20 20 2f 2a 20 49 6e 64 65 78 20 4e   12   /* Index N
1ab40 61 6d 65 20 20 20 20 20 20 54 61 62 6c 65 20 4e  ame      Table N
1ab50 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66  ame      */.#def
1ab60 69 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f  ine SQLITE_DROP_
1ab70 54 45 4d 50 5f 54 41 42 4c 45 20 20 20 20 20 20  TEMP_TABLE      
1ab80 31 33 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  13   /* Table Na
1ab90 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20  me      NULL    
1aba0 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69          */.#defi
1abb0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54  ne SQLITE_DROP_T
1abc0 45 4d 50 5f 54 52 49 47 47 45 52 20 20 20 20 31  EMP_TRIGGER    1
1abd0 34 20 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e  4   /* Trigger N
1abe0 61 6d 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d  ame    Table Nam
1abf0 65 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  e      */.#defin
1ac00 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 45  e SQLITE_DROP_TE
1ac10 4d 50 5f 56 49 45 57 20 20 20 20 20 20 20 31 35  MP_VIEW       15
1ac20 20 20 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20     /* View Name 
1ac30 20 20 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20        NULL      
1ac40 20 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65        */.#define
1ac50 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 54 52 49   SQLITE_DROP_TRI
1ac60 47 47 45 52 20 20 20 20 20 20 20 20 20 31 36 20  GGER         16 
1ac70 20 20 2f 2a 20 54 72 69 67 67 65 72 20 4e 61 6d    /* Trigger Nam
1ac80 65 20 20 20 20 54 61 62 6c 65 20 4e 61 6d 65 20  e    Table Name 
1ac90 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20       */.#define 
1aca0 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56 49 45 57  SQLITE_DROP_VIEW
1acb0 20 20 20 20 20 20 20 20 20 20 20 20 31 37 20 20              17  
1acc0 20 2f 2a 20 56 69 65 77 20 4e 61 6d 65 20 20 20   /* View Name   
1acd0 20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20      NULL        
1ace0 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53      */.#define S
1acf0 51 4c 49 54 45 5f 49 4e 53 45 52 54 20 20 20 20  QLITE_INSERT    
1ad00 20 20 20 20 20 20 20 20 20 20 20 31 38 20 20 20             18   
1ad10 2f 2a 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20  /* Table Name   
1ad20 20 20 20 4e 55 4c 4c 20 20 20 20 20 20 20 20 20     NULL         
1ad30 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51     */.#define SQ
1ad40 4c 49 54 45 5f 50 52 41 47 4d 41 20 20 20 20 20  LITE_PRAGMA     
1ad50 20 20 20 20 20 20 20 20 20 20 31 39 20 20 20 2f            19   /
1ad60 2a 20 50 72 61 67 6d 61 20 4e 61 6d 65 20 20 20  * Pragma Name   
1ad70 20 20 31 73 74 20 61 72 67 20 6f 72 20 4e 55 4c    1st arg or NUL
1ad80 4c 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c  L */.#define SQL
1ad90 49 54 45 5f 52 45 41 44 20 20 20 20 20 20 20 20  ITE_READ        
1ada0 20 20 20 20 20 20 20 20 20 32 30 20 20 20 2f 2a           20   /*
1adb0 20 54 61 62 6c 65 20 4e 61 6d 65 20 20 20 20 20   Table Name     
1adc0 20 43 6f 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20   Column Name    
1add0 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49   */.#define SQLI
1ade0 54 45 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  TE_SELECT       
1adf0 20 20 20 20 20 20 20 20 32 31 20 20 20 2f 2a 20          21   /* 
1ae00 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ae10 4e 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20  NULL            
1ae20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54  */.#define SQLIT
1ae30 45 5f 54 52 41 4e 53 41 43 54 49 4f 4e 20 20 20  E_TRANSACTION   
1ae40 20 20 20 20 20 20 20 32 32 20 20 20 2f 2a 20 4f         22   /* O
1ae50 70 65 72 61 74 69 6f 6e 20 20 20 20 20 20 20 4e  peration       N
1ae60 55 4c 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a  ULL            *
1ae70 2f 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  /.#define SQLITE
1ae80 5f 55 50 44 41 54 45 20 20 20 20 20 20 20 20 20  _UPDATE         
1ae90 20 20 20 20 20 20 32 33 20 20 20 2f 2a 20 54 61        23   /* Ta
1aea0 62 6c 65 20 4e 61 6d 65 20 20 20 20 20 20 43 6f  ble Name      Co
1aeb0 6c 75 6d 6e 20 4e 61 6d 65 20 20 20 20 20 2a 2f  lumn Name     */
1aec0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
1aed0 41 54 54 41 43 48 20 20 20 20 20 20 20 20 20 20  ATTACH          
1aee0 20 20 20 20 20 32 34 20 20 20 2f 2a 20 46 69 6c       24   /* Fil
1aef0 65 6e 61 6d 65 20 20 20 20 20 20 20 20 4e 55 4c  ename        NUL
1af00 4c 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a  L            */.
1af10 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 44  #define SQLITE_D
1af20 45 54 41 43 48 20 20 20 20 20 20 20 20 20 20 20  ETACH           
1af30 20 20 20 20 32 35 20 20 20 2f 2a 20 44 61 74 61      25   /* Data
1af40 62 61 73 65 20 4e 61 6d 65 20 20 20 4e 55 4c 4c  base Name   NULL
1af50 20 20 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23              */.#
1af60 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4c  define SQLITE_AL
1af70 54 45 52 5f 54 41 42 4c 45 20 20 20 20 20 20 20  TER_TABLE       
1af80 20 20 20 32 36 20 20 20 2f 2a 20 44 61 74 61 62     26   /* Datab
1af90 61 73 65 20 4e 61 6d 65 20 20 20 54 61 62 6c 65  ase Name   Table
1afa0 20 4e 61 6d 65 20 20 20 20 20 20 2a 2f 0a 23 64   Name      */.#d
1afb0 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 52 45 49  efine SQLITE_REI
1afc0 4e 44 45 58 20 20 20 20 20 20 20 20 20 20 20 20  NDEX            
1afd0 20 20 32 37 20 20 20 2f 2a 20 49 6e 64 65 78 20    27   /* Index 
1afe0 4e 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20  Name      NULL  
1aff0 20 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65            */.#de
1b000 66 69 6e 65 20 53 51 4c 49 54 45 5f 41 4e 41 4c  fine SQLITE_ANAL
1b010 59 5a 45 20 20 20 20 20 20 20 20 20 20 20 20 20  YZE             
1b020 20 32 38 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e   28   /* Table N
1b030 61 6d 65 20 20 20 20 20 20 4e 55 4c 4c 20 20 20  ame      NULL   
1b040 20 20 20 20 20 20 20 20 20 2a 2f 0a 23 64 65 66           */.#def
1b050 69 6e 65 20 53 51 4c 49 54 45 5f 43 52 45 41 54  ine SQLITE_CREAT
1b060 45 5f 56 54 41 42 4c 45 20 20 20 20 20 20 20 20  E_VTABLE        
1b070 32 39 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61  29   /* Table Na
1b080 6d 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e  me      Module N
1b090 61 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69  ame     */.#defi
1b0a0 6e 65 20 53 51 4c 49 54 45 5f 44 52 4f 50 5f 56  ne SQLITE_DROP_V
1b0b0 54 41 42 4c 45 20 20 20 20 20 20 20 20 20 20 33  TABLE          3
1b0c0 30 20 20 20 2f 2a 20 54 61 62 6c 65 20 4e 61 6d  0   /* Table Nam
1b0d0 65 20 20 20 20 20 20 4d 6f 64 75 6c 65 20 4e 61  e      Module Na
1b0e0 6d 65 20 20 20 20 20 2a 2f 0a 23 64 65 66 69 6e  me     */.#defin
1b0f0 65 20 53 51 4c 49 54 45 5f 46 55 4e 43 54 49 4f  e SQLITE_FUNCTIO
1b100 4e 20 20 20 20 20 20 20 20 20 20 20 20 20 33 31  N             31
1b110 20 20 20 2f 2a 20 4e 55 4c 4c 20 20 20 20 20 20     /* NULL      
1b120 20 20 20 20 20 20 46 75 6e 63 74 69 6f 6e 20 4e        Function N
1b130 61 6d 65 20 20 20 2a 2f 0a 23 64 65 66 69 6e 65  ame   */.#define
1b140 20 53 51 4c 49 54 45 5f 53 41 56 45 50 4f 49 4e   SQLITE_SAVEPOIN
1b150 54 20 20 20 20 20 20 20 20 20 20 20 20 33 32 20  T            32 
1b160 20 20 2f 2a 20 4f 70 65 72 61 74 69 6f 6e 20 20    /* Operation  
1b170 20 20 20 20 20 53 61 76 65 70 6f 69 6e 74 20 4e       Savepoint N
1b180 61 6d 65 20 20 2a 2f 0a 23 64 65 66 69 6e 65 20  ame  */.#define 
1b190 53 51 4c 49 54 45 5f 43 4f 50 59 20 20 20 20 20  SQLITE_COPY     
1b1a0 20 20 20 20 20 20 20 20 20 20 20 20 20 30 20 20               0  
1b1b0 20 2f 2a 20 4e 6f 20 6c 6f 6e 67 65 72 20 75 73   /* No longer us
1b1c0 65 64 20 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  ed */../*.** CAP
1b1d0 49 33 52 45 46 3a 20 54 72 61 63 69 6e 67 20 41  I3REF: Tracing A
1b1e0 6e 64 20 50 72 6f 66 69 6c 69 6e 67 20 46 75 6e  nd Profiling Fun
1b1f0 63 74 69 6f 6e 73 0a 2a 2a 0a 2a 2a 20 54 68 65  ctions.**.** The
1b200 73 65 20 72 6f 75 74 69 6e 65 73 20 72 65 67 69  se routines regi
1b210 73 74 65 72 20 63 61 6c 6c 62 61 63 6b 20 66 75  ster callback fu
1b220 6e 63 74 69 6f 6e 73 20 74 68 61 74 20 63 61 6e  nctions that can
1b230 20 62 65 20 75 73 65 64 20 66 6f 72 0a 2a 2a 20   be used for.** 
1b240 74 72 61 63 69 6e 67 20 61 6e 64 20 70 72 6f 66  tracing and prof
1b250 69 6c 69 6e 67 20 74 68 65 20 65 78 65 63 75 74  iling the execut
1b260 69 6f 6e 20 6f 66 20 53 51 4c 20 73 74 61 74 65  ion of SQL state
1b270 6d 65 6e 74 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ments..**.** ^Th
1b280 65 20 63 61 6c 6c 62 61 63 6b 20 66 75 6e 63 74  e callback funct
1b290 69 6f 6e 20 72 65 67 69 73 74 65 72 65 64 20 62  ion registered b
1b2a0 79 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  y sqlite3_trace(
1b2b0 29 20 69 73 20 69 6e 76 6f 6b 65 64 20 61 74 0a  ) is invoked at.
1b2c0 2a 2a 20 76 61 72 69 6f 75 73 20 74 69 6d 65 73  ** various times
1b2d0 20 77 68 65 6e 20 61 6e 20 53 51 4c 20 73 74 61   when an SQL sta
1b2e0 74 65 6d 65 6e 74 20 69 73 20 62 65 69 6e 67 20  tement is being 
1b2f0 72 75 6e 20 62 79 20 5b 73 71 6c 69 74 65 33 5f  run by [sqlite3_
1b300 73 74 65 70 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65  step()]..** ^The
1b310 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28 29   sqlite3_trace()
1b320 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e 76   callback is inv
1b330 6f 6b 65 64 20 77 69 74 68 20 61 20 55 54 46 2d  oked with a UTF-
1b340 38 20 72 65 6e 64 65 72 69 6e 67 20 6f 66 20 74  8 rendering of t
1b350 68 65 0a 2a 2a 20 53 51 4c 20 73 74 61 74 65 6d  he.** SQL statem
1b360 65 6e 74 20 74 65 78 74 20 61 73 20 74 68 65 20  ent text as the 
1b370 73 74 61 74 65 6d 65 6e 74 20 66 69 72 73 74 20  statement first 
1b380 62 65 67 69 6e 73 20 65 78 65 63 75 74 69 6e 67  begins executing
1b390 2e 0a 2a 2a 20 5e 28 41 64 64 69 74 69 6f 6e 61  ..** ^(Additiona
1b3a0 6c 20 73 71 6c 69 74 65 33 5f 74 72 61 63 65 28  l sqlite3_trace(
1b3b0 29 20 63 61 6c 6c 62 61 63 6b 73 20 6d 69 67 68  ) callbacks migh
1b3c0 74 20 6f 63 63 75 72 0a 2a 2a 20 61 73 20 65 61  t occur.** as ea
1b3d0 63 68 20 74 72 69 67 67 65 72 65 64 20 73 75 62  ch triggered sub
1b3e0 70 72 6f 67 72 61 6d 20 69 73 20 65 6e 74 65 72  program is enter
1b3f0 65 64 2e 20 20 54 68 65 20 63 61 6c 6c 62 61 63  ed.  The callbac
1b400 6b 73 20 66 6f 72 20 74 72 69 67 67 65 72 73 0a  ks for triggers.
1b410 2a 2a 20 63 6f 6e 74 61 69 6e 20 61 20 55 54 46  ** contain a UTF
1b420 2d 38 20 53 51 4c 20 63 6f 6d 6d 65 6e 74 20 74  -8 SQL comment t
1b430 68 61 74 20 69 64 65 6e 74 69 66 69 65 73 20 74  hat identifies t
1b440 68 65 20 74 72 69 67 67 65 72 2e 29 5e 0a 2a 2a  he trigger.)^.**
1b450 0a 2a 2a 20 5e 54 68 65 20 63 61 6c 6c 62 61 63  .** ^The callbac
1b460 6b 20 66 75 6e 63 74 69 6f 6e 20 72 65 67 69 73  k function regis
1b470 74 65 72 65 64 20 62 79 20 73 71 6c 69 74 65 33  tered by sqlite3
1b480 5f 70 72 6f 66 69 6c 65 28 29 20 69 73 20 69 6e  _profile() is in
1b490 76 6f 6b 65 64 0a 2a 2a 20 61 73 20 65 61 63 68  voked.** as each
1b4a0 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 66   SQL statement f
1b4b0 69 6e 69 73 68 65 73 2e 20 20 5e 54 68 65 20 70  inishes.  ^The p
1b4c0 72 6f 66 69 6c 65 20 63 61 6c 6c 62 61 63 6b 20  rofile callback 
1b4d0 63 6f 6e 74 61 69 6e 73 0a 2a 2a 20 74 68 65 20  contains.** the 
1b4e0 6f 72 69 67 69 6e 61 6c 20 73 74 61 74 65 6d 65  original stateme
1b4f0 6e 74 20 74 65 78 74 20 61 6e 64 20 61 6e 20 65  nt text and an e
1b500 73 74 69 6d 61 74 65 20 6f 66 20 77 61 6c 6c 2d  stimate of wall-
1b510 63 6c 6f 63 6b 20 74 69 6d 65 0a 2a 2a 20 6f 66  clock time.** of
1b520 20 68 6f 77 20 6c 6f 6e 67 20 74 68 61 74 20 73   how long that s
1b530 74 61 74 65 6d 65 6e 74 20 74 6f 6f 6b 20 74 6f  tatement took to
1b540 20 72 75 6e 2e 20 20 5e 54 68 65 20 70 72 6f 66   run.  ^The prof
1b550 69 6c 65 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20  ile callback.** 
1b560 74 69 6d 65 20 69 73 20 69 6e 20 75 6e 69 74 73  time is in units
1b570 20 6f 66 20 6e 61 6e 6f 73 65 63 6f 6e 64 73 2c   of nanoseconds,
1b580 20 68 6f 77 65 76 65 72 20 74 68 65 20 63 75 72   however the cur
1b590 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74 61 74  rent implementat
1b5a0 69 6f 6e 0a 2a 2a 20 69 73 20 6f 6e 6c 79 20 63  ion.** is only c
1b5b0 61 70 61 62 6c 65 20 6f 66 20 6d 69 6c 6c 69 73  apable of millis
1b5c0 65 63 6f 6e 64 20 72 65 73 6f 6c 75 74 69 6f 6e  econd resolution
1b5d0 20 73 6f 20 74 68 65 20 73 69 78 20 6c 65 61 73   so the six leas
1b5e0 74 20 73 69 67 6e 69 66 69 63 61 6e 74 0a 2a 2a  t significant.**
1b5f0 20 64 69 67 69 74 73 20 69 6e 20 74 68 65 20 74   digits in the t
1b600 69 6d 65 20 61 72 65 20 6d 65 61 6e 69 6e 67 6c  ime are meaningl
1b610 65 73 73 2e 20 20 46 75 74 75 72 65 20 76 65 72  ess.  Future ver
1b620 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 0a  sions of SQLite.
1b630 2a 2a 20 6d 69 67 68 74 20 70 72 6f 76 69 64 65  ** might provide
1b640 20 67 72 65 61 74 65 72 20 72 65 73 6f 6c 75 74   greater resolut
1b650 69 6f 6e 20 6f 6e 20 74 68 65 20 70 72 6f 66 69  ion on the profi
1b660 6c 65 72 20 63 61 6c 6c 62 61 63 6b 2e 20 20 54  ler callback.  T
1b670 68 65 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 70 72  he.** sqlite3_pr
1b680 6f 66 69 6c 65 28 29 20 66 75 6e 63 74 69 6f 6e  ofile() function
1b690 20 69 73 20 63 6f 6e 73 69 64 65 72 65 64 20 65   is considered e
1b6a0 78 70 65 72 69 6d 65 6e 74 61 6c 20 61 6e 64 20  xperimental and 
1b6b0 69 73 0a 2a 2a 20 73 75 62 6a 65 63 74 20 74 6f  is.** subject to
1b6c0 20 63 68 61 6e 67 65 20 69 6e 20 66 75 74 75 72   change in futur
1b6d0 65 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  e versions of SQ
1b6e0 4c 69 74 65 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  Lite..*/.void *s
1b6f0 71 6c 69 74 65 33 5f 74 72 61 63 65 28 73 71 6c  qlite3_trace(sql
1b700 69 74 65 33 2a 2c 20 76 6f 69 64 28 2a 78 54 72  ite3*, void(*xTr
1b710 61 63 65 29 28 76 6f 69 64 2a 2c 63 6f 6e 73 74  ace)(void*,const
1b720 20 63 68 61 72 2a 29 2c 20 76 6f 69 64 2a 29 3b   char*), void*);
1b730 0a 53 51 4c 49 54 45 5f 45 58 50 45 52 49 4d 45  .SQLITE_EXPERIME
1b740 4e 54 41 4c 20 76 6f 69 64 20 2a 73 71 6c 69 74  NTAL void *sqlit
1b750 65 33 5f 70 72 6f 66 69 6c 65 28 73 71 6c 69 74  e3_profile(sqlit
1b760 65 33 2a 2c 0a 20 20 20 76 6f 69 64 28 2a 78 50  e3*,.   void(*xP
1b770 72 6f 66 69 6c 65 29 28 76 6f 69 64 2a 2c 63 6f  rofile)(void*,co
1b780 6e 73 74 20 63 68 61 72 2a 2c 73 71 6c 69 74 65  nst char*,sqlite
1b790 33 5f 75 69 6e 74 36 34 29 2c 20 76 6f 69 64 2a  3_uint64), void*
1b7a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
1b7b0 45 46 3a 20 51 75 65 72 79 20 50 72 6f 67 72 65  EF: Query Progre
1b7c0 73 73 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a  ss Callbacks.**.
1b7d0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
1b7e0 70 72 6f 67 72 65 73 73 5f 68 61 6e 64 6c 65 72  progress_handler
1b7f0 28 44 2c 4e 2c 58 2c 50 29 20 69 6e 74 65 72 66  (D,N,X,P) interf
1b800 61 63 65 20 63 61 75 73 65 73 20 74 68 65 20 63  ace causes the c
1b810 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63 74  allback.** funct
1b820 69 6f 6e 20 58 20 74 6f 20 62 65 20 69 6e 76 6f  ion X to be invo
1b830 6b 65 64 20 70 65 72 69 6f 64 69 63 61 6c 6c 79  ked periodically
1b840 20 64 75 72 69 6e 67 20 6c 6f 6e 67 20 72 75 6e   during long run
1b850 6e 69 6e 67 20 63 61 6c 6c 73 20 74 6f 0a 2a 2a  ning calls to.**
1b860 20 5b 73 71 6c 69 74 65 33 5f 65 78 65 63 28 29   [sqlite3_exec()
1b870 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70  ], [sqlite3_step
1b880 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
1b890 5f 67 65 74 5f 74 61 62 6c 65 28 29 5d 20 66 6f  _get_table()] fo
1b8a0 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63 6f  r.** database co
1b8b0 6e 6e 65 63 74 69 6f 6e 20 44 2e 20 20 41 6e 20  nnection D.  An 
1b8c0 65 78 61 6d 70 6c 65 20 75 73 65 20 66 6f 72 20  example use for 
1b8d0 74 68 69 73 0a 2a 2a 20 69 6e 74 65 72 66 61 63  this.** interfac
1b8e0 65 20 69 73 20 74 6f 20 6b 65 65 70 20 61 20 47  e is to keep a G
1b8f0 55 49 20 75 70 64 61 74 65 64 20 64 75 72 69 6e  UI updated durin
1b900 67 20 61 20 6c 61 72 67 65 20 71 75 65 72 79 2e  g a large query.
1b910 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 70 61 72 61  .**.** ^The para
1b920 6d 65 74 65 72 20 50 20 69 73 20 70 61 73 73 65  meter P is passe
1b930 64 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65  d through as the
1b940 20 6f 6e 6c 79 20 70 61 72 61 6d 65 74 65 72 20   only parameter 
1b950 74 6f 20 74 68 65 20 0a 2a 2a 20 63 61 6c 6c 62  to the .** callb
1b960 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 58 2e 20  ack function X. 
1b970 20 5e 54 68 65 20 70 61 72 61 6d 65 74 65 72 20   ^The parameter 
1b980 4e 20 69 73 20 74 68 65 20 6e 75 6d 62 65 72 20  N is the number 
1b990 6f 66 20 0a 2a 2a 20 5b 76 69 72 74 75 61 6c 20  of .** [virtual 
1b9a0 6d 61 63 68 69 6e 65 20 69 6e 73 74 72 75 63 74  machine instruct
1b9b0 69 6f 6e 73 5d 20 74 68 61 74 20 61 72 65 20 65  ions] that are e
1b9c0 76 61 6c 75 61 74 65 64 20 62 65 74 77 65 65 6e  valuated between
1b9d0 20 73 75 63 63 65 73 73 69 76 65 0a 2a 2a 20 69   successive.** i
1b9e0 6e 76 6f 63 61 74 69 6f 6e 73 20 6f 66 20 74 68  nvocations of th
1b9f0 65 20 63 61 6c 6c 62 61 63 6b 20 58 2e 0a 2a 2a  e callback X..**
1ba00 0a 2a 2a 20 5e 4f 6e 6c 79 20 61 20 73 69 6e 67  .** ^Only a sing
1ba10 6c 65 20 70 72 6f 67 72 65 73 73 20 68 61 6e 64  le progress hand
1ba20 6c 65 72 20 6d 61 79 20 62 65 20 64 65 66 69 6e  ler may be defin
1ba30 65 64 20 61 74 20 6f 6e 65 20 74 69 6d 65 20 70  ed at one time p
1ba40 65 72 0a 2a 2a 20 5b 64 61 74 61 62 61 73 65 20  er.** [database 
1ba50 63 6f 6e 6e 65 63 74 69 6f 6e 5d 3b 20 73 65 74  connection]; set
1ba60 74 69 6e 67 20 61 20 6e 65 77 20 70 72 6f 67 72  ting a new progr
1ba70 65 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6e 63  ess handler canc
1ba80 65 6c 73 20 74 68 65 0a 2a 2a 20 6f 6c 64 20 6f  els the.** old o
1ba90 6e 65 2e 20 20 5e 53 65 74 74 69 6e 67 20 70 61  ne.  ^Setting pa
1baa0 72 61 6d 65 74 65 72 20 58 20 74 6f 20 4e 55 4c  rameter X to NUL
1bab0 4c 20 64 69 73 61 62 6c 65 73 20 74 68 65 20 70  L disables the p
1bac0 72 6f 67 72 65 73 73 20 68 61 6e 64 6c 65 72 2e  rogress handler.
1bad0 0a 2a 2a 20 5e 54 68 65 20 70 72 6f 67 72 65 73  .** ^The progres
1bae0 73 20 68 61 6e 64 6c 65 72 20 69 73 20 61 6c 73  s handler is als
1baf0 6f 20 64 69 73 61 62 6c 65 64 20 62 79 20 73 65  o disabled by se
1bb00 74 74 69 6e 67 20 4e 20 74 6f 20 61 20 76 61 6c  tting N to a val
1bb10 75 65 20 6c 65 73 73 0a 2a 2a 20 74 68 61 6e 20  ue less.** than 
1bb20 31 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  1..**.** ^If the
1bb30 20 70 72 6f 67 72 65 73 73 20 63 61 6c 6c 62 61   progress callba
1bb40 63 6b 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ck returns non-z
1bb50 65 72 6f 2c 20 74 68 65 20 6f 70 65 72 61 74 69  ero, the operati
1bb60 6f 6e 20 69 73 0a 2a 2a 20 69 6e 74 65 72 72 75  on is.** interru
1bb70 70 74 65 64 2e 20 20 54 68 69 73 20 66 65 61 74  pted.  This feat
1bb80 75 72 65 20 63 61 6e 20 62 65 20 75 73 65 64 20  ure can be used 
1bb90 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 61 0a 2a  to implement a.*
1bba0 2a 20 22 43 61 6e 63 65 6c 22 20 62 75 74 74 6f  * "Cancel" butto
1bbb0 6e 20 6f 6e 20 61 20 47 55 49 20 70 72 6f 67 72  n on a GUI progr
1bbc0 65 73 73 20 64 69 61 6c 6f 67 20 62 6f 78 2e 0a  ess dialog box..
1bbd0 2a 2a 0a 2a 2a 20 54 68 65 20 70 72 6f 67 72 65  **.** The progre
1bbe0 73 73 20 68 61 6e 64 6c 65 72 20 63 61 6c 6c 62  ss handler callb
1bbf0 61 63 6b 20 6d 75 73 74 20 6e 6f 74 20 64 6f 20  ack must not do 
1bc00 61 6e 79 74 68 69 6e 67 20 74 68 61 74 20 77 69  anything that wi
1bc10 6c 6c 20 6d 6f 64 69 66 79 0a 2a 2a 20 74 68 65  ll modify.** the
1bc20 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1bc30 74 69 6f 6e 20 74 68 61 74 20 69 6e 76 6f 6b 65  tion that invoke
1bc40 64 20 74 68 65 20 70 72 6f 67 72 65 73 73 20 68  d the progress h
1bc50 61 6e 64 6c 65 72 2e 0a 2a 2a 20 4e 6f 74 65 20  andler..** Note 
1bc60 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
1bc70 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
1bc80 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
1bc90 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
1bca0 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
1bcb0 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
1bcc0 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
1bcd0 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
1bce0 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2f 0a  aragraph..**.*/.
1bcf0 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 70 72 6f  void sqlite3_pro
1bd00 67 72 65 73 73 5f 68 61 6e 64 6c 65 72 28 73 71  gress_handler(sq
1bd10 6c 69 74 65 33 2a 2c 20 69 6e 74 2c 20 69 6e 74  lite3*, int, int
1bd20 28 2a 29 28 76 6f 69 64 2a 29 2c 20 76 6f 69 64  (*)(void*), void
1bd30 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  *);../*.** CAPI3
1bd40 52 45 46 3a 20 4f 70 65 6e 69 6e 67 20 41 20 4e  REF: Opening A N
1bd50 65 77 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e  ew Database Conn
1bd60 65 63 74 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ection.**.** ^Th
1bd70 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6f 70 65  ese routines ope
1bd80 6e 20 61 6e 20 53 51 4c 69 74 65 20 64 61 74 61  n an SQLite data
1bd90 62 61 73 65 20 66 69 6c 65 20 61 73 20 73 70 65  base file as spe
1bda0 63 69 66 69 65 64 20 62 79 20 74 68 65 20 0a 2a  cified by the .*
1bdb0 2a 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  * filename argum
1bdc0 65 6e 74 2e 20 5e 54 68 65 20 66 69 6c 65 6e 61  ent. ^The filena
1bdd0 6d 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20 69  me argument is i
1bde0 6e 74 65 72 70 72 65 74 65 64 20 61 73 20 55 54  nterpreted as UT
1bdf0 46 2d 38 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74  F-8 for.** sqlit
1be00 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71  e3_open() and sq
1be10 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20  lite3_open_v2() 
1be20 61 6e 64 20 61 73 20 55 54 46 2d 31 36 20 69 6e  and as UTF-16 in
1be30 20 74 68 65 20 6e 61 74 69 76 65 20 62 79 74 65   the native byte
1be40 0a 2a 2a 20 6f 72 64 65 72 20 66 6f 72 20 73 71  .** order for sq
1be50 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 20  lite3_open16(). 
1be60 5e 28 41 20 5b 64 61 74 61 62 61 73 65 20 63 6f  ^(A [database co
1be70 6e 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65  nnection] handle
1be80 20 69 73 20 75 73 75 61 6c 6c 79 0a 2a 2a 20 72   is usually.** r
1be90 65 74 75 72 6e 65 64 20 69 6e 20 2a 70 70 44 62  eturned in *ppDb
1bea0 2c 20 65 76 65 6e 20 69 66 20 61 6e 20 65 72 72  , even if an err
1beb0 6f 72 20 6f 63 63 75 72 73 2e 20 20 54 68 65 20  or occurs.  The 
1bec0 6f 6e 6c 79 20 65 78 63 65 70 74 69 6f 6e 20 69  only exception i
1bed0 73 20 74 68 61 74 0a 2a 2a 20 69 66 20 53 51 4c  s that.** if SQL
1bee0 69 74 65 20 69 73 20 75 6e 61 62 6c 65 20 74 6f  ite is unable to
1bef0 20 61 6c 6c 6f 63 61 74 65 20 6d 65 6d 6f 72 79   allocate memory
1bf00 20 74 6f 20 68 6f 6c 64 20 74 68 65 20 5b 73 71   to hold the [sq
1bf10 6c 69 74 65 33 5d 20 6f 62 6a 65 63 74 2c 0a 2a  lite3] object,.*
1bf20 2a 20 61 20 4e 55 4c 4c 20 77 69 6c 6c 20 62 65  * a NULL will be
1bf30 20 77 72 69 74 74 65 6e 20 69 6e 74 6f 20 2a 70   written into *p
1bf40 70 44 62 20 69 6e 73 74 65 61 64 20 6f 66 20 61  pDb instead of a
1bf50 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20   pointer to the 
1bf60 5b 73 71 6c 69 74 65 33 5d 0a 2a 2a 20 6f 62 6a  [sqlite3].** obj
1bf70 65 63 74 2e 29 5e 20 5e 28 49 66 20 74 68 65 20  ect.)^ ^(If the 
1bf80 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65 6e  database is open
1bf90 65 64 20 28 61 6e 64 2f 6f 72 20 63 72 65 61 74  ed (and/or creat
1bfa0 65 64 29 20 73 75 63 63 65 73 73 66 75 6c 6c 79  ed) successfully
1bfb0 2c 20 74 68 65 6e 0a 2a 2a 20 5b 53 51 4c 49 54  , then.** [SQLIT
1bfc0 45 5f 4f 4b 5d 20 69 73 20 72 65 74 75 72 6e 65  E_OK] is returne
1bfd0 64 2e 20 20 4f 74 68 65 72 77 69 73 65 20 61 6e  d.  Otherwise an
1bfe0 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 73   [error code] is
1bff0 20 72 65 74 75 72 6e 65 64 2e 29 5e 20 5e 54 68   returned.)^ ^Th
1c000 65 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 65 72  e.** [sqlite3_er
1c010 72 6d 73 67 28 29 5d 20 6f 72 20 5b 73 71 6c 69  rmsg()] or [sqli
1c020 74 65 33 5f 65 72 72 6d 73 67 31 36 28 29 5d 20  te3_errmsg16()] 
1c030 72 6f 75 74 69 6e 65 73 20 63 61 6e 20 62 65 20  routines can be 
1c040 75 73 65 64 20 74 6f 20 6f 62 74 61 69 6e 0a 2a  used to obtain.*
1c050 2a 20 61 6e 20 45 6e 67 6c 69 73 68 20 6c 61 6e  * an English lan
1c060 67 75 61 67 65 20 64 65 73 63 72 69 70 74 69 6f  guage descriptio
1c070 6e 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20 66  n of the error f
1c080 6f 6c 6c 6f 77 69 6e 67 20 61 20 66 61 69 6c 75  ollowing a failu
1c090 72 65 20 6f 66 20 61 6e 79 0a 2a 2a 20 6f 66 20  re of any.** of 
1c0a0 74 68 65 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e  the sqlite3_open
1c0b0 28 29 20 72 6f 75 74 69 6e 65 73 2e 0a 2a 2a 0a  () routines..**.
1c0c0 2a 2a 20 5e 54 68 65 20 64 65 66 61 75 6c 74 20  ** ^The default 
1c0d0 65 6e 63 6f 64 69 6e 67 20 66 6f 72 20 74 68 65  encoding for the
1c0e0 20 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62   database will b
1c0f0 65 20 55 54 46 2d 38 20 69 66 0a 2a 2a 20 73 71  e UTF-8 if.** sq
1c100 6c 69 74 65 33 5f 6f 70 65 6e 28 29 20 6f 72 20  lite3_open() or 
1c110 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28  sqlite3_open_v2(
1c120 29 20 69 73 20 63 61 6c 6c 65 64 20 61 6e 64 0a  ) is called and.
1c130 2a 2a 20 55 54 46 2d 31 36 20 69 6e 20 74 68 65  ** UTF-16 in the
1c140 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
1c150 65 72 20 69 66 20 73 71 6c 69 74 65 33 5f 6f 70  er if sqlite3_op
1c160 65 6e 31 36 28 29 20 69 73 20 75 73 65 64 2e 0a  en16() is used..
1c170 2a 2a 0a 2a 2a 20 57 68 65 74 68 65 72 20 6f 72  **.** Whether or
1c180 20 6e 6f 74 20 61 6e 20 65 72 72 6f 72 20 6f 63   not an error oc
1c190 63 75 72 73 20 77 68 65 6e 20 69 74 20 69 73 20  curs when it is 
1c1a0 6f 70 65 6e 65 64 2c 20 72 65 73 6f 75 72 63 65  opened, resource
1c1b0 73 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  s.** associated 
1c1c0 77 69 74 68 20 74 68 65 20 5b 64 61 74 61 62 61  with the [databa
1c1d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 68  se connection] h
1c1e0 61 6e 64 6c 65 20 73 68 6f 75 6c 64 20 62 65 20  andle should be 
1c1f0 72 65 6c 65 61 73 65 64 20 62 79 0a 2a 2a 20 70  released by.** p
1c200 61 73 73 69 6e 67 20 69 74 20 74 6f 20 5b 73 71  assing it to [sq
1c210 6c 69 74 65 33 5f 63 6c 6f 73 65 28 29 5d 20 77  lite3_close()] w
1c220 68 65 6e 20 69 74 20 69 73 20 6e 6f 20 6c 6f 6e  hen it is no lon
1c230 67 65 72 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a  ger required..**
1c240 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
1c250 6f 70 65 6e 5f 76 32 28 29 20 69 6e 74 65 72 66  open_v2() interf
1c260 61 63 65 20 77 6f 72 6b 73 20 6c 69 6b 65 20 73  ace works like s
1c270 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29 0a 2a 2a  qlite3_open().**
1c280 20 65 78 63 65 70 74 20 74 68 61 74 20 69 74 20   except that it 
1c290 61 63 63 65 70 74 73 20 74 77 6f 20 61 64 64 69  accepts two addi
1c2a0 74 69 6f 6e 61 6c 20 70 61 72 61 6d 65 74 65 72  tional parameter
1c2b0 73 20 66 6f 72 20 61 64 64 69 74 69 6f 6e 61 6c  s for additional
1c2c0 20 63 6f 6e 74 72 6f 6c 0a 2a 2a 20 6f 76 65 72   control.** over
1c2d0 20 74 68 65 20 6e 65 77 20 64 61 74 61 62 61 73   the new databas
1c2e0 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 5e  e connection.  ^
1c2f0 28 54 68 65 20 66 6c 61 67 73 20 70 61 72 61 6d  (The flags param
1c300 65 74 65 72 20 74 6f 0a 2a 2a 20 73 71 6c 69 74  eter to.** sqlit
1c310 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 63 61 6e  e3_open_v2() can
1c320 20 74 61 6b 65 20 6f 6e 65 20 6f 66 0a 2a 2a 20   take one of.** 
1c330 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68  the following th
1c340 72 65 65 20 76 61 6c 75 65 73 2c 20 6f 70 74 69  ree values, opti
1c350 6f 6e 61 6c 6c 79 20 63 6f 6d 62 69 6e 65 64 20  onally combined 
1c360 77 69 74 68 20 74 68 65 20 0a 2a 2a 20 5b 53 51  with the .** [SQ
1c370 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55 54 45  LITE_OPEN_NOMUTE
1c380 58 5d 2c 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e  X], [SQLITE_OPEN
1c390 5f 46 55 4c 4c 4d 55 54 45 58 5d 2c 20 5b 53 51  _FULLMUTEX], [SQ
1c3a0 4c 49 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44  LITE_OPEN_SHARED
1c3b0 43 41 43 48 45 5d 2c 0a 2a 2a 20 61 6e 64 2f 6f  CACHE],.** and/o
1c3c0 72 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 50  r [SQLITE_OPEN_P
1c3d0 52 49 56 41 54 45 43 41 43 48 45 5d 20 66 6c 61  RIVATECACHE] fla
1c3e0 67 73 3a 29 5e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e  gs:)^.**.** <dl>
1c3f0 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c 49 54  .** ^(<dt>[SQLIT
1c400 45 5f 4f 50 45 4e 5f 52 45 41 44 4f 4e 4c 59 5d  E_OPEN_READONLY]
1c410 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65  </dt>.** <dd>The
1c420 20 64 61 74 61 62 61 73 65 20 69 73 20 6f 70 65   database is ope
1c430 6e 65 64 20 69 6e 20 72 65 61 64 2d 6f 6e 6c 79  ned in read-only
1c440 20 6d 6f 64 65 2e 20 20 49 66 20 74 68 65 20 64   mode.  If the d
1c450 61 74 61 62 61 73 65 20 64 6f 65 73 20 6e 6f 74  atabase does not
1c460 0a 2a 2a 20 61 6c 72 65 61 64 79 20 65 78 69 73  .** already exis
1c470 74 2c 20 61 6e 20 65 72 72 6f 72 20 69 73 20 72  t, an error is r
1c480 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29 5e 0a  eturned.</dd>)^.
1c490 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53 51 4c  **.** ^(<dt>[SQL
1c4a0 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1c4b0 54 45 5d 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e  TE]</dt>.** <dd>
1c4c0 54 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20  The database is 
1c4d0 6f 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 69  opened for readi
1c4e0 6e 67 20 61 6e 64 20 77 72 69 74 69 6e 67 20 69  ng and writing i
1c4f0 66 20 70 6f 73 73 69 62 6c 65 2c 20 6f 72 20 72  f possible, or r
1c500 65 61 64 69 6e 67 0a 2a 2a 20 6f 6e 6c 79 20 69  eading.** only i
1c510 66 20 74 68 65 20 66 69 6c 65 20 69 73 20 77 72  f the file is wr
1c520 69 74 65 20 70 72 6f 74 65 63 74 65 64 20 62 79  ite protected by
1c530 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73   the operating s
1c540 79 73 74 65 6d 2e 20 20 49 6e 20 65 69 74 68 65  ystem.  In eithe
1c550 72 0a 2a 2a 20 63 61 73 65 20 74 68 65 20 64 61  r.** case the da
1c560 74 61 62 61 73 65 20 6d 75 73 74 20 61 6c 72 65  tabase must alre
1c570 61 64 79 20 65 78 69 73 74 2c 20 6f 74 68 65 72  ady exist, other
1c580 77 69 73 65 20 61 6e 20 65 72 72 6f 72 20 69 73  wise an error is
1c590 20 72 65 74 75 72 6e 65 64 2e 3c 2f 64 64 3e 29   returned.</dd>)
1c5a0 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 5b 53  ^.**.** ^(<dt>[S
1c5b0 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57  QLITE_OPEN_READW
1c5c0 52 49 54 45 5d 20 7c 20 5b 53 51 4c 49 54 45 5f  RITE] | [SQLITE_
1c5d0 4f 50 45 4e 5f 43 52 45 41 54 45 5d 3c 2f 64 74  OPEN_CREATE]</dt
1c5e0 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 64 61 74  >.** <dd>The dat
1c5f0 61 62 61 73 65 20 69 73 20 6f 70 65 6e 65 64 20  abase is opened 
1c600 66 6f 72 20 72 65 61 64 69 6e 67 20 61 6e 64 20  for reading and 
1c610 77 72 69 74 69 6e 67 2c 20 61 6e 64 20 69 73 20  writing, and is 
1c620 63 72 65 61 74 65 64 20 69 66 0a 2a 2a 20 69 74  created if.** it
1c630 20 64 6f 65 73 20 6e 6f 74 20 61 6c 72 65 61 64   does not alread
1c640 79 20 65 78 69 73 74 2e 20 54 68 69 73 20 69 73  y exist. This is
1c650 20 74 68 65 20 62 65 68 61 76 69 6f 72 20 74 68   the behavior th
1c660 61 74 20 69 73 20 61 6c 77 61 79 73 20 75 73 65  at is always use
1c670 64 20 66 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  d for.** sqlite3
1c680 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73 71 6c 69  _open() and sqli
1c690 74 65 33 5f 6f 70 65 6e 31 36 28 29 2e 3c 2f 64  te3_open16().</d
1c6a0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2a  d>)^.** </dl>.**
1c6b0 0a 2a 2a 20 49 66 20 74 68 65 20 33 72 64 20 70  .** If the 3rd p
1c6c0 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71 6c 69  arameter to sqli
1c6d0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 20 69 73  te3_open_v2() is
1c6e0 20 6e 6f 74 20 6f 6e 65 20 6f 66 20 74 68 65 0a   not one of the.
1c6f0 2a 2a 20 63 6f 6d 62 69 6e 61 74 69 6f 6e 73 20  ** combinations 
1c700 73 68 6f 77 6e 20 61 62 6f 76 65 20 6f 72 20 6f  shown above or o
1c710 6e 65 20 6f 66 20 74 68 65 20 63 6f 6d 62 69 6e  ne of the combin
1c720 61 74 69 6f 6e 73 20 73 68 6f 77 6e 20 61 62 6f  ations shown abo
1c730 76 65 20 63 6f 6d 62 69 6e 65 64 0a 2a 2a 20 77  ve combined.** w
1c740 69 74 68 20 74 68 65 20 5b 53 51 4c 49 54 45 5f  ith the [SQLITE_
1c750 4f 50 45 4e 5f 4e 4f 4d 55 54 45 58 5d 2c 20 5b  OPEN_NOMUTEX], [
1c760 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c  SQLITE_OPEN_FULL
1c770 4d 55 54 45 58 5d 2c 0a 2a 2a 20 5b 53 51 4c 49  MUTEX],.** [SQLI
1c780 54 45 5f 4f 50 45 4e 5f 53 48 41 52 45 44 43 41  TE_OPEN_SHAREDCA
1c790 43 48 45 5d 20 61 6e 64 2f 6f 72 20 5b 53 51 4c  CHE] and/or [SQL
1c7a0 49 54 45 5f 4f 50 45 4e 5f 50 52 49 56 41 54 45  ITE_OPEN_PRIVATE
1c7b0 43 41 43 48 45 5d 20 66 6c 61 67 73 2c 0a 2a 2a  CACHE] flags,.**
1c7c0 20 74 68 65 6e 20 74 68 65 20 62 65 68 61 76 69   then the behavi
1c7d0 6f 72 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e  or is undefined.
1c7e0 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 5b  .**.** ^If the [
1c7f0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 4e 4f 4d 55  SQLITE_OPEN_NOMU
1c800 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65 74  TEX] flag is set
1c810 2c 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  , then the datab
1c820 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 0a 2a  ase connection.*
1c830 2a 20 6f 70 65 6e 73 20 69 6e 20 74 68 65 20 6d  * opens in the m
1c840 75 6c 74 69 2d 74 68 72 65 61 64 20 5b 74 68 72  ulti-thread [thr
1c850 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 61 73 20  eading mode] as 
1c860 6c 6f 6e 67 20 61 73 20 74 68 65 20 73 69 6e 67  long as the sing
1c870 6c 65 2d 74 68 72 65 61 64 0a 2a 2a 20 6d 6f 64  le-thread.** mod
1c880 65 20 68 61 73 20 6e 6f 74 20 62 65 65 6e 20 73  e has not been s
1c890 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74 69  et at compile-ti
1c8a0 6d 65 20 6f 72 20 73 74 61 72 74 2d 74 69 6d 65  me or start-time
1c8b0 2e 20 20 5e 49 66 20 74 68 65 0a 2a 2a 20 5b 53  .  ^If the.** [S
1c8c0 51 4c 49 54 45 5f 4f 50 45 4e 5f 46 55 4c 4c 4d  QLITE_OPEN_FULLM
1c8d0 55 54 45 58 5d 20 66 6c 61 67 20 69 73 20 73 65  UTEX] flag is se
1c8e0 74 20 74 68 65 6e 20 74 68 65 20 64 61 74 61 62  t then the datab
1c8f0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6f  ase connection o
1c900 70 65 6e 73 0a 2a 2a 20 69 6e 20 74 68 65 20 73  pens.** in the s
1c910 65 72 69 61 6c 69 7a 65 64 20 5b 74 68 72 65 61  erialized [threa
1c920 64 69 6e 67 20 6d 6f 64 65 5d 20 75 6e 6c 65 73  ding mode] unles
1c930 73 20 73 69 6e 67 6c 65 2d 74 68 72 65 61 64 20  s single-thread 
1c940 77 61 73 0a 2a 2a 20 70 72 65 76 69 6f 75 73 6c  was.** previousl
1c950 79 20 73 65 6c 65 63 74 65 64 20 61 74 20 63 6f  y selected at co
1c960 6d 70 69 6c 65 2d 74 69 6d 65 20 6f 72 20 73 74  mpile-time or st
1c970 61 72 74 2d 74 69 6d 65 2e 0a 2a 2a 20 5e 54 68  art-time..** ^Th
1c980 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53  e [SQLITE_OPEN_S
1c990 48 41 52 45 44 43 41 43 48 45 5d 20 66 6c 61 67  HAREDCACHE] flag
1c9a0 20 63 61 75 73 65 73 20 74 68 65 20 64 61 74 61   causes the data
1c9b0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
1c9c0 74 6f 20 62 65 0a 2a 2a 20 65 6c 69 67 69 62 6c  to be.** eligibl
1c9d0 65 20 74 6f 20 75 73 65 20 5b 73 68 61 72 65 64  e to use [shared
1c9e0 20 63 61 63 68 65 20 6d 6f 64 65 5d 2c 20 72 65   cache mode], re
1c9f0 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68 65 74  gardless of whet
1ca00 68 65 72 20 6f 72 20 6e 6f 74 20 73 68 61 72 65  her or not share
1ca10 64 0a 2a 2a 20 63 61 63 68 65 20 69 73 20 65 6e  d.** cache is en
1ca20 61 62 6c 65 64 20 75 73 69 6e 67 20 5b 73 71 6c  abled using [sql
1ca30 69 74 65 33 5f 65 6e 61 62 6c 65 5f 73 68 61 72  ite3_enable_shar
1ca40 65 64 5f 63 61 63 68 65 28 29 5d 2e 20 20 5e 54  ed_cache()].  ^T
1ca50 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4f 50  he.** [SQLITE_OP
1ca60 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45 5d  EN_PRIVATECACHE]
1ca70 20 66 6c 61 67 20 63 61 75 73 65 73 20 74 68 65   flag causes the
1ca80 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1ca90 74 69 6f 6e 20 74 6f 20 6e 6f 74 0a 2a 2a 20 70  tion to not.** p
1caa0 61 72 74 69 63 69 70 61 74 65 20 69 6e 20 5b 73  articipate in [s
1cab0 68 61 72 65 64 20 63 61 63 68 65 20 6d 6f 64 65  hared cache mode
1cac0 5d 20 65 76 65 6e 20 69 66 20 69 74 20 69 73 20  ] even if it is 
1cad0 65 6e 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  enabled..**.** ^
1cae0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
1caf0 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f  eter to sqlite3_
1cb00 6f 70 65 6e 5f 76 32 28 29 20 69 73 20 74 68 65  open_v2() is the
1cb10 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a 20   name of the.** 
1cb20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f 62  [sqlite3_vfs] ob
1cb30 6a 65 63 74 20 74 68 61 74 20 64 65 66 69 6e 65  ject that define
1cb40 73 20 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20  s the operating 
1cb50 73 79 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65  system interface
1cb60 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 6e 65 77   that.** the new
1cb70 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
1cb80 74 69 6f 6e 20 73 68 6f 75 6c 64 20 75 73 65 2e  tion should use.
1cb90 20 20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68    ^If the fourth
1cba0 20 70 61 72 61 6d 65 74 65 72 20 69 73 0a 2a 2a   parameter is.**
1cbb0 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20   a NULL pointer 
1cbc0 74 68 65 6e 20 74 68 65 20 64 65 66 61 75 6c 74  then the default
1cbd0 20 5b 73 71 6c 69 74 65 33 5f 76 66 73 5d 20 6f   [sqlite3_vfs] o
1cbe0 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 0a 2a  bject is used..*
1cbf0 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 66 69 6c  *.** ^If the fil
1cc00 65 6e 61 6d 65 20 69 73 20 22 3a 6d 65 6d 6f 72  ename is ":memor
1cc10 79 3a 22 2c 20 74 68 65 6e 20 61 20 70 72 69 76  y:", then a priv
1cc20 61 74 65 2c 20 74 65 6d 70 6f 72 61 72 79 20 69  ate, temporary i
1cc30 6e 2d 6d 65 6d 6f 72 79 20 64 61 74 61 62 61 73  n-memory databas
1cc40 65 0a 2a 2a 20 69 73 20 63 72 65 61 74 65 64 20  e.** is created 
1cc50 66 6f 72 20 74 68 65 20 63 6f 6e 6e 65 63 74 69  for the connecti
1cc60 6f 6e 2e 20 20 5e 54 68 69 73 20 69 6e 2d 6d 65  on.  ^This in-me
1cc70 6d 6f 72 79 20 64 61 74 61 62 61 73 65 20 77 69  mory database wi
1cc80 6c 6c 20 76 61 6e 69 73 68 20 77 68 65 6e 0a 2a  ll vanish when.*
1cc90 2a 20 74 68 65 20 64 61 74 61 62 61 73 65 20 63  * the database c
1cca0 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 63 6c 6f  onnection is clo
1ccb0 73 65 64 2e 20 20 46 75 74 75 72 65 20 76 65 72  sed.  Future ver
1ccc0 73 69 6f 6e 73 20 6f 66 20 53 51 4c 69 74 65 20  sions of SQLite 
1ccd0 6d 69 67 68 74 0a 2a 2a 20 6d 61 6b 65 20 75 73  might.** make us
1cce0 65 20 6f 66 20 61 64 64 69 74 69 6f 6e 61 6c 20  e of additional 
1ccf0 73 70 65 63 69 61 6c 20 66 69 6c 65 6e 61 6d 65  special filename
1cd00 73 20 74 68 61 74 20 62 65 67 69 6e 20 77 69 74  s that begin wit
1cd10 68 20 74 68 65 20 22 3a 22 20 63 68 61 72 61 63  h the ":" charac
1cd20 74 65 72 2e 0a 2a 2a 20 49 74 20 69 73 20 72 65  ter..** It is re
1cd30 63 6f 6d 6d 65 6e 64 65 64 20 74 68 61 74 20 77  commended that w
1cd40 68 65 6e 20 61 20 64 61 74 61 62 61 73 65 20 66  hen a database f
1cd50 69 6c 65 6e 61 6d 65 20 61 63 74 75 61 6c 6c 79  ilename actually
1cd60 20 64 6f 65 73 20 62 65 67 69 6e 20 77 69 74 68   does begin with
1cd70 0a 2a 2a 20 61 20 22 3a 22 20 63 68 61 72 61 63  .** a ":" charac
1cd80 74 65 72 20 79 6f 75 20 73 68 6f 75 6c 64 20 70  ter you should p
1cd90 72 65 66 69 78 20 74 68 65 20 66 69 6c 65 6e 61  refix the filena
1cda0 6d 65 20 77 69 74 68 20 61 20 70 61 74 68 6e 61  me with a pathna
1cdb0 6d 65 20 73 75 63 68 20 61 73 0a 2a 2a 20 22 2e  me such as.** ".
1cdc0 2f 22 20 74 6f 20 61 76 6f 69 64 20 61 6d 62 69  /" to avoid ambi
1cdd0 67 75 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66  guity..**.** ^If
1cde0 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1cdf0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1ce00 2c 20 74 68 65 6e 20 61 20 70 72 69 76 61 74 65  , then a private
1ce10 2c 20 74 65 6d 70 6f 72 61 72 79 0a 2a 2a 20 6f  , temporary.** o
1ce20 6e 2d 64 69 73 6b 20 64 61 74 61 62 61 73 65 20  n-disk database 
1ce30 77 69 6c 6c 20 62 65 20 63 72 65 61 74 65 64 2e  will be created.
1ce40 20 20 5e 54 68 69 73 20 70 72 69 76 61 74 65 20    ^This private 
1ce50 64 61 74 61 62 61 73 65 20 77 69 6c 6c 20 62 65  database will be
1ce60 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c  .** automaticall
1ce70 79 20 64 65 6c 65 74 65 64 20 61 73 20 73 6f 6f  y deleted as soo
1ce80 6e 20 61 73 20 74 68 65 20 64 61 74 61 62 61 73  n as the databas
1ce90 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20  e connection is 
1cea0 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49  closed..**.** ^I
1ceb0 66 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 20 69  f URI filename i
1cec0 6e 74 65 72 70 72 65 74 61 74 69 6f 6e 20 69 73  nterpretation is
1ced0 20 65 6e 61 62 6c 65 64 2c 20 61 6e 64 20 74 68   enabled, and th
1cee0 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67 75 6d  e filename argum
1cef0 65 6e 74 0a 2a 2a 20 62 65 67 69 6e 73 20 77 69  ent.** begins wi
1cf00 74 68 20 22 66 69 6c 65 3a 22 2c 20 74 68 65 6e  th "file:", then
1cf10 20 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 69 73   the filename is
1cf20 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73 20   interpreted as 
1cf30 61 20 55 52 49 2e 20 5e 55 52 49 0a 2a 2a 20 66  a URI. ^URI.** f
1cf40 69 6c 65 6e 61 6d 65 20 69 6e 74 65 72 70 72 65  ilename interpre
1cf50 74 61 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  tation is enable
1cf60 64 20 69 66 20 74 68 65 20 5b 53 51 4c 49 54 45  d if the [SQLITE
1cf70 5f 4f 50 45 4e 5f 55 52 49 5d 20 66 6c 61 67 20  _OPEN_URI] flag 
1cf80 69 73 0a 2a 2a 20 69 73 20 73 65 74 20 69 6e 20  is.** is set in 
1cf90 74 68 65 20 66 6f 75 72 74 68 20 61 72 67 75 6d  the fourth argum
1cfa0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 6f  ent to sqlite3_o
1cfb0 70 65 6e 5f 76 32 28 29 2c 20 6f 72 20 69 66 20  pen_v2(), or if 
1cfc0 69 74 20 68 61 73 0a 2a 2a 20 62 65 65 6e 20 65  it has.** been e
1cfd0 6e 61 62 6c 65 64 20 67 6c 6f 62 61 6c 6c 79 20  nabled globally 
1cfe0 75 73 69 6e 67 20 74 68 65 20 5b 53 51 4c 49 54  using the [SQLIT
1cff0 45 5f 43 4f 4e 46 49 47 5f 55 52 49 5d 20 6f 70  E_CONFIG_URI] op
1d000 74 69 6f 6e 20 77 69 74 68 20 74 68 65 0a 2a 2a  tion with the.**
1d010 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e 66 69 67   [sqlite3_config
1d020 28 29 5d 20 6d 65 74 68 6f 64 2e 20 0a 2a 2a 0a  ()] method. .**.
1d030 2a 2a 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  ** URI filenames
1d040 20 61 72 65 20 70 61 72 73 65 64 20 61 63 63 6f   are parsed acco
1d050 72 64 69 6e 67 20 74 6f 20 52 46 43 20 31 37 33  rding to RFC 173
1d060 38 2e 20 49 66 20 74 68 65 20 55 52 49 20 63 6f  8. If the URI co
1d070 6e 74 61 69 6e 73 20 61 6e 0a 2a 2a 20 27 61 75  ntains an.** 'au
1d080 74 68 6f 72 69 74 79 27 2c 20 74 68 65 6e 20 69  thority', then i
1d090 74 20 6d 75 73 74 20 62 65 20 65 69 74 68 65 72  t must be either
1d0a0 20 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67   an empty string
1d0b0 20 6f 72 20 74 68 65 20 73 74 72 69 6e 67 20 0a   or the string .
1d0c0 2a 2a 20 22 6c 6f 63 61 6c 68 6f 73 74 22 2e 20  ** "localhost". 
1d0d0 5e 49 66 20 74 68 65 20 61 75 74 68 6f 72 69 74  ^If the authorit
1d0e0 79 20 69 73 20 6e 6f 74 20 61 6e 20 65 6d 70 74  y is not an empt
1d0f0 79 20 73 74 72 69 6e 67 20 6f 72 20 22 6c 6f 63  y string or "loc
1d100 61 6c 68 6f 73 74 22 2c 20 61 6e 20 0a 2a 2a 20  alhost", an .** 
1d110 65 72 72 6f 72 20 69 73 20 72 65 74 75 72 6e 65  error is returne
1d120 64 20 74 6f 20 74 68 65 20 63 61 6c 6c 65 72 2e  d to the caller.
1d130 20 5e 54 68 65 20 27 66 72 61 67 6d 65 6e 74 27   ^The 'fragment'
1d140 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20   component of a 
1d150 55 52 49 2c 20 69 66 20 0a 2a 2a 20 70 72 65 73  URI, if .** pres
1d160 65 6e 74 2c 20 69 73 20 61 6c 77 61 79 73 20 69  ent, is always i
1d170 67 6e 6f 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 53  gnored..**.** ^S
1d180 51 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 27  QLite uses the '
1d190 70 61 74 68 27 20 63 6f 6d 70 6f 6e 65 6e 74 20  path' component 
1d1a0 6f 66 20 74 68 65 20 55 52 49 20 61 73 20 74 68  of the URI as th
1d1b0 65 20 70 61 74 68 20 74 6f 20 74 68 65 20 64 61  e path to the da
1d1c0 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a 20 74  tabase file.** t
1d1d0 6f 20 6f 70 65 6e 2e 20 5e 49 66 20 74 68 65 20  o open. ^If the 
1d1e0 70 61 74 68 20 62 65 67 69 6e 73 20 77 69 74 68  path begins with
1d1f0 20 61 20 27 2f 27 20 63 68 61 72 61 63 74 65 72   a '/' character
1d200 2c 20 74 68 65 6e 20 69 74 20 69 73 20 69 6e 74  , then it is int
1d210 65 72 70 72 65 74 65 64 20 61 73 0a 2a 2a 20 61  erpreted as.** a
1d220 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74 68 2e  n absolute path.
1d230 20 5e 49 66 20 69 74 20 64 6f 65 73 20 6e 6f 74   ^If it does not
1d240 20 62 65 67 69 6e 20 77 69 74 68 20 61 20 27 2f   begin with a '/
1d250 27 2c 20 69 74 20 69 73 20 69 6e 74 65 72 70 72  ', it is interpr
1d260 65 74 65 64 20 61 73 20 61 20 0a 2a 2a 20 72 65  eted as a .** re
1d270 6c 61 74 69 76 65 20 70 61 74 68 2e 20 5e 4f 6e  lative path. ^On
1d280 20 77 69 6e 64 6f 77 73 2c 20 74 68 65 20 66 69   windows, the fi
1d290 72 73 74 20 63 6f 6d 70 6f 6e 65 6e 74 20 6f 66  rst component of
1d2a0 20 61 6e 20 61 62 73 6f 6c 75 74 65 20 70 61 74   an absolute pat
1d2b0 68 20 0a 2a 2a 20 69 73 20 61 20 64 72 69 76 65  h .** is a drive
1d2c0 20 73 70 65 63 69 66 69 63 61 74 69 6f 6e 20 28   specification (
1d2d0 65 2e 67 2e 20 22 43 3a 22 29 2e 0a 2a 2a 0a 2a  e.g. "C:")..**.*
1d2e0 2a 20 54 68 65 20 71 75 65 72 79 20 63 6f 6d 70  * The query comp
1d2f0 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52 49 20 6d  onent of a URI m
1d300 61 79 20 63 6f 6e 74 61 69 6e 20 70 61 72 61 6d  ay contain param
1d310 65 74 65 72 73 20 74 68 61 74 20 61 72 65 20 69  eters that are i
1d320 6e 74 65 72 70 72 65 74 65 64 0a 2a 2a 20 65 69  nterpreted.** ei
1d330 74 68 65 72 20 62 79 20 53 51 4c 69 74 65 20 69  ther by SQLite i
1d340 74 73 65 6c 66 2c 20 6f 72 20 62 79 20 61 20 5b  tself, or by a [
1d350 73 71 6c 69 74 65 33 5f 76 66 73 20 7c 20 63 75  sqlite3_vfs | cu
1d360 73 74 6f 6d 20 56 46 53 20 69 6d 70 6c 65 6d 65  stom VFS impleme
1d370 6e 74 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 53 51 4c  ntation]..** SQL
1d380 69 74 65 20 69 6e 74 65 72 70 72 65 74 73 20 74  ite interprets t
1d390 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 74 68 72  he following thr
1d3a0 65 65 20 71 75 65 72 79 20 70 61 72 61 6d 65 74  ee query paramet
1d3b0 65 72 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a  ers:.**.** <ul>.
1d3c0 2a 2a 20 20 20 3c 6c 69 3e 20 3c 62 3e 76 66 73  **   <li> <b>vfs
1d3d0 3c 2f 62 3e 3a 20 5e 54 68 65 20 22 76 66 73 22  </b>: ^The "vfs"
1d3e0 20 70 61 72 61 6d 65 74 65 72 20 6d 61 79 20 62   parameter may b
1d3f0 65 20 75 73 65 64 20 74 6f 20 73 70 65 63 69 66  e used to specif
1d400 79 20 74 68 65 20 6e 61 6d 65 20 6f 66 0a 2a 2a  y the name of.**
1d410 20 20 20 20 20 61 20 56 46 53 20 6f 62 6a 65 63       a VFS objec
1d420 74 20 74 68 61 74 20 70 72 6f 76 69 64 65 73 20  t that provides 
1d430 74 68 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79  the operating sy
1d440 73 74 65 6d 20 69 6e 74 65 72 66 61 63 65 20 74  stem interface t
1d450 68 61 74 20 73 68 6f 75 6c 64 0a 2a 2a 20 20 20  hat should.**   
1d460 20 20 62 65 20 75 73 65 64 20 74 6f 20 61 63 63    be used to acc
1d470 65 73 73 20 74 68 65 20 64 61 74 61 62 61 73 65  ess the database
1d480 20 66 69 6c 65 20 6f 6e 20 64 69 73 6b 2e 20 5e   file on disk. ^
1d490 49 66 20 74 68 69 73 20 6f 70 74 69 6f 6e 20 69  If this option i
1d4a0 73 20 73 65 74 20 74 6f 0a 2a 2a 20 20 20 20 20  s set to.**     
1d4b0 61 6e 20 65 6d 70 74 79 20 73 74 72 69 6e 67 20  an empty string 
1d4c0 74 68 65 20 64 65 66 61 75 6c 74 20 56 46 53 20  the default VFS 
1d4d0 6f 62 6a 65 63 74 20 69 73 20 75 73 65 64 2e 20  object is used. 
1d4e0 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20 75  ^Specifying an u
1d4f0 6e 6b 6e 6f 77 6e 0a 2a 2a 20 20 20 20 20 56 46  nknown.**     VF
1d500 53 20 69 73 20 61 6e 20 65 72 72 6f 72 2e 20 5e  S is an error. ^
1d510 49 66 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  If sqlite3_open_
1d520 76 32 28 29 20 69 73 20 75 73 65 64 20 61 6e 64  v2() is used and
1d530 20 74 68 65 20 76 66 73 20 6f 70 74 69 6f 6e 20   the vfs option 
1d540 69 73 0a 2a 2a 20 20 20 20 20 70 72 65 73 65 6e  is.**     presen
1d550 74 2c 20 74 68 65 6e 20 74 68 65 20 56 46 53 20  t, then the VFS 
1d560 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68 65  specified by the
1d570 20 6f 70 74 69 6f 6e 20 74 61 6b 65 73 20 70 72   option takes pr
1d580 65 63 65 64 65 6e 63 65 20 6f 76 65 72 0a 2a 2a  ecedence over.**
1d590 20 20 20 20 20 74 68 65 20 76 61 6c 75 65 20 70       the value p
1d5a0 61 73 73 65 64 20 61 73 20 74 68 65 20 66 6f 75  assed as the fou
1d5b0 72 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  rth parameter to
1d5c0 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1d5d0 28 29 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  ()..**.**   <li>
1d5e0 20 3c 62 3e 6d 6f 64 65 3c 2f 62 3e 3a 20 5e 28   <b>mode</b>: ^(
1d5f0 54 68 65 20 6d 6f 64 65 20 70 61 72 61 6d 65 74  The mode paramet
1d600 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74 6f  er may be set to
1d610 20 65 69 74 68 65 72 20 22 72 6f 22 2c 20 22 72   either "ro", "r
1d620 77 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 72 77  w" or.**     "rw
1d630 63 22 2e 20 41 74 74 65 6d 70 74 69 6e 67 20 74  c". Attempting t
1d640 6f 20 73 65 74 20 69 74 20 74 6f 20 61 6e 79 20  o set it to any 
1d650 6f 74 68 65 72 20 76 61 6c 75 65 20 69 73 20 61  other value is a
1d660 6e 20 65 72 72 6f 72 29 5e 2e 20 0a 2a 2a 20 20  n error)^. .**  
1d670 20 20 20 5e 49 66 20 22 72 6f 22 20 69 73 20 73     ^If "ro" is s
1d680 70 65 63 69 66 69 65 64 2c 20 74 68 65 6e 20 74  pecified, then t
1d690 68 65 20 64 61 74 61 62 61 73 65 20 69 73 20 6f  he database is o
1d6a0 70 65 6e 65 64 20 66 6f 72 20 72 65 61 64 2d 6f  pened for read-o
1d6b0 6e 6c 79 20 0a 2a 2a 20 20 20 20 20 61 63 63 65  nly .**     acce
1d6c0 73 73 2c 20 6a 75 73 74 20 61 73 20 69 66 20 74  ss, just as if t
1d6d0 68 65 20 5b 53 51 4c 49 54 45 5f 4f 50 45 4e 5f  he [SQLITE_OPEN_
1d6e0 52 45 41 44 4f 4e 4c 59 5d 20 66 6c 61 67 20 68  READONLY] flag h
1d6f0 61 64 20 62 65 65 6e 20 73 65 74 20 69 6e 20 74  ad been set in t
1d700 68 65 20 0a 2a 2a 20 20 20 20 20 74 68 69 72 64  he .**     third
1d710 20 61 72 67 75 6d 65 6e 74 20 74 6f 20 73 71 6c   argument to sql
1d720 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
1d730 29 2e 20 5e 49 66 20 74 68 65 20 6d 6f 64 65 20  ). ^If the mode 
1d740 6f 70 74 69 6f 6e 20 69 73 20 73 65 74 20 74 6f  option is set to
1d750 20 0a 2a 2a 20 20 20 20 20 22 72 77 22 2c 20 74   .**     "rw", t
1d760 68 65 6e 20 74 68 65 20 64 61 74 61 62 61 73 65  hen the database
1d770 20 69 73 20 6f 70 65 6e 65 64 20 66 6f 72 20 72   is opened for r
1d780 65 61 64 2d 77 72 69 74 65 20 28 62 75 74 20 6e  ead-write (but n
1d790 6f 74 20 63 72 65 61 74 65 29 20 0a 2a 2a 20 20  ot create) .**  
1d7a0 20 20 20 61 63 63 65 73 73 2c 20 61 73 20 69 66     access, as if
1d7b0 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 52 45 41   SQLITE_OPEN_REA
1d7c0 44 57 52 49 54 45 20 28 62 75 74 20 6e 6f 74 20  DWRITE (but not 
1d7d0 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 43 52 45 41  SQLITE_OPEN_CREA
1d7e0 54 45 29 20 68 61 64 20 0a 2a 2a 20 20 20 20 20  TE) had .**     
1d7f0 62 65 65 6e 20 73 65 74 2e 20 5e 56 61 6c 75 65  been set. ^Value
1d800 20 22 72 77 63 22 20 69 73 20 65 71 75 69 76 61   "rwc" is equiva
1d810 6c 65 6e 74 20 74 6f 20 73 65 74 74 69 6e 67 20  lent to setting 
1d820 62 6f 74 68 20 0a 2a 2a 20 20 20 20 20 53 51 4c  both .**     SQL
1d830 49 54 45 5f 4f 50 45 4e 5f 52 45 41 44 57 52 49  ITE_OPEN_READWRI
1d840 54 45 20 61 6e 64 20 53 51 4c 49 54 45 5f 4f 50  TE and SQLITE_OP
1d850 45 4e 5f 43 52 45 41 54 45 2e 20 5e 49 66 20 73  EN_CREATE. ^If s
1d860 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1d870 20 69 73 20 0a 2a 2a 20 20 20 20 20 75 73 65 64   is .**     used
1d880 2c 20 69 74 20 69 73 20 61 6e 20 65 72 72 6f 72  , it is an error
1d890 20 74 6f 20 73 70 65 63 69 66 79 20 61 20 76 61   to specify a va
1d8a0 6c 75 65 20 66 6f 72 20 74 68 65 20 6d 6f 64 65  lue for the mode
1d8b0 20 70 61 72 61 6d 65 74 65 72 20 74 68 61 74 20   parameter that 
1d8c0 69 73 20 0a 2a 2a 20 20 20 20 20 6c 65 73 73 20  is .**     less 
1d8d0 72 65 73 74 72 69 63 74 69 76 65 20 74 68 61 6e  restrictive than
1d8e0 20 74 68 61 74 20 73 70 65 63 69 66 69 65 64 20   that specified 
1d8f0 62 79 20 74 68 65 20 66 6c 61 67 73 20 70 61 73  by the flags pas
1d900 73 65 64 20 61 73 20 74 68 65 20 74 68 69 72 64  sed as the third
1d910 20 0a 2a 2a 20 20 20 20 20 70 61 72 61 6d 65 74   .**     paramet
1d920 65 72 2e 0a 2a 2a 0a 2a 2a 20 20 20 3c 6c 69 3e  er..**.**   <li>
1d930 20 3c 62 3e 63 61 63 68 65 3c 2f 62 3e 3a 20 5e   <b>cache</b>: ^
1d940 54 68 65 20 63 61 63 68 65 20 70 61 72 61 6d 65  The cache parame
1d950 74 65 72 20 6d 61 79 20 62 65 20 73 65 74 20 74  ter may be set t
1d960 6f 20 65 69 74 68 65 72 20 22 73 68 61 72 65 64  o either "shared
1d970 22 20 6f 72 0a 2a 2a 20 20 20 20 20 22 70 72 69  " or.**     "pri
1d980 76 61 74 65 22 2e 20 5e 53 65 74 74 69 6e 67 20  vate". ^Setting 
1d990 69 74 20 74 6f 20 22 73 68 61 72 65 64 22 20 69  it to "shared" i
1d9a0 73 20 65 71 75 69 76 61 6c 65 6e 74 20 74 6f 20  s equivalent to 
1d9b0 73 65 74 74 69 6e 67 20 74 68 65 0a 2a 2a 20 20  setting the.**  
1d9c0 20 20 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f 53     SQLITE_OPEN_S
1d9d0 48 41 52 45 44 43 41 43 48 45 20 62 69 74 20 69  HAREDCACHE bit i
1d9e0 6e 20 74 68 65 20 66 6c 61 67 73 20 61 72 67 75  n the flags argu
1d9f0 6d 65 6e 74 20 70 61 73 73 65 64 20 74 6f 0a 2a  ment passed to.*
1da00 2a 20 20 20 20 20 73 71 6c 69 74 65 33 5f 6f 70  *     sqlite3_op
1da10 65 6e 5f 76 32 28 29 2e 20 5e 53 65 74 74 69 6e  en_v2(). ^Settin
1da20 67 20 74 68 65 20 63 61 63 68 65 20 70 61 72 61  g the cache para
1da30 6d 65 74 65 72 20 74 6f 20 22 70 72 69 76 61 74  meter to "privat
1da40 65 22 20 69 73 20 0a 2a 2a 20 20 20 20 20 65 71  e" is .**     eq
1da50 75 69 76 61 6c 65 6e 74 20 74 6f 20 73 65 74 74  uivalent to sett
1da60 69 6e 67 20 74 68 65 20 53 51 4c 49 54 45 5f 4f  ing the SQLITE_O
1da70 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1da80 20 62 69 74 2e 0a 2a 2a 20 20 20 20 20 5e 49 66   bit..**     ^If
1da90 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32   sqlite3_open_v2
1daa0 28 29 20 69 73 20 75 73 65 64 20 61 6e 64 20 74  () is used and t
1dab0 68 65 20 22 63 61 63 68 65 22 20 70 61 72 61 6d  he "cache" param
1dac0 65 74 65 72 20 69 73 20 70 72 65 73 65 6e 74 20  eter is present 
1dad0 69 6e 0a 2a 2a 20 20 20 20 20 61 20 55 52 49 20  in.**     a URI 
1dae0 66 69 6c 65 6e 61 6d 65 2c 20 69 74 73 20 76 61  filename, its va
1daf0 6c 75 65 20 6f 76 65 72 72 69 64 65 73 20 61 6e  lue overrides an
1db00 79 20 62 65 68 61 76 69 6f 75 72 20 72 65 71 75  y behaviour requ
1db10 65 73 74 65 64 20 62 79 20 73 65 74 74 69 6e 67  ested by setting
1db20 0a 2a 2a 20 20 20 20 20 53 51 4c 49 54 45 5f 4f  .**     SQLITE_O
1db30 50 45 4e 5f 50 52 49 56 41 54 45 43 41 43 48 45  PEN_PRIVATECACHE
1db40 20 6f 72 20 53 51 4c 49 54 45 5f 4f 50 45 4e 5f   or SQLITE_OPEN_
1db50 53 48 41 52 45 44 43 41 43 48 45 20 66 6c 61 67  SHAREDCACHE flag
1db60 2e 0a 2a 2a 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a  ..** </ul>.**.**
1db70 20 5e 53 70 65 63 69 66 79 69 6e 67 20 61 6e 20   ^Specifying an 
1db80 75 6e 6b 6e 6f 77 6e 20 70 61 72 61 6d 65 74 65  unknown paramete
1db90 72 20 69 6e 20 74 68 65 20 71 75 65 72 79 20 63  r in the query c
1dba0 6f 6d 70 6f 6e 65 6e 74 20 6f 66 20 61 20 55 52  omponent of a UR
1dbb0 49 20 69 73 20 6e 6f 74 20 61 6e 0a 2a 2a 20 65  I is not an.** e
1dbc0 72 72 6f 72 2e 0a 2a 2a 0a 2a 2a 20 55 52 49 20  rror..**.** URI 
1dbd0 66 69 6c 65 6e 61 6d 65 20 65 78 61 6d 70 6c 65  filename example
1dbe0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 74 61 62 6c 65 20  s:.**.** <table 
1dbf0 62 6f 72 64 65 72 3d 22 31 22 20 61 6c 69 67 6e  border="1" align
1dc00 3d 63 65 6e 74 65 72 20 63 65 6c 6c 70 61 64 64  =center cellpadd
1dc10 69 6e 67 3d 35 3e 0a 2a 2a 20 3c 74 72 3e 3c 74  ing=5>.** <tr><t
1dc20 68 3e 20 55 52 49 20 66 69 6c 65 6e 61 6d 65 73  h> URI filenames
1dc30 20 3c 74 68 3e 20 52 65 73 75 6c 74 73 0a 2a 2a   <th> Results.**
1dc40 20 3c 74 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64   <tr><td> file:d
1dc50 61 74 61 2e 64 62 20 3c 74 64 3e 20 0a 2a 2a 20  ata.db <td> .** 
1dc60 20 20 20 20 20 20 20 20 20 4f 70 65 6e 20 74 68           Open th
1dc70 65 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22  e file "data.db"
1dc80 20 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20   in the current 
1dc90 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 20 3c 74  directory..** <t
1dca0 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 2f 68 6f 6d  r><td> file:/hom
1dcb0 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 3c 62  e/fred/data.db<b
1dcc0 72 3e 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 66  r>.**          f
1dcd0 69 6c 65 3a 2f 2f 2f 68 6f 6d 65 2f 66 72 65 64  ile:///home/fred
1dce0 2f 64 61 74 61 2e 64 62 20 3c 62 72 3e 20 0a 2a  /data.db <br> .*
1dcf0 2a 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a  *          file:
1dd00 2f 2f 6c 6f 63 61 6c 68 6f 73 74 2f 68 6f 6d 65  //localhost/home
1dd10 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20 3c 62  /fred/data.db <b
1dd20 72 3e 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20  r> <td> .**     
1dd30 20 20 20 20 20 4f 70 65 6e 20 74 68 65 20 64 61       Open the da
1dd40 74 61 62 61 73 65 20 66 69 6c 65 20 22 2f 68 6f  tabase file "/ho
1dd50 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 22  me/fred/data.db"
1dd60 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1dd70 6c 65 3a 2f 2f 64 61 72 6b 73 74 61 72 2f 68 6f  le://darkstar/ho
1dd80 6d 65 2f 66 72 65 64 2f 64 61 74 61 2e 64 62 20  me/fred/data.db 
1dd90 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20 20  <td> .**        
1dda0 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 64 61 72    An error. "dar
1ddb0 6b 73 74 61 72 22 20 69 73 20 6e 6f 74 20 61 20  kstar" is not a 
1ddc0 72 65 63 6f 67 6e 69 7a 65 64 20 61 75 74 68 6f  recognized autho
1ddd0 72 69 74 79 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64  rity..** <tr><td
1dde0 20 73 74 79 6c 65 3d 22 77 68 69 74 65 2d 73 70   style="white-sp
1ddf0 61 63 65 3a 6e 6f 77 72 61 70 22 3e 20 0a 2a 2a  ace:nowrap"> .**
1de00 20 20 20 20 20 20 20 20 20 20 66 69 6c 65 3a 2f            file:/
1de10 2f 2f 43 3a 2f 44 6f 63 75 6d 65 6e 74 73 25 32  //C:/Documents%2
1de20 30 61 6e 64 25 32 30 53 65 74 74 69 6e 67 73 2f  0and%20Settings/
1de30 66 72 65 64 2f 44 65 73 6b 74 6f 70 2f 64 61 74  fred/Desktop/dat
1de40 61 2e 64 62 0a 2a 2a 20 20 20 20 20 3c 74 64 3e  a.db.**     <td>
1de50 20 57 69 6e 64 6f 77 73 20 6f 6e 6c 79 3a 20 4f   Windows only: O
1de60 70 65 6e 20 74 68 65 20 66 69 6c 65 20 22 64 61  pen the file "da
1de70 74 61 2e 64 62 22 20 6f 6e 20 66 72 65 64 27 73  ta.db" on fred's
1de80 20 64 65 73 6b 74 6f 70 20 6f 6e 20 64 72 69 76   desktop on driv
1de90 65 0a 2a 2a 20 20 20 20 20 20 20 20 20 20 43 3a  e.**          C:
1dea0 2e 20 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20  . Note that the 
1deb0 25 32 30 20 65 73 63 61 70 69 6e 67 20 69 6e 20  %20 escaping in 
1dec0 74 68 69 73 20 65 78 61 6d 70 6c 65 20 69 73 20  this example is 
1ded0 6e 6f 74 20 73 74 72 69 63 74 6c 79 20 0a 2a 2a  not strictly .**
1dee0 20 20 20 20 20 20 20 20 20 20 6e 65 63 65 73 73            necess
1def0 61 72 79 20 2d 20 73 70 61 63 65 20 63 68 61 72  ary - space char
1df00 61 63 74 65 72 73 20 63 61 6e 20 62 65 20 75 73  acters can be us
1df10 65 64 20 6c 69 74 65 72 61 6c 6c 79 0a 2a 2a 20  ed literally.** 
1df20 20 20 20 20 20 20 20 20 20 69 6e 20 55 52 49 20           in URI 
1df30 66 69 6c 65 6e 61 6d 65 73 2e 0a 2a 2a 20 3c 74  filenames..** <t
1df40 72 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61  r><td> file:data
1df50 2e 64 62 3f 6d 6f 64 65 3d 72 6f 26 63 61 63 68  .db?mode=ro&cach
1df60 65 3d 70 72 69 76 61 74 65 20 3c 74 64 3e 20 0a  e=private <td> .
1df70 2a 2a 20 20 20 20 20 20 20 20 20 20 4f 70 65 6e  **          Open
1df80 20 66 69 6c 65 20 22 64 61 74 61 2e 64 62 22 20   file "data.db" 
1df90 69 6e 20 74 68 65 20 63 75 72 72 65 6e 74 20 64  in the current d
1dfa0 69 72 65 63 74 6f 72 79 20 66 6f 72 20 72 65 61  irectory for rea
1dfb0 64 2d 6f 6e 6c 79 20 61 63 63 65 73 73 2e 0a 2a  d-only access..*
1dfc0 2a 20 20 20 20 20 20 20 20 20 20 52 65 67 61 72  *          Regar
1dfd0 64 6c 65 73 73 20 6f 66 20 77 68 65 74 68 65 72  dless of whether
1dfe0 20 6f 72 20 6e 6f 74 20 73 68 61 72 65 64 2d 63   or not shared-c
1dff0 61 63 68 65 20 6d 6f 64 65 20 69 73 20 65 6e 61  ache mode is ena
1e000 62 6c 65 64 20 62 79 0a 2a 2a 20 20 20 20 20 20  bled by.**      
1e010 20 20 20 20 64 65 66 61 75 6c 74 2c 20 75 73 65      default, use
1e020 20 61 20 70 72 69 76 61 74 65 20 63 61 63 68 65   a private cache
1e030 2e 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 66 69  ..** <tr><td> fi
1e040 6c 65 3a 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61  le:/home/fred/da
1e050 74 61 2e 64 62 3f 76 66 73 3d 75 6e 69 78 2d 6e  ta.db?vfs=unix-n
1e060 6f 6c 6f 63 6b 20 3c 74 64 3e 0a 2a 2a 20 20 20  olock <td>.**   
1e070 20 20 20 20 20 20 20 4f 70 65 6e 20 66 69 6c 65         Open file
1e080 20 22 2f 68 6f 6d 65 2f 66 72 65 64 2f 64 61 74   "/home/fred/dat
1e090 61 2e 64 62 22 2e 20 55 73 65 20 74 68 65 20 73  a.db". Use the s
1e0a0 70 65 63 69 61 6c 20 56 46 53 20 22 75 6e 69 78  pecial VFS "unix
1e0b0 2d 6e 6f 6c 6f 63 6b 22 2e 0a 2a 2a 20 3c 74 72  -nolock"..** <tr
1e0c0 3e 3c 74 64 3e 20 66 69 6c 65 3a 64 61 74 61 2e  ><td> file:data.
1e0d0 64 62 3f 6d 6f 64 65 3d 72 65 61 64 6f 6e 6c 79  db?mode=readonly
1e0e0 20 3c 74 64 3e 20 0a 2a 2a 20 20 20 20 20 20 20   <td> .**       
1e0f0 20 20 20 41 6e 20 65 72 72 6f 72 2e 20 22 72 65     An error. "re
1e100 61 64 6f 6e 6c 79 22 20 69 73 20 6e 6f 74 20 61  adonly" is not a
1e110 20 76 61 6c 69 64 20 6f 70 74 69 6f 6e 20 66 6f   valid option fo
1e120 72 20 74 68 65 20 22 6d 6f 64 65 22 20 70 61 72  r the "mode" par
1e130 61 6d 65 74 65 72 2e 0a 2a 2a 20 3c 2f 74 61 62  ameter..** </tab
1e140 6c 65 3e 0a 2a 2a 0a 2a 2a 20 5e 55 52 49 20 68  le>.**.** ^URI h
1e150 65 78 61 64 65 63 69 6d 61 6c 20 65 73 63 61 70  exadecimal escap
1e160 65 20 73 65 71 75 65 6e 63 65 73 20 28 25 48 48  e sequences (%HH
1e170 29 20 61 72 65 20 73 75 70 70 6f 72 74 65 64 20  ) are supported 
1e180 77 69 74 68 69 6e 20 74 68 65 20 70 61 74 68 20  within the path 
1e190 61 6e 64 0a 2a 2a 20 71 75 65 72 79 20 63 6f 6d  and.** query com
1e1a0 70 6f 6e 65 6e 74 73 20 6f 66 20 61 20 55 52 49  ponents of a URI
1e1b0 2e 20 41 20 68 65 78 61 64 65 63 69 6d 61 6c 20  . A hexadecimal 
1e1c0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 20  escape sequence 
1e1d0 63 6f 6e 73 69 73 74 73 20 6f 66 20 61 0a 2a 2a  consists of a.**
1e1e0 20 70 65 72 63 65 6e 74 20 73 69 67 6e 20 2d 20   percent sign - 
1e1f0 22 25 22 20 2d 20 66 6f 6c 6c 6f 77 65 64 20 62  "%" - followed b
1e200 79 20 65 78 61 63 74 6c 79 20 74 77 6f 20 68 65  y exactly two he
1e210 78 61 64 65 63 69 6d 61 6c 20 64 69 67 69 74 73  xadecimal digits
1e220 20 0a 2a 2a 20 73 70 65 63 69 66 79 69 6e 67 20   .** specifying 
1e230 61 6e 20 6f 63 74 65 74 20 76 61 6c 75 65 2e 20  an octet value. 
1e240 5e 42 65 66 6f 72 65 20 74 68 65 20 70 61 74 68  ^Before the path
1e250 20 6f 72 20 71 75 65 72 79 20 63 6f 6d 70 6f 6e   or query compon
1e260 65 6e 74 73 20 6f 66 20 61 0a 2a 2a 20 55 52 49  ents of a.** URI
1e270 20 66 69 6c 65 6e 61 6d 65 20 61 72 65 20 69 6e   filename are in
1e280 74 65 72 70 72 65 74 65 64 2c 20 74 68 65 79 20  terpreted, they 
1e290 61 72 65 20 65 6e 63 6f 64 65 64 20 75 73 69 6e  are encoded usin
1e2a0 67 20 55 54 46 2d 38 20 61 6e 64 20 61 6c 6c 20  g UTF-8 and all 
1e2b0 0a 2a 2a 20 68 65 78 61 64 65 63 69 6d 61 6c 20  .** hexadecimal 
1e2c0 65 73 63 61 70 65 20 73 65 71 75 65 6e 63 65 73  escape sequences
1e2d0 20 72 65 70 6c 61 63 65 64 20 62 79 20 61 20 73   replaced by a s
1e2e0 69 6e 67 6c 65 20 62 79 74 65 20 63 6f 6e 74 61  ingle byte conta
1e2f0 69 6e 69 6e 67 20 74 68 65 0a 2a 2a 20 63 6f 72  ining the.** cor
1e300 72 65 73 70 6f 6e 64 69 6e 67 20 6f 63 74 65 74  responding octet
1e310 2e 20 49 66 20 74 68 69 73 20 70 72 6f 63 65 73  . If this proces
1e320 73 20 67 65 6e 65 72 61 74 65 73 20 61 6e 20 69  s generates an i
1e330 6e 76 61 6c 69 64 20 55 54 46 2d 38 20 65 6e 63  nvalid UTF-8 enc
1e340 6f 64 69 6e 67 2c 0a 2a 2a 20 74 68 65 20 72 65  oding,.** the re
1e350 73 75 6c 74 73 20 61 72 65 20 75 6e 64 65 66 69  sults are undefi
1e360 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 3c 62 3e 4e 6f  ned..**.** <b>No
1e370 74 65 20 74 6f 20 57 69 6e 64 6f 77 73 20 75 73  te to Windows us
1e380 65 72 73 3a 3c 2f 62 3e 20 20 54 68 65 20 65 6e  ers:</b>  The en
1e390 63 6f 64 69 6e 67 20 75 73 65 64 20 66 6f 72 20  coding used for 
1e3a0 74 68 65 20 66 69 6c 65 6e 61 6d 65 20 61 72 67  the filename arg
1e3b0 75 6d 65 6e 74 0a 2a 2a 20 6f 66 20 73 71 6c 69  ument.** of sqli
1e3c0 74 65 33 5f 6f 70 65 6e 28 29 20 61 6e 64 20 73  te3_open() and s
1e3d0 71 6c 69 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29  qlite3_open_v2()
1e3e0 20 6d 75 73 74 20 62 65 20 55 54 46 2d 38 2c 20   must be UTF-8, 
1e3f0 6e 6f 74 20 77 68 61 74 65 76 65 72 0a 2a 2a 20  not whatever.** 
1e400 63 6f 64 65 70 61 67 65 20 69 73 20 63 75 72 72  codepage is curr
1e410 65 6e 74 6c 79 20 64 65 66 69 6e 65 64 2e 20 20  ently defined.  
1e420 46 69 6c 65 6e 61 6d 65 73 20 63 6f 6e 74 61 69  Filenames contai
1e430 6e 69 6e 67 20 69 6e 74 65 72 6e 61 74 69 6f 6e  ning internation
1e440 61 6c 0a 2a 2a 20 63 68 61 72 61 63 74 65 72 73  al.** characters
1e450 20 6d 75 73 74 20 62 65 20 63 6f 6e 76 65 72 74   must be convert
1e460 65 64 20 74 6f 20 55 54 46 2d 38 20 70 72 69 6f  ed to UTF-8 prio
1e470 72 20 74 6f 20 70 61 73 73 69 6e 67 20 74 68 65  r to passing the
1e480 6d 20 69 6e 74 6f 0a 2a 2a 20 73 71 6c 69 74 65  m into.** sqlite
1e490 33 5f 6f 70 65 6e 28 29 20 6f 72 20 73 71 6c 69  3_open() or sqli
1e4a0 74 65 33 5f 6f 70 65 6e 5f 76 32 28 29 2e 0a 2a  te3_open_v2()..*
1e4b0 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70  /.int sqlite3_op
1e4c0 65 6e 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  en(.  const char
1e4d0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e4e0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1e4f0 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1e500 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 20 20  sqlite3 **ppDb  
1e510 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1e520 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1e530 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74   */.);.int sqlit
1e540 65 33 5f 6f 70 65 6e 31 36 28 0a 20 20 63 6f 6e  e3_open16(.  con
1e550 73 74 20 76 6f 69 64 20 2a 66 69 6c 65 6e 61 6d  st void *filenam
1e560 65 2c 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65  e,   /* Database
1e570 20 66 69 6c 65 6e 61 6d 65 20 28 55 54 46 2d 31   filename (UTF-1
1e580 36 29 20 2a 2f 0a 20 20 73 71 6c 69 74 65 33 20  6) */.  sqlite3 
1e590 2a 2a 70 70 44 62 20 20 20 20 20 20 20 20 20 20  **ppDb          
1e5a0 2f 2a 20 4f 55 54 3a 20 53 51 4c 69 74 65 20 64  /* OUT: SQLite d
1e5b0 62 20 68 61 6e 64 6c 65 20 2a 2f 0a 29 3b 0a 69  b handle */.);.i
1e5c0 6e 74 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 5f  nt sqlite3_open_
1e5d0 76 32 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  v2(.  const char
1e5e0 20 2a 66 69 6c 65 6e 61 6d 65 2c 20 20 20 2f 2a   *filename,   /*
1e5f0 20 44 61 74 61 62 61 73 65 20 66 69 6c 65 6e 61   Database filena
1e600 6d 65 20 28 55 54 46 2d 38 29 20 2a 2f 0a 20 20  me (UTF-8) */.  
1e610 73 71 6c 69 74 65 33 20 2a 2a 70 70 44 62 2c 20  sqlite3 **ppDb, 
1e620 20 20 20 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20          /* OUT: 
1e630 53 51 4c 69 74 65 20 64 62 20 68 61 6e 64 6c 65  SQLite db handle
1e640 20 2a 2f 0a 20 20 69 6e 74 20 66 6c 61 67 73 2c   */.  int flags,
1e650 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
1e660 20 46 6c 61 67 73 20 2a 2f 0a 20 20 63 6f 6e 73   Flags */.  cons
1e670 74 20 63 68 61 72 20 2a 7a 56 66 73 20 20 20 20  t char *zVfs    
1e680 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66 20 56      /* Name of V
1e690 46 53 20 6d 6f 64 75 6c 65 20 74 6f 20 75 73 65  FS module to use
1e6a0 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41   */.);../*.** CA
1e6b0 50 49 33 52 45 46 3a 20 45 72 72 6f 72 20 43 6f  PI3REF: Error Co
1e6c0 64 65 73 20 41 6e 64 20 4d 65 73 73 61 67 65 73  des And Messages
1e6d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
1e6e0 74 65 33 5f 65 72 72 63 6f 64 65 28 29 20 69 6e  te3_errcode() in
1e6f0 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
1e700 74 68 65 20 6e 75 6d 65 72 69 63 20 5b 72 65 73  the numeric [res
1e710 75 6c 74 20 63 6f 64 65 5d 20 6f 72 0a 2a 2a 20  ult code] or.** 
1e720 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1e730 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65 20 6d   code] for the m
1e740 6f 73 74 20 72 65 63 65 6e 74 20 66 61 69 6c 65  ost recent faile
1e750 64 20 73 71 6c 69 74 65 33 5f 2a 20 41 50 49 20  d sqlite3_* API 
1e760 63 61 6c 6c 0a 2a 2a 20 61 73 73 6f 63 69 61 74  call.** associat
1e770 65 64 20 77 69 74 68 20 61 20 5b 64 61 74 61 62  ed with a [datab
1e780 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 2e  ase connection].
1e790 20 49 66 20 61 20 70 72 69 6f 72 20 41 50 49 20   If a prior API 
1e7a0 63 61 6c 6c 20 66 61 69 6c 65 64 0a 2a 2a 20 62  call failed.** b
1e7b0 75 74 20 74 68 65 20 6d 6f 73 74 20 72 65 63 65  ut the most rece
1e7c0 6e 74 20 41 50 49 20 63 61 6c 6c 20 73 75 63 63  nt API call succ
1e7d0 65 65 64 65 64 2c 20 74 68 65 20 72 65 74 75 72  eeded, the retur
1e7e0 6e 20 76 61 6c 75 65 20 66 72 6f 6d 0a 2a 2a 20  n value from.** 
1e7f0 73 71 6c 69 74 65 33 5f 65 72 72 63 6f 64 65 28  sqlite3_errcode(
1e800 29 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 20  ) is undefined. 
1e810 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 65 78   ^The sqlite3_ex
1e820 74 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 29  tended_errcode()
1e830 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 20 69 73  .** interface is
1e840 20 74 68 65 20 73 61 6d 65 20 65 78 63 65 70 74   the same except
1e850 20 74 68 61 74 20 69 74 20 61 6c 77 61 79 73 20   that it always 
1e860 72 65 74 75 72 6e 73 20 74 68 65 20 0a 2a 2a 20  returns the .** 
1e870 5b 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74  [extended result
1e880 20 63 6f 64 65 5d 20 65 76 65 6e 20 77 68 65 6e   code] even when
1e890 20 65 78 74 65 6e 64 65 64 20 72 65 73 75 6c 74   extended result
1e8a0 20 63 6f 64 65 73 20 61 72 65 0a 2a 2a 20 64 69   codes are.** di
1e8b0 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54  sabled..**.** ^T
1e8c0 68 65 20 73 71 6c 69 74 65 33 5f 65 72 72 6d 73  he sqlite3_errms
1e8d0 67 28 29 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  g() and sqlite3_
1e8e0 65 72 72 6d 73 67 31 36 28 29 20 72 65 74 75 72  errmsg16() retur
1e8f0 6e 20 45 6e 67 6c 69 73 68 2d 6c 61 6e 67 75 61  n English-langua
1e900 67 65 0a 2a 2a 20 74 65 78 74 20 74 68 61 74 20  ge.** text that 
1e910 64 65 73 63 72 69 62 65 73 20 74 68 65 20 65 72  describes the er
1e920 72 6f 72 2c 20 61 73 20 65 69 74 68 65 72 20 55  ror, as either U
1e930 54 46 2d 38 20 6f 72 20 55 54 46 2d 31 36 20 72  TF-8 or UTF-16 r
1e940 65 73 70 65 63 74 69 76 65 6c 79 2e 0a 2a 2a 20  espectively..** 
1e950 5e 28 4d 65 6d 6f 72 79 20 74 6f 20 68 6f 6c 64  ^(Memory to hold
1e960 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73 73 61   the error messa
1e970 67 65 20 73 74 72 69 6e 67 20 69 73 20 6d 61 6e  ge string is man
1e980 61 67 65 64 20 69 6e 74 65 72 6e 61 6c 6c 79 2e  aged internally.
1e990 0a 2a 2a 20 54 68 65 20 61 70 70 6c 69 63 61 74  .** The applicat
1e9a0 69 6f 6e 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65  ion does not nee
1e9b0 64 20 74 6f 20 77 6f 72 72 79 20 61 62 6f 75 74  d to worry about
1e9c0 20 66 72 65 65 69 6e 67 20 74 68 65 20 72 65 73   freeing the res
1e9d0 75 6c 74 2e 0a 2a 2a 20 48 6f 77 65 76 65 72 2c  ult..** However,
1e9e0 20 74 68 65 20 65 72 72 6f 72 20 73 74 72 69 6e   the error strin
1e9f0 67 20 6d 69 67 68 74 20 62 65 20 6f 76 65 72 77  g might be overw
1ea00 72 69 74 74 65 6e 20 6f 72 20 64 65 61 6c 6c 6f  ritten or deallo
1ea10 63 61 74 65 64 20 62 79 0a 2a 2a 20 73 75 62 73  cated by.** subs
1ea20 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 20  equent calls to 
1ea30 6f 74 68 65 72 20 53 51 4c 69 74 65 20 69 6e 74  other SQLite int
1ea40 65 72 66 61 63 65 20 66 75 6e 63 74 69 6f 6e 73  erface functions
1ea50 2e 29 5e 0a 2a 2a 0a 2a 2a 20 57 68 65 6e 20 74  .)^.**.** When t
1ea60 68 65 20 73 65 72 69 61 6c 69 7a 65 64 20 5b 74  he serialized [t
1ea70 68 72 65 61 64 69 6e 67 20 6d 6f 64 65 5d 20 69  hreading mode] i
1ea80 73 20 69 6e 20 75 73 65 2c 20 69 74 20 6d 69 67  s in use, it mig
1ea90 68 74 20 62 65 20 74 68 65 0a 2a 2a 20 63 61 73  ht be the.** cas
1eaa0 65 20 74 68 61 74 20 61 20 73 65 63 6f 6e 64 20  e that a second 
1eab0 65 72 72 6f 72 20 6f 63 63 75 72 73 20 6f 6e 20  error occurs on 
1eac0 61 20 73 65 70 61 72 61 74 65 20 74 68 72 65 61  a separate threa
1ead0 64 20 69 6e 20 62 65 74 77 65 65 6e 0a 2a 2a 20  d in between.** 
1eae0 74 68 65 20 74 69 6d 65 20 6f 66 20 74 68 65 20  the time of the 
1eaf0 66 69 72 73 74 20 65 72 72 6f 72 20 61 6e 64 20  first error and 
1eb00 74 68 65 20 63 61 6c 6c 20 74 6f 20 74 68 65 73  the call to thes
1eb10 65 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  e interfaces..**
1eb20 20 57 68 65 6e 20 74 68 61 74 20 68 61 70 70 65   When that happe
1eb30 6e 73 2c 20 74 68 65 20 73 65 63 6f 6e 64 20 65  ns, the second e
1eb40 72 72 6f 72 20 77 69 6c 6c 20 62 65 20 72 65 70  rror will be rep
1eb50 6f 72 74 65 64 20 73 69 6e 63 65 20 74 68 65 73  orted since thes
1eb60 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65 73 20  e.** interfaces 
1eb70 61 6c 77 61 79 73 20 72 65 70 6f 72 74 20 74 68  always report th
1eb80 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 72 65  e most recent re
1eb90 73 75 6c 74 2e 20 20 54 6f 20 61 76 6f 69 64 0a  sult.  To avoid.
1eba0 2a 2a 20 74 68 69 73 2c 20 65 61 63 68 20 74 68  ** this, each th
1ebb0 72 65 61 64 20 63 61 6e 20 6f 62 74 61 69 6e 20  read can obtain 
1ebc0 65 78 63 6c 75 73 69 76 65 20 75 73 65 20 6f 66  exclusive use of
1ebd0 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   the [database c
1ebe0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44 0a 2a 2a 20  onnection] D.** 
1ebf0 62 79 20 69 6e 76 6f 6b 69 6e 67 20 5b 73 71 6c  by invoking [sql
1ec00 69 74 65 33 5f 6d 75 74 65 78 5f 65 6e 74 65 72  ite3_mutex_enter
1ec10 5d 28 5b 73 71 6c 69 74 65 33 5f 64 62 5f 6d 75  ]([sqlite3_db_mu
1ec20 74 65 78 5d 28 44 29 29 20 62 65 66 6f 72 65 20  tex](D)) before 
1ec30 62 65 67 69 6e 6e 69 6e 67 0a 2a 2a 20 74 6f 20  beginning.** to 
1ec40 75 73 65 20 44 20 61 6e 64 20 69 6e 76 6f 6b 69  use D and invoki
1ec50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6d 75 74 65  ng [sqlite3_mute
1ec60 78 5f 6c 65 61 76 65 5d 28 5b 73 71 6c 69 74 65  x_leave]([sqlite
1ec70 33 5f 64 62 5f 6d 75 74 65 78 5d 28 44 29 29 20  3_db_mutex](D)) 
1ec80 61 66 74 65 72 0a 2a 2a 20 61 6c 6c 20 63 61 6c  after.** all cal
1ec90 6c 73 20 74 6f 20 74 68 65 20 69 6e 74 65 72 66  ls to the interf
1eca0 61 63 65 73 20 6c 69 73 74 65 64 20 68 65 72 65  aces listed here
1ecb0 20 61 72 65 20 63 6f 6d 70 6c 65 74 65 64 2e 0a   are completed..
1ecc0 2a 2a 0a 2a 2a 20 49 66 20 61 6e 20 69 6e 74 65  **.** If an inte
1ecd0 72 66 61 63 65 20 66 61 69 6c 73 20 77 69 74 68  rface fails with
1ece0 20 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 2c 20   SQLITE_MISUSE, 
1ecf0 74 68 61 74 20 6d 65 61 6e 73 20 74 68 65 20 69  that means the i
1ed00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 77 61 73 20  nterface.** was 
1ed10 69 6e 76 6f 6b 65 64 20 69 6e 63 6f 72 72 65 63  invoked incorrec
1ed20 74 6c 79 20 62 79 20 74 68 65 20 61 70 70 6c 69  tly by the appli
1ed30 63 61 74 69 6f 6e 2e 20 20 49 6e 20 74 68 61 74  cation.  In that
1ed40 20 63 61 73 65 2c 20 74 68 65 0a 2a 2a 20 65 72   case, the.** er
1ed50 72 6f 72 20 63 6f 64 65 20 61 6e 64 20 6d 65 73  ror code and mes
1ed60 73 61 67 65 20 6d 61 79 20 6f 72 20 6d 61 79 20  sage may or may 
1ed70 6e 6f 74 20 62 65 20 73 65 74 2e 0a 2a 2f 0a 69  not be set..*/.i
1ed80 6e 74 20 73 71 6c 69 74 65 33 5f 65 72 72 63 6f  nt sqlite3_errco
1ed90 64 65 28 73 71 6c 69 74 65 33 20 2a 64 62 29 3b  de(sqlite3 *db);
1eda0 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 78 74  .int sqlite3_ext
1edb0 65 6e 64 65 64 5f 65 72 72 63 6f 64 65 28 73 71  ended_errcode(sq
1edc0 6c 69 74 65 33 20 2a 64 62 29 3b 0a 63 6f 6e 73  lite3 *db);.cons
1edd0 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f  t char *sqlite3_
1ede0 65 72 72 6d 73 67 28 73 71 6c 69 74 65 33 2a 29  errmsg(sqlite3*)
1edf0 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  ;.const void *sq
1ee00 6c 69 74 65 33 5f 65 72 72 6d 73 67 31 36 28 73  lite3_errmsg16(s
1ee10 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f 2a 0a 2a 2a  qlite3*);../*.**
1ee20 20 43 41 50 49 33 52 45 46 3a 20 53 51 4c 20 53   CAPI3REF: SQL S
1ee30 74 61 74 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a  tatement Object.
1ee40 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 70 72  ** KEYWORDS: {pr
1ee50 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
1ee60 7d 20 7b 70 72 65 70 61 72 65 64 20 73 74 61 74  } {prepared stat
1ee70 65 6d 65 6e 74 73 7d 0a 2a 2a 0a 2a 2a 20 41 6e  ements}.**.** An
1ee80 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68 69   instance of thi
1ee90 73 20 6f 62 6a 65 63 74 20 72 65 70 72 65 73 65  s object represe
1eea0 6e 74 73 20 61 20 73 69 6e 67 6c 65 20 53 51 4c  nts a single SQL
1eeb0 20 73 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 54   statement..** T
1eec0 68 69 73 20 6f 62 6a 65 63 74 20 69 73 20 76 61  his object is va
1eed0 72 69 6f 75 73 6c 79 20 6b 6e 6f 77 6e 20 61 73  riously known as
1eee0 20 61 20 22 70 72 65 70 61 72 65 64 20 73 74 61   a "prepared sta
1eef0 74 65 6d 65 6e 74 22 20 6f 72 20 61 0a 2a 2a 20  tement" or a.** 
1ef00 22 63 6f 6d 70 69 6c 65 64 20 53 51 4c 20 73 74  "compiled SQL st
1ef10 61 74 65 6d 65 6e 74 22 20 6f 72 20 73 69 6d 70  atement" or simp
1ef20 6c 79 20 61 73 20 61 20 22 73 74 61 74 65 6d 65  ly as a "stateme
1ef30 6e 74 22 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 6c  nt"..**.** The l
1ef40 69 66 65 20 6f 66 20 61 20 73 74 61 74 65 6d 65  ife of a stateme
1ef50 6e 74 20 6f 62 6a 65 63 74 20 67 6f 65 73 20 73  nt object goes s
1ef60 6f 6d 65 74 68 69 6e 67 20 6c 69 6b 65 20 74 68  omething like th
1ef70 69 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a  is:.**.** <ol>.*
1ef80 2a 20 3c 6c 69 3e 20 43 72 65 61 74 65 20 74 68  * <li> Create th
1ef90 65 20 6f 62 6a 65 63 74 20 75 73 69 6e 67 20 5b  e object using [
1efa0 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
1efb0 76 32 28 29 5d 20 6f 72 20 61 20 72 65 6c 61 74  v2()] or a relat
1efc0 65 64 0a 2a 2a 20 20 20 20 20 20 66 75 6e 63 74  ed.**      funct
1efd0 69 6f 6e 2e 0a 2a 2a 20 3c 6c 69 3e 20 42 69 6e  ion..** <li> Bin
1efe0 64 20 76 61 6c 75 65 73 20 74 6f 20 5b 68 6f 73  d values to [hos
1eff0 74 20 70 61 72 61 6d 65 74 65 72 73 5d 20 75 73  t parameters] us
1f000 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
1f010 62 69 6e 64 5f 2a 28 29 0a 2a 2a 20 20 20 20 20  bind_*().**     
1f020 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a 20   interfaces..** 
1f030 3c 6c 69 3e 20 52 75 6e 20 74 68 65 20 53 51 4c  <li> Run the SQL
1f040 20 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c   by calling [sql
1f050 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f 6e 65  ite3_step()] one
1f060 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e 0a   or more times..
1f070 2a 2a 20 3c 6c 69 3e 20 52 65 73 65 74 20 74 68  ** <li> Reset th
1f080 65 20 73 74 61 74 65 6d 65 6e 74 20 75 73 69 6e  e statement usin
1f090 67 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  g [sqlite3_reset
1f0a0 28 29 5d 20 74 68 65 6e 20 67 6f 20 62 61 63 6b  ()] then go back
1f0b0 0a 2a 2a 20 20 20 20 20 20 74 6f 20 73 74 65 70  .**      to step
1f0c0 20 32 2e 20 20 44 6f 20 74 68 69 73 20 7a 65 72   2.  Do this zer
1f0d0 6f 20 6f 72 20 6d 6f 72 65 20 74 69 6d 65 73 2e  o or more times.
1f0e0 0a 2a 2a 20 3c 6c 69 3e 20 44 65 73 74 72 6f 79  .** <li> Destroy
1f0f0 20 74 68 65 20 6f 62 6a 65 63 74 20 75 73 69 6e   the object usin
1f100 67 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  g [sqlite3_final
1f110 69 7a 65 28 29 5d 2e 0a 2a 2a 20 3c 2f 6f 6c 3e  ize()]..** </ol>
1f120 0a 2a 2a 0a 2a 2a 20 52 65 66 65 72 20 74 6f 20  .**.** Refer to 
1f130 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 6f 6e  documentation on
1f140 20 69 6e 64 69 76 69 64 75 61 6c 20 6d 65 74 68   individual meth
1f150 6f 64 73 20 61 62 6f 76 65 20 66 6f 72 20 61 64  ods above for ad
1f160 64 69 74 69 6f 6e 61 6c 0a 2a 2a 20 69 6e 66 6f  ditional.** info
1f170 72 6d 61 74 69 6f 6e 2e 0a 2a 2f 0a 74 79 70 65  rmation..*/.type
1f180 64 65 66 20 73 74 72 75 63 74 20 73 71 6c 69 74  def struct sqlit
1f190 65 33 5f 73 74 6d 74 20 73 71 6c 69 74 65 33 5f  e3_stmt sqlite3_
1f1a0 73 74 6d 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  stmt;../*.** CAP
1f1b0 49 33 52 45 46 3a 20 52 75 6e 2d 74 69 6d 65 20  I3REF: Run-time 
1f1c0 4c 69 6d 69 74 73 0a 2a 2a 0a 2a 2a 20 5e 28 54  Limits.**.** ^(T
1f1d0 68 69 73 20 69 6e 74 65 72 66 61 63 65 20 61 6c  his interface al
1f1e0 6c 6f 77 73 20 74 68 65 20 73 69 7a 65 20 6f 66  lows the size of
1f1f0 20 76 61 72 69 6f 75 73 20 63 6f 6e 73 74 72 75   various constru
1f200 63 74 73 20 74 6f 20 62 65 20 6c 69 6d 69 74 65  cts to be limite
1f210 64 0a 2a 2a 20 6f 6e 20 61 20 63 6f 6e 6e 65 63  d.** on a connec
1f220 74 69 6f 6e 20 62 79 20 63 6f 6e 6e 65 63 74 69  tion by connecti
1f230 6f 6e 20 62 61 73 69 73 2e 20 20 54 68 65 20 66  on basis.  The f
1f240 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20 69  irst parameter i
1f250 73 20 74 68 65 0a 2a 2a 20 5b 64 61 74 61 62 61  s the.** [databa
1f260 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 77  se connection] w
1f270 68 6f 73 65 20 6c 69 6d 69 74 20 69 73 20 74 6f  hose limit is to
1f280 20 62 65 20 73 65 74 20 6f 72 20 71 75 65 72 69   be set or queri
1f290 65 64 2e 20 20 54 68 65 0a 2a 2a 20 73 65 63 6f  ed.  The.** seco
1f2a0 6e 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  nd parameter is 
1f2b0 6f 6e 65 20 6f 66 20 74 68 65 20 5b 6c 69 6d 69  one of the [limi
1f2c0 74 20 63 61 74 65 67 6f 72 69 65 73 5d 20 74 68  t categories] th
1f2d0 61 74 20 64 65 66 69 6e 65 20 61 0a 2a 2a 20 63  at define a.** c
1f2e0 6c 61 73 73 20 6f 66 20 63 6f 6e 73 74 72 75 63  lass of construc
1f2f0 74 73 20 74 6f 20 62 65 20 73 69 7a 65 20 6c 69  ts to be size li
1f300 6d 69 74 65 64 2e 20 20 54 68 65 20 74 68 69 72  mited.  The thir
1f310 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74  d parameter is t
1f320 68 65 0a 2a 2a 20 6e 65 77 20 6c 69 6d 69 74 20  he.** new limit 
1f330 66 6f 72 20 74 68 61 74 20 63 6f 6e 73 74 72 75  for that constru
1f340 63 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  ct.)^.**.** ^If 
1f350 74 68 65 20 6e 65 77 20 6c 69 6d 69 74 20 69 73  the new limit is
1f360 20 61 20 6e 65 67 61 74 69 76 65 20 6e 75 6d 62   a negative numb
1f370 65 72 2c 20 74 68 65 20 6c 69 6d 69 74 20 69 73  er, the limit is
1f380 20 75 6e 63 68 61 6e 67 65 64 2e 0a 2a 2a 20 5e   unchanged..** ^
1f390 28 46 6f 72 20 65 61 63 68 20 6c 69 6d 69 74 20  (For each limit 
1f3a0 63 61 74 65 67 6f 72 79 20 53 51 4c 49 54 45 5f  category SQLITE_
1f3b0 4c 49 4d 49 54 5f 3c 69 3e 4e 41 4d 45 3c 2f 69  LIMIT_<i>NAME</i
1f3c0 3e 20 74 68 65 72 65 20 69 73 20 61 20 0a 2a 2a  > there is a .**
1f3d0 20 5b 6c 69 6d 69 74 73 20 7c 20 68 61 72 64 20   [limits | hard 
1f3e0 75 70 70 65 72 20 62 6f 75 6e 64 5d 0a 2a 2a 20  upper bound].** 
1f3f0 73 65 74 20 61 74 20 63 6f 6d 70 69 6c 65 2d 74  set at compile-t
1f400 69 6d 65 20 62 79 20 61 20 43 20 70 72 65 70 72  ime by a C prepr
1f410 6f 63 65 73 73 6f 72 20 6d 61 63 72 6f 20 63 61  ocessor macro ca
1f420 6c 6c 65 64 0a 2a 2a 20 5b 6c 69 6d 69 74 73 20  lled.** [limits 
1f430 7c 20 53 51 4c 49 54 45 5f 4d 41 58 5f 3c 69 3e  | SQLITE_MAX_<i>
1f440 4e 41 4d 45 3c 2f 69 3e 5d 2e 0a 2a 2a 20 28 54  NAME</i>]..** (T
1f450 68 65 20 22 5f 4c 49 4d 49 54 5f 22 20 69 6e 20  he "_LIMIT_" in 
1f460 74 68 65 20 6e 61 6d 65 20 69 73 20 63 68 61 6e  the name is chan
1f470 67 65 64 20 74 6f 20 22 5f 4d 41 58 5f 22 2e 29  ged to "_MAX_".)
1f480 29 5e 0a 2a 2a 20 5e 41 74 74 65 6d 70 74 73 20  )^.** ^Attempts 
1f490 74 6f 20 69 6e 63 72 65 61 73 65 20 61 20 6c 69  to increase a li
1f4a0 6d 69 74 20 61 62 6f 76 65 20 69 74 73 20 68 61  mit above its ha
1f4b0 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64 20 61  rd upper bound a
1f4c0 72 65 0a 2a 2a 20 73 69 6c 65 6e 74 6c 79 20 74  re.** silently t
1f4d0 72 75 6e 63 61 74 65 64 20 74 6f 20 74 68 65 20  runcated to the 
1f4e0 68 61 72 64 20 75 70 70 65 72 20 62 6f 75 6e 64  hard upper bound
1f4f0 2e 0a 2a 2a 0a 2a 2a 20 5e 52 65 67 61 72 64 6c  ..**.** ^Regardl
1f500 65 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f  ess of whether o
1f510 72 20 6e 6f 74 20 74 68 65 20 6c 69 6d 69 74 20  r not the limit 
1f520 77 61 73 20 63 68 61 6e 67 65 64 2c 20 74 68 65  was changed, the
1f530 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6c 69   .** [sqlite3_li
1f540 6d 69 74 28 29 5d 20 69 6e 74 65 72 66 61 63 65  mit()] interface
1f550 20 72 65 74 75 72 6e 73 20 74 68 65 20 70 72 69   returns the pri
1f560 6f 72 20 76 61 6c 75 65 20 6f 66 20 74 68 65 20  or value of the 
1f570 6c 69 6d 69 74 2e 0a 2a 2a 20 5e 48 65 6e 63 65  limit..** ^Hence
1f580 2c 20 74 6f 20 66 69 6e 64 20 74 68 65 20 63 75  , to find the cu
1f590 72 72 65 6e 74 20 76 61 6c 75 65 20 6f 66 20 61  rrent value of a
1f5a0 20 6c 69 6d 69 74 20 77 69 74 68 6f 75 74 20 63   limit without c
1f5b0 68 61 6e 67 69 6e 67 20 69 74 2c 0a 2a 2a 20 73  hanging it,.** s
1f5c0 69 6d 70 6c 79 20 69 6e 76 6f 6b 65 20 74 68 69  imply invoke thi
1f5d0 73 20 69 6e 74 65 72 66 61 63 65 20 77 69 74 68  s interface with
1f5e0 20 74 68 65 20 74 68 69 72 64 20 70 61 72 61 6d   the third param
1f5f0 65 74 65 72 20 73 65 74 20 74 6f 20 2d 31 2e 0a  eter set to -1..
1f600 2a 2a 0a 2a 2a 20 52 75 6e 2d 74 69 6d 65 20 6c  **.** Run-time l
1f610 69 6d 69 74 73 20 61 72 65 20 69 6e 74 65 6e 64  imits are intend
1f620 65 64 20 66 6f 72 20 75 73 65 20 69 6e 20 61 70  ed for use in ap
1f630 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
1f640 6d 61 6e 61 67 65 0a 2a 2a 20 62 6f 74 68 20 74  manage.** both t
1f650 68 65 69 72 20 6f 77 6e 20 69 6e 74 65 72 6e 61  heir own interna
1f660 6c 20 64 61 74 61 62 61 73 65 20 61 6e 64 20 61  l database and a
1f670 6c 73 6f 20 64 61 74 61 62 61 73 65 73 20 74 68  lso databases th
1f680 61 74 20 61 72 65 20 63 6f 6e 74 72 6f 6c 6c 65  at are controlle
1f690 64 0a 2a 2a 20 62 79 20 75 6e 74 72 75 73 74 65  d.** by untruste
1f6a0 64 20 65 78 74 65 72 6e 61 6c 20 73 6f 75 72 63  d external sourc
1f6b0 65 73 2e 20 20 41 6e 20 65 78 61 6d 70 6c 65 20  es.  An example 
1f6c0 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d 69 67 68  application migh
1f6d0 74 20 62 65 20 61 0a 2a 2a 20 77 65 62 20 62 72  t be a.** web br
1f6e0 6f 77 73 65 72 20 74 68 61 74 20 68 61 73 20 69  owser that has i
1f6f0 74 73 20 6f 77 6e 20 64 61 74 61 62 61 73 65 73  ts own databases
1f700 20 66 6f 72 20 73 74 6f 72 69 6e 67 20 68 69 73   for storing his
1f710 74 6f 72 79 20 61 6e 64 0a 2a 2a 20 73 65 70 61  tory and.** sepa
1f720 72 61 74 65 20 64 61 74 61 62 61 73 65 73 20 63  rate databases c
1f730 6f 6e 74 72 6f 6c 6c 65 64 20 62 79 20 4a 61 76  ontrolled by Jav
1f740 61 53 63 72 69 70 74 20 61 70 70 6c 69 63 61 74  aScript applicat
1f750 69 6f 6e 73 20 64 6f 77 6e 6c 6f 61 64 65 64 0a  ions downloaded.
1f760 2a 2a 20 6f 66 66 20 74 68 65 20 49 6e 74 65 72  ** off the Inter
1f770 6e 65 74 2e 20 20 54 68 65 20 69 6e 74 65 72 6e  net.  The intern
1f780 61 6c 20 64 61 74 61 62 61 73 65 73 20 63 61 6e  al databases can
1f790 20 62 65 20 67 69 76 65 6e 20 74 68 65 0a 2a 2a   be given the.**
1f7a0 20 6c 61 72 67 65 2c 20 64 65 66 61 75 6c 74 20   large, default 
1f7b0 6c 69 6d 69 74 73 2e 20 20 44 61 74 61 62 61 73  limits.  Databas
1f7c0 65 73 20 6d 61 6e 61 67 65 64 20 62 79 20 65 78  es managed by ex
1f7d0 74 65 72 6e 61 6c 20 73 6f 75 72 63 65 73 20 63  ternal sources c
1f7e0 61 6e 0a 2a 2a 20 62 65 20 67 69 76 65 6e 20 6d  an.** be given m
1f7f0 75 63 68 20 73 6d 61 6c 6c 65 72 20 6c 69 6d 69  uch smaller limi
1f800 74 73 20 64 65 73 69 67 6e 65 64 20 74 6f 20 70  ts designed to p
1f810 72 65 76 65 6e 74 20 61 20 64 65 6e 69 61 6c 20  revent a denial 
1f820 6f 66 20 73 65 72 76 69 63 65 0a 2a 2a 20 61 74  of service.** at
1f830 74 61 63 6b 2e 20 20 44 65 76 65 6c 6f 70 65 72  tack.  Developer
1f840 73 20 6d 69 67 68 74 20 61 6c 73 6f 20 77 61 6e  s might also wan
1f850 74 20 74 6f 20 75 73 65 20 74 68 65 20 5b 73 71  t to use the [sq
1f860 6c 69 74 65 33 5f 73 65 74 5f 61 75 74 68 6f 72  lite3_set_author
1f870 69 7a 65 72 28 29 5d 0a 2a 2a 20 69 6e 74 65 72  izer()].** inter
1f880 66 61 63 65 20 74 6f 20 66 75 72 74 68 65 72 20  face to further 
1f890 63 6f 6e 74 72 6f 6c 20 75 6e 74 72 75 73 74 65  control untruste
1f8a0 64 20 53 51 4c 2e 20 20 54 68 65 20 73 69 7a 65  d SQL.  The size
1f8b0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
1f8c0 0a 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 61  .** created by a
1f8d0 6e 20 75 6e 74 72 75 73 74 65 64 20 73 63 72 69  n untrusted scri
1f8e0 70 74 20 63 61 6e 20 62 65 20 63 6f 6e 74 61 69  pt can be contai
1f8f0 6e 65 64 20 75 73 69 6e 67 20 74 68 65 0a 2a 2a  ned using the.**
1f900 20 5b 6d 61 78 5f 70 61 67 65 5f 63 6f 75 6e 74   [max_page_count
1f910 5d 20 5b 50 52 41 47 4d 41 5d 2e 0a 2a 2a 0a 2a  ] [PRAGMA]..**.*
1f920 2a 20 4e 65 77 20 72 75 6e 2d 74 69 6d 65 20 6c  * New run-time l
1f930 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73 20  imit categories 
1f940 6d 61 79 20 62 65 20 61 64 64 65 64 20 69 6e 20  may be added in 
1f950 66 75 74 75 72 65 20 72 65 6c 65 61 73 65 73 2e  future releases.
1f960 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
1f970 6c 69 6d 69 74 28 73 71 6c 69 74 65 33 2a 2c 20  limit(sqlite3*, 
1f980 69 6e 74 20 69 64 2c 20 69 6e 74 20 6e 65 77 56  int id, int newV
1f990 61 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  al);../*.** CAPI
1f9a0 33 52 45 46 3a 20 52 75 6e 2d 54 69 6d 65 20 4c  3REF: Run-Time L
1f9b0 69 6d 69 74 20 43 61 74 65 67 6f 72 69 65 73 0a  imit Categories.
1f9c0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 6c 69  ** KEYWORDS: {li
1f9d0 6d 69 74 20 63 61 74 65 67 6f 72 79 7d 20 7b 2a  mit category} {*
1f9e0 6c 69 6d 69 74 20 63 61 74 65 67 6f 72 69 65 73  limit categories
1f9f0 7d 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f  }.**.** These co
1fa00 6e 73 74 61 6e 74 73 20 64 65 66 69 6e 65 20 76  nstants define v
1fa10 61 72 69 6f 75 73 20 70 65 72 66 6f 72 6d 61 6e  arious performan
1fa20 63 65 20 6c 69 6d 69 74 73 0a 2a 2a 20 74 68 61  ce limits.** tha
1fa30 74 20 63 61 6e 20 62 65 20 6c 6f 77 65 72 65 64  t can be lowered
1fa40 20 61 74 20 72 75 6e 2d 74 69 6d 65 20 75 73 69   at run-time usi
1fa50 6e 67 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d 69  ng [sqlite3_limi
1fa60 74 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 73 79 6e  t()]..** The syn
1fa70 6f 70 73 69 73 20 6f 66 20 74 68 65 20 6d 65 61  opsis of the mea
1fa80 6e 69 6e 67 73 20 6f 66 20 74 68 65 20 76 61 72  nings of the var
1fa90 69 6f 75 73 20 6c 69 6d 69 74 73 20 69 73 20 73  ious limits is s
1faa0 68 6f 77 6e 20 62 65 6c 6f 77 2e 0a 2a 2a 20 41  hown below..** A
1fab0 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72 6d  dditional inform
1fac0 61 74 69 6f 6e 20 69 73 20 61 76 61 69 6c 61 62  ation is availab
1fad0 6c 65 20 61 74 20 5b 6c 69 6d 69 74 73 20 7c 20  le at [limits | 
1fae0 4c 69 6d 69 74 73 20 69 6e 20 53 51 4c 69 74 65  Limits in SQLite
1faf0 5d 2e 0a 2a 2a 0a 2a 2a 20 3c 64 6c 3e 0a 2a 2a  ]..**.** <dl>.**
1fb00 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1fb10 4d 49 54 5f 4c 45 4e 47 54 48 3c 2f 64 74 3e 0a  MIT_LENGTH</dt>.
1fb20 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d  ** <dd>The maxim
1fb30 75 6d 20 73 69 7a 65 20 6f 66 20 61 6e 79 20 73  um size of any s
1fb40 74 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 6f 72  tring or BLOB or
1fb50 20 74 61 62 6c 65 20 72 6f 77 2c 20 69 6e 20 62   table row, in b
1fb60 79 74 65 73 2e 3c 64 64 3e 29 5e 0a 2a 2a 0a 2a  ytes.<dd>)^.**.*
1fb70 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c  * ^(<dt>SQLITE_L
1fb80 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54 48 3c  IMIT_SQL_LENGTH<
1fb90 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20  /dt>.** <dd>The 
1fba0 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f  maximum length o
1fbb0 66 20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65  f an SQL stateme
1fbc0 6e 74 2c 20 69 6e 20 62 79 74 65 73 2e 3c 2f 64  nt, in bytes.</d
1fbd0 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  d>)^.**.** ^(<dt
1fbe0 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43 4f  >SQLITE_LIMIT_CO
1fbf0 4c 55 4d 4e 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  LUMN</dt>.** <dd
1fc00 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d  >The maximum num
1fc10 62 65 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69  ber of columns i
1fc20 6e 20 61 20 74 61 62 6c 65 20 64 65 66 69 6e 69  n a table defini
1fc30 74 69 6f 6e 20 6f 72 20 69 6e 20 74 68 65 0a 2a  tion or in the.*
1fc40 2a 20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20  * result set of 
1fc50 61 20 5b 53 45 4c 45 43 54 5d 20 6f 72 20 74 68  a [SELECT] or th
1fc60 65 20 6d 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72  e maximum number
1fc70 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61   of columns in a
1fc80 6e 20 69 6e 64 65 78 0a 2a 2a 20 6f 72 20 69 6e  n index.** or in
1fc90 20 61 6e 20 4f 52 44 45 52 20 42 59 20 6f 72 20   an ORDER BY or 
1fca0 47 52 4f 55 50 20 42 59 20 63 6c 61 75 73 65 2e  GROUP BY clause.
1fcb0 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28  </dd>)^.**.** ^(
1fcc0 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54  <dt>SQLITE_LIMIT
1fcd0 5f 45 58 50 52 5f 44 45 50 54 48 3c 2f 64 74 3e  _EXPR_DEPTH</dt>
1fce0 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78 69  .** <dd>The maxi
1fcf0 6d 75 6d 20 64 65 70 74 68 20 6f 66 20 74 68 65  mum depth of the
1fd00 20 70 61 72 73 65 20 74 72 65 65 20 6f 6e 20 61   parse tree on a
1fd10 6e 79 20 65 78 70 72 65 73 73 69 6f 6e 2e 3c 2f  ny expression.</
1fd20 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
1fd30 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 43  t>SQLITE_LIMIT_C
1fd40 4f 4d 50 4f 55 4e 44 5f 53 45 4c 45 43 54 3c 2f  OMPOUND_SELECT</
1fd50 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1fd60 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1fd70 20 74 65 72 6d 73 20 69 6e 20 61 20 63 6f 6d 70   terms in a comp
1fd80 6f 75 6e 64 20 53 45 4c 45 43 54 20 73 74 61 74  ound SELECT stat
1fd90 65 6d 65 6e 74 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a  ement.</dd>)^.**
1fda0 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
1fdb0 5f 4c 49 4d 49 54 5f 56 44 42 45 5f 4f 50 3c 2f  _LIMIT_VDBE_OP</
1fdc0 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
1fdd0 61 78 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66  aximum number of
1fde0 20 69 6e 73 74 72 75 63 74 69 6f 6e 73 20 69 6e   instructions in
1fdf0 20 61 20 76 69 72 74 75 61 6c 20 6d 61 63 68 69   a virtual machi
1fe00 6e 65 20 70 72 6f 67 72 61 6d 0a 2a 2a 20 75 73  ne program.** us
1fe10 65 64 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20  ed to implement 
1fe20 61 6e 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74  an SQL statement
1fe30 2e 20 20 54 68 69 73 20 6c 69 6d 69 74 20 69 73  .  This limit is
1fe40 20 6e 6f 74 20 63 75 72 72 65 6e 74 6c 79 0a 2a   not currently.*
1fe50 2a 20 65 6e 66 6f 72 63 65 64 2c 20 74 68 6f 75  * enforced, thou
1fe60 67 68 20 74 68 61 74 20 6d 69 67 68 74 20 62 65  gh that might be
1fe70 20 61 64 64 65 64 20 69 6e 20 73 6f 6d 65 20 66   added in some f
1fe80 75 74 75 72 65 20 72 65 6c 65 61 73 65 20 6f 66  uture release of
1fe90 0a 2a 2a 20 53 51 4c 69 74 65 2e 3c 2f 64 64 3e  .** SQLite.</dd>
1fea0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74 3e 53  )^.**.** ^(<dt>S
1feb0 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
1fec0 54 49 4f 4e 5f 41 52 47 3c 2f 64 74 3e 0a 2a 2a  TION_ARG</dt>.**
1fed0 20 3c 64 64 3e 54 68 65 20 6d 61 78 69 6d 75 6d   <dd>The maximum
1fee0 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67 75 6d   number of argum
1fef0 65 6e 74 73 20 6f 6e 20 61 20 66 75 6e 63 74 69  ents on a functi
1ff00 6f 6e 2e 3c 2f 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a  on.</dd>)^.**.**
1ff10 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45 5f 4c 49   ^(<dt>SQLITE_LI
1ff20 4d 49 54 5f 41 54 54 41 43 48 45 44 3c 2f 64 74  MIT_ATTACHED</dt
1ff30 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d 61 78  >.** <dd>The max
1ff40 69 6d 75 6d 20 6e 75 6d 62 65 72 20 6f 66 20 5b  imum number of [
1ff50 41 54 54 41 43 48 20 7c 20 61 74 74 61 63 68 65  ATTACH | attache
1ff60 64 20 64 61 74 61 62 61 73 65 73 5d 2e 29 5e 3c  d databases].)^<
1ff70 2f 64 64 3e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64 74  /dd>.**.** ^(<dt
1ff80 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49  >SQLITE_LIMIT_LI
1ff90 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
1ffa0 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68  H</dt>.** <dd>Th
1ffb0 65 20 6d 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68  e maximum length
1ffc0 20 6f 66 20 74 68 65 20 70 61 74 74 65 72 6e 20   of the pattern 
1ffd0 61 72 67 75 6d 65 6e 74 20 74 6f 20 74 68 65 20  argument to the 
1ffe0 5b 4c 49 4b 45 5d 20 6f 72 0a 2a 2a 20 5b 47 4c  [LIKE] or.** [GL
1fff0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 73 2e 3c 2f  OB] operators.</
20000 64 64 3e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 64  dd>)^.**.** ^(<d
20010 74 3e 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  t>SQLITE_LIMIT_V
20020 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 3c 2f  ARIABLE_NUMBER</
20030 64 74 3e 0a 2a 2a 20 3c 64 64 3e 54 68 65 20 6d  dt>.** <dd>The m
20040 61 78 69 6d 75 6d 20 69 6e 64 65 78 20 6e 75 6d  aximum index num
20050 62 65 72 20 6f 66 20 61 6e 79 20 5b 70 61 72 61  ber of any [para
20060 6d 65 74 65 72 5d 20 69 6e 20 61 6e 20 53 51 4c  meter] in an SQL
20070 20 73 74 61 74 65 6d 65 6e 74 2e 29 5e 0a 2a 2a   statement.)^.**
20080 0a 2a 2a 20 5e 28 3c 64 74 3e 53 51 4c 49 54 45  .** ^(<dt>SQLITE
20090 5f 4c 49 4d 49 54 5f 54 52 49 47 47 45 52 5f 44  _LIMIT_TRIGGER_D
200a0 45 50 54 48 3c 2f 64 74 3e 0a 2a 2a 20 3c 64 64  EPTH</dt>.** <dd
200b0 3e 54 68 65 20 6d 61 78 69 6d 75 6d 20 64 65 70  >The maximum dep
200c0 74 68 20 6f 66 20 72 65 63 75 72 73 69 6f 6e 20  th of recursion 
200d0 66 6f 72 20 74 72 69 67 67 65 72 73 2e 3c 2f 64  for triggers.</d
200e0 64 3e 29 5e 0a 2a 2a 20 3c 2f 64 6c 3e 0a 2a 2f  d>)^.** </dl>.*/
200f0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
20100 4c 49 4d 49 54 5f 4c 45 4e 47 54 48 20 20 20 20  LIMIT_LENGTH    
20110 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20120 30 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45  0.#define SQLITE
20130 5f 4c 49 4d 49 54 5f 53 51 4c 5f 4c 45 4e 47 54  _LIMIT_SQL_LENGT
20140 48 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  H               
20150 20 31 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54   1.#define SQLIT
20160 45 5f 4c 49 4d 49 54 5f 43 4f 4c 55 4d 4e 20 20  E_LIMIT_COLUMN  
20170 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
20180 20 20 32 0a 23 64 65 66 69 6e 65 20 53 51 4c 49    2.#define SQLI
20190 54 45 5f 4c 49 4d 49 54 5f 45 58 50 52 5f 44 45  TE_LIMIT_EXPR_DE
201a0 50 54 48 20 20 20 20 20 20 20 20 20 20 20 20 20  PTH             
201b0 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53 51 4c     3.#define SQL
201c0 49 54 45 5f 4c 49 4d 49 54 5f 43 4f 4d 50 4f 55  ITE_LIMIT_COMPOU
201d0 4e 44 5f 53 45 4c 45 43 54 20 20 20 20 20 20 20  ND_SELECT       
201e0 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51      4.#define SQ
201f0 4c 49 54 45 5f 4c 49 4d 49 54 5f 56 44 42 45 5f  LITE_LIMIT_VDBE_
20200 4f 50 20 20 20 20 20 20 20 20 20 20 20 20 20 20  OP              
20210 20 20 20 20 20 35 0a 23 64 65 66 69 6e 65 20 53       5.#define S
20220 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 46 55 4e 43  QLITE_LIMIT_FUNC
20230 54 49 4f 4e 5f 41 52 47 20 20 20 20 20 20 20 20  TION_ARG        
20240 20 20 20 20 20 20 36 0a 23 64 65 66 69 6e 65 20        6.#define 
20250 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 41 54 54  SQLITE_LIMIT_ATT
20260 41 43 48 45 44 20 20 20 20 20 20 20 20 20 20 20  ACHED           
20270 20 20 20 20 20 20 20 37 0a 23 64 65 66 69 6e 65         7.#define
20280 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 4c 49   SQLITE_LIMIT_LI
20290 4b 45 5f 50 41 54 54 45 52 4e 5f 4c 45 4e 47 54  KE_PATTERN_LENGT
202a0 48 20 20 20 20 20 20 20 38 0a 23 64 65 66 69 6e  H       8.#defin
202b0 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f 56  e SQLITE_LIMIT_V
202c0 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52 20 20  ARIABLE_NUMBER  
202d0 20 20 20 20 20 20 20 20 20 39 0a 23 64 65 66 69           9.#defi
202e0 6e 65 20 53 51 4c 49 54 45 5f 4c 49 4d 49 54 5f  ne SQLITE_LIMIT_
202f0 54 52 49 47 47 45 52 5f 44 45 50 54 48 20 20 20  TRIGGER_DEPTH   
20300 20 20 20 20 20 20 20 20 20 31 30 0a 0a 2f 2a 0a           10../*.
20310 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6d  ** CAPI3REF: Com
20320 70 69 6c 69 6e 67 20 41 6e 20 53 51 4c 20 53 74  piling An SQL St
20330 61 74 65 6d 65 6e 74 0a 2a 2a 20 4b 45 59 57 4f  atement.** KEYWO
20340 52 44 53 3a 20 7b 53 51 4c 20 73 74 61 74 65 6d  RDS: {SQL statem
20350 65 6e 74 20 63 6f 6d 70 69 6c 65 72 7d 0a 2a 2a  ent compiler}.**
20360 0a 2a 2a 20 54 6f 20 65 78 65 63 75 74 65 20 61  .** To execute a
20370 6e 20 53 51 4c 20 71 75 65 72 79 2c 20 69 74 20  n SQL query, it 
20380 6d 75 73 74 20 66 69 72 73 74 20 62 65 20 63 6f  must first be co
20390 6d 70 69 6c 65 64 20 69 6e 74 6f 20 61 20 62 79  mpiled into a by
203a0 74 65 2d 63 6f 64 65 0a 2a 2a 20 70 72 6f 67 72  te-code.** progr
203b0 61 6d 20 75 73 69 6e 67 20 6f 6e 65 20 6f 66 20  am using one of 
203c0 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 2e 0a  these routines..
203d0 2a 2a 0a 2a 2a 20 54 68 65 20 66 69 72 73 74 20  **.** The first 
203e0 61 72 67 75 6d 65 6e 74 2c 20 22 64 62 22 2c 20  argument, "db", 
203f0 69 73 20 61 20 5b 64 61 74 61 62 61 73 65 20 63  is a [database c
20400 6f 6e 6e 65 63 74 69 6f 6e 5d 20 6f 62 74 61 69  onnection] obtai
20410 6e 65 64 20 66 72 6f 6d 20 61 0a 2a 2a 20 70 72  ned from a.** pr
20420 69 6f 72 20 73 75 63 63 65 73 73 66 75 6c 20 63  ior successful c
20430 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
20440 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  open()], [sqlite
20450 33 5f 6f 70 65 6e 5f 76 32 28 29 5d 20 6f 72 0a  3_open_v2()] or.
20460 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  ** [sqlite3_open
20470 31 36 28 29 5d 2e 20 20 54 68 65 20 64 61 74 61  16()].  The data
20480 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
20490 6d 75 73 74 20 6e 6f 74 20 68 61 76 65 20 62 65  must not have be
204a0 65 6e 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a  en closed..**.**
204b0 20 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   The second argu
204c0 6d 65 6e 74 2c 20 22 7a 53 71 6c 22 2c 20 69 73  ment, "zSql", is
204d0 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 74   the statement t
204e0 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 2c 20 65  o be compiled, e
204f0 6e 63 6f 64 65 64 0a 2a 2a 20 61 73 20 65 69 74  ncoded.** as eit
20500 68 65 72 20 55 54 46 2d 38 20 6f 72 20 55 54 46  her UTF-8 or UTF
20510 2d 31 36 2e 20 20 54 68 65 20 73 71 6c 69 74 65  -16.  The sqlite
20520 33 5f 70 72 65 70 61 72 65 28 29 20 61 6e 64 20  3_prepare() and 
20530 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f  sqlite3_prepare_
20540 76 32 28 29 0a 2a 2a 20 69 6e 74 65 72 66 61 63  v2().** interfac
20550 65 73 20 75 73 65 20 55 54 46 2d 38 2c 20 61 6e  es use UTF-8, an
20560 64 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72  d sqlite3_prepar
20570 65 31 36 28 29 20 61 6e 64 20 73 71 6c 69 74 65  e16() and sqlite
20580 33 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29  3_prepare16_v2()
20590 0a 2a 2a 20 75 73 65 20 55 54 46 2d 31 36 2e 0a  .** use UTF-16..
205a0 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 6e 42  **.** ^If the nB
205b0 79 74 65 20 61 72 67 75 6d 65 6e 74 20 69 73 20  yte argument is 
205c0 6c 65 73 73 20 74 68 61 6e 20 7a 65 72 6f 2c 20  less than zero, 
205d0 74 68 65 6e 20 7a 53 71 6c 20 69 73 20 72 65 61  then zSql is rea
205e0 64 20 75 70 20 74 6f 20 74 68 65 0a 2a 2a 20 66  d up to the.** f
205f0 69 72 73 74 20 7a 65 72 6f 20 74 65 72 6d 69 6e  irst zero termin
20600 61 74 6f 72 2e 20 5e 49 66 20 6e 42 79 74 65 20  ator. ^If nByte 
20610 69 73 20 6e 6f 6e 2d 6e 65 67 61 74 69 76 65 2c  is non-negative,
20620 20 74 68 65 6e 20 69 74 20 69 73 20 74 68 65 20   then it is the 
20630 6d 61 78 69 6d 75 6d 0a 2a 2a 20 6e 75 6d 62 65  maximum.** numbe
20640 72 20 6f 66 20 20 62 79 74 65 73 20 72 65 61 64  r of  bytes read
20650 20 66 72 6f 6d 20 7a 53 71 6c 2e 20 20 5e 57 68   from zSql.  ^Wh
20660 65 6e 20 6e 42 79 74 65 20 69 73 20 6e 6f 6e 2d  en nByte is non-
20670 6e 65 67 61 74 69 76 65 2c 20 74 68 65 0a 2a 2a  negative, the.**
20680 20 7a 53 71 6c 20 73 74 72 69 6e 67 20 65 6e 64   zSql string end
20690 73 20 61 74 20 65 69 74 68 65 72 20 74 68 65 20  s at either the 
206a0 66 69 72 73 74 20 27 5c 30 30 30 27 20 6f 72 20  first '\000' or 
206b0 27 5c 75 30 30 30 30 27 20 63 68 61 72 61 63 74  '\u0000' charact
206c0 65 72 20 6f 72 0a 2a 2a 20 74 68 65 20 6e 42 79  er or.** the nBy
206d0 74 65 2d 74 68 20 62 79 74 65 2c 20 77 68 69 63  te-th byte, whic
206e0 68 65 76 65 72 20 63 6f 6d 65 73 20 66 69 72 73  hever comes firs
206f0 74 2e 20 49 66 20 74 68 65 20 63 61 6c 6c 65 72  t. If the caller
20700 20 6b 6e 6f 77 73 0a 2a 2a 20 74 68 61 74 20 74   knows.** that t
20710 68 65 20 73 75 70 70 6c 69 65 64 20 73 74 72 69  he supplied stri
20720 6e 67 20 69 73 20 6e 75 6c 2d 74 65 72 6d 69 6e  ng is nul-termin
20730 61 74 65 64 2c 20 74 68 65 6e 20 74 68 65 72 65  ated, then there
20740 20 69 73 20 61 20 73 6d 61 6c 6c 0a 2a 2a 20 70   is a small.** p
20750 65 72 66 6f 72 6d 61 6e 63 65 20 61 64 76 61 6e  erformance advan
20760 74 61 67 65 20 74 6f 20 62 65 20 67 61 69 6e 65  tage to be gaine
20770 64 20 62 79 20 70 61 73 73 69 6e 67 20 61 6e 20  d by passing an 
20780 6e 42 79 74 65 20 70 61 72 61 6d 65 74 65 72 20  nByte parameter 
20790 74 68 61 74 0a 2a 2a 20 69 73 20 65 71 75 61 6c  that.** is equal
207a0 20 74 6f 20 74 68 65 20 6e 75 6d 62 65 72 20 6f   to the number o
207b0 66 20 62 79 74 65 73 20 69 6e 20 74 68 65 20 69  f bytes in the i
207c0 6e 70 75 74 20 73 74 72 69 6e 67 20 3c 69 3e 69  nput string <i>i
207d0 6e 63 6c 75 64 69 6e 67 3c 2f 69 3e 0a 2a 2a 20  ncluding</i>.** 
207e0 74 68 65 20 6e 75 6c 2d 74 65 72 6d 69 6e 61 74  the nul-terminat
207f0 6f 72 20 62 79 74 65 73 2e 0a 2a 2a 0a 2a 2a 20  or bytes..**.** 
20800 5e 49 66 20 70 7a 54 61 69 6c 20 69 73 20 6e 6f  ^If pzTail is no
20810 74 20 4e 55 4c 4c 20 74 68 65 6e 20 2a 70 7a 54  t NULL then *pzT
20820 61 69 6c 20 69 73 20 6d 61 64 65 20 74 6f 20 70  ail is made to p
20830 6f 69 6e 74 20 74 6f 20 74 68 65 20 66 69 72 73  oint to the firs
20840 74 20 62 79 74 65 0a 2a 2a 20 70 61 73 74 20 74  t byte.** past t
20850 68 65 20 65 6e 64 20 6f 66 20 74 68 65 20 66 69  he end of the fi
20860 72 73 74 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  rst SQL statemen
20870 74 20 69 6e 20 7a 53 71 6c 2e 20 20 54 68 65 73  t in zSql.  Thes
20880 65 20 72 6f 75 74 69 6e 65 73 20 6f 6e 6c 79 0a  e routines only.
20890 2a 2a 20 63 6f 6d 70 69 6c 65 20 74 68 65 20 66  ** compile the f
208a0 69 72 73 74 20 73 74 61 74 65 6d 65 6e 74 20 69  irst statement i
208b0 6e 20 7a 53 71 6c 2c 20 73 6f 20 2a 70 7a 54 61  n zSql, so *pzTa
208c0 69 6c 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74  il is left point
208d0 69 6e 67 20 74 6f 0a 2a 2a 20 77 68 61 74 20 72  ing to.** what r
208e0 65 6d 61 69 6e 73 20 75 6e 63 6f 6d 70 69 6c 65  emains uncompile
208f0 64 2e 0a 2a 2a 0a 2a 2a 20 5e 2a 70 70 53 74 6d  d..**.** ^*ppStm
20900 74 20 69 73 20 6c 65 66 74 20 70 6f 69 6e 74 69  t is left pointi
20910 6e 67 20 74 6f 20 61 20 63 6f 6d 70 69 6c 65 64  ng to a compiled
20920 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
20930 6d 65 6e 74 5d 20 74 68 61 74 20 63 61 6e 20 62  ment] that can b
20940 65 0a 2a 2a 20 65 78 65 63 75 74 65 64 20 75 73  e.** executed us
20950 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  ing [sqlite3_ste
20960 70 28 29 5d 2e 20 20 5e 49 66 20 74 68 65 72 65  p()].  ^If there
20970 20 69 73 20 61 6e 20 65 72 72 6f 72 2c 20 2a 70   is an error, *p
20980 70 53 74 6d 74 20 69 73 20 73 65 74 0a 2a 2a 20  pStmt is set.** 
20990 74 6f 20 4e 55 4c 4c 2e 20 20 5e 49 66 20 74 68  to NULL.  ^If th
209a0 65 20 69 6e 70 75 74 20 74 65 78 74 20 63 6f 6e  e input text con
209b0 74 61 69 6e 73 20 6e 6f 20 53 51 4c 20 28 69 66  tains no SQL (if
209c0 20 74 68 65 20 69 6e 70 75 74 20 69 73 20 61 6e   the input is an
209d0 20 65 6d 70 74 79 0a 2a 2a 20 73 74 72 69 6e 67   empty.** string
209e0 20 6f 72 20 61 20 63 6f 6d 6d 65 6e 74 29 20 74   or a comment) t
209f0 68 65 6e 20 2a 70 70 53 74 6d 74 20 69 73 20 73  hen *ppStmt is s
20a00 65 74 20 74 6f 20 4e 55 4c 4c 2e 0a 2a 2a 20 54  et to NULL..** T
20a10 68 65 20 63 61 6c 6c 69 6e 67 20 70 72 6f 63 65  he calling proce
20a20 64 75 72 65 20 69 73 20 72 65 73 70 6f 6e 73 69  dure is responsi
20a30 62 6c 65 20 66 6f 72 20 64 65 6c 65 74 69 6e 67  ble for deleting
20a40 20 74 68 65 20 63 6f 6d 70 69 6c 65 64 0a 2a 2a   the compiled.**
20a50 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 75   SQL statement u
20a60 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f 66 69  sing [sqlite3_fi
20a70 6e 61 6c 69 7a 65 28 29 5d 20 61 66 74 65 72 20  nalize()] after 
20a80 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
20a90 77 69 74 68 20 69 74 2e 0a 2a 2a 20 70 70 53 74  with it..** ppSt
20aa0 6d 74 20 6d 61 79 20 6e 6f 74 20 62 65 20 4e 55  mt may not be NU
20ab0 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 4f 6e 20 73 75  LL..**.** ^On su
20ac0 63 63 65 73 73 2c 20 74 68 65 20 73 71 6c 69 74  ccess, the sqlit
20ad0 65 33 5f 70 72 65 70 61 72 65 28 29 20 66 61 6d  e3_prepare() fam
20ae0 69 6c 79 20 6f 66 20 72 6f 75 74 69 6e 65 73 20  ily of routines 
20af0 72 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4f  return [SQLITE_O
20b00 4b 5d 3b 0a 2a 2a 20 6f 74 68 65 72 77 69 73 65  K];.** otherwise
20b10 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d   an [error code]
20b20 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a   is returned..**
20b30 0a 2a 2a 20 54 68 65 20 73 71 6c 69 74 65 33 5f  .** The sqlite3_
20b40 70 72 65 70 61 72 65 5f 76 32 28 29 20 61 6e 64  prepare_v2() and
20b50 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65   sqlite3_prepare
20b60 31 36 5f 76 32 28 29 20 69 6e 74 65 72 66 61 63  16_v2() interfac
20b70 65 73 20 61 72 65 0a 2a 2a 20 72 65 63 6f 6d 6d  es are.** recomm
20b80 65 6e 64 65 64 20 66 6f 72 20 61 6c 6c 20 6e 65  ended for all ne
20b90 77 20 70 72 6f 67 72 61 6d 73 2e 20 54 68 65 20  w programs. The 
20ba0 74 77 6f 20 6f 6c 64 65 72 20 69 6e 74 65 72 66  two older interf
20bb0 61 63 65 73 20 61 72 65 20 72 65 74 61 69 6e 65  aces are retaine
20bc0 64 0a 2a 2a 20 66 6f 72 20 62 61 63 6b 77 61 72  d.** for backwar
20bd0 64 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79  ds compatibility
20be0 2c 20 62 75 74 20 74 68 65 69 72 20 75 73 65 20  , but their use 
20bf0 69 73 20 64 69 73 63 6f 75 72 61 67 65 64 2e 0a  is discouraged..
20c00 2a 2a 20 5e 49 6e 20 74 68 65 20 22 76 32 22 20  ** ^In the "v2" 
20c10 69 6e 74 65 72 66 61 63 65 73 2c 20 74 68 65 20  interfaces, the 
20c20 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65  prepared stateme
20c30 6e 74 0a 2a 2a 20 74 68 61 74 20 69 73 20 72 65  nt.** that is re
20c40 74 75 72 6e 65 64 20 28 74 68 65 20 5b 73 71 6c  turned (the [sql
20c50 69 74 65 33 5f 73 74 6d 74 5d 20 6f 62 6a 65 63  ite3_stmt] objec
20c60 74 29 20 63 6f 6e 74 61 69 6e 73 20 61 20 63 6f  t) contains a co
20c70 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 6f 72 69  py of the.** ori
20c80 67 69 6e 61 6c 20 53 51 4c 20 74 65 78 74 2e 20  ginal SQL text. 
20c90 54 68 69 73 20 63 61 75 73 65 73 20 74 68 65 20  This causes the 
20ca0 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
20cb0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
20cc0 20 62 65 68 61 76 65 20 64 69 66 66 65 72 65 6e   behave differen
20cd0 74 6c 79 20 69 6e 20 74 68 72 65 65 20 77 61 79  tly in three way
20ce0 73 3a 0a 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a  s:.**.** <ol>.**
20cf0 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74 68 65   <li>.** ^If the
20d00 20 64 61 74 61 62 61 73 65 20 73 63 68 65 6d 61   database schema
20d10 20 63 68 61 6e 67 65 73 2c 20 69 6e 73 74 65 61   changes, instea
20d20 64 20 6f 66 20 72 65 74 75 72 6e 69 6e 67 20 5b  d of returning [
20d30 53 51 4c 49 54 45 5f 53 43 48 45 4d 41 5d 20 61  SQLITE_SCHEMA] a
20d40 73 20 69 74 0a 2a 2a 20 61 6c 77 61 79 73 20 75  s it.** always u
20d50 73 65 64 20 74 6f 20 64 6f 2c 20 5b 73 71 6c 69  sed to do, [sqli
20d60 74 65 33 5f 73 74 65 70 28 29 5d 20 77 69 6c 6c  te3_step()] will
20d70 20 61 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 72   automatically r
20d80 65 63 6f 6d 70 69 6c 65 20 74 68 65 20 53 51 4c  ecompile the SQL
20d90 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  .** statement an
20da0 64 20 74 72 79 20 74 6f 20 72 75 6e 20 69 74 20  d try to run it 
20db0 61 67 61 69 6e 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a  again..** </li>.
20dc0 2a 2a 0a 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 57  **.** <li>.** ^W
20dd0 68 65 6e 20 61 6e 20 65 72 72 6f 72 20 6f 63 63  hen an error occ
20de0 75 72 73 2c 20 5b 73 71 6c 69 74 65 33 5f 73 74  urs, [sqlite3_st
20df0 65 70 28 29 5d 20 77 69 6c 6c 20 72 65 74 75 72  ep()] will retur
20e00 6e 20 6f 6e 65 20 6f 66 20 74 68 65 20 64 65 74  n one of the det
20e10 61 69 6c 65 64 0a 2a 2a 20 5b 65 72 72 6f 72 20  ailed.** [error 
20e20 63 6f 64 65 73 5d 20 6f 72 20 5b 65 78 74 65 6e  codes] or [exten
20e30 64 65 64 20 65 72 72 6f 72 20 63 6f 64 65 73 5d  ded error codes]
20e40 2e 20 20 5e 54 68 65 20 6c 65 67 61 63 79 20 62  .  ^The legacy b
20e50 65 68 61 76 69 6f 72 20 77 61 73 20 74 68 61 74  ehavior was that
20e60 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
20e70 70 28 29 5d 20 77 6f 75 6c 64 20 6f 6e 6c 79 20  p()] would only 
20e80 72 65 74 75 72 6e 20 61 20 67 65 6e 65 72 69 63  return a generic
20e90 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
20ea0 72 65 73 75 6c 74 20 63 6f 64 65 0a 2a 2a 20 61  result code.** a
20eb0 6e 64 20 74 68 65 20 61 70 70 6c 69 63 61 74 69  nd the applicati
20ec0 6f 6e 20 77 6f 75 6c 64 20 68 61 76 65 20 74 6f  on would have to
20ed0 20 6d 61 6b 65 20 61 20 73 65 63 6f 6e 64 20 63   make a second c
20ee0 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  all to [sqlite3_
20ef0 72 65 73 65 74 28 29 5d 0a 2a 2a 20 69 6e 20 6f  reset()].** in o
20f00 72 64 65 72 20 74 6f 20 66 69 6e 64 20 74 68 65  rder to find the
20f10 20 75 6e 64 65 72 6c 79 69 6e 67 20 63 61 75 73   underlying caus
20f20 65 20 6f 66 20 74 68 65 20 70 72 6f 62 6c 65 6d  e of the problem
20f30 2e 20 57 69 74 68 20 74 68 65 20 22 76 32 22 20  . With the "v2" 
20f40 70 72 65 70 61 72 65 0a 2a 2a 20 69 6e 74 65 72  prepare.** inter
20f50 66 61 63 65 73 2c 20 74 68 65 20 75 6e 64 65 72  faces, the under
20f60 6c 79 69 6e 67 20 72 65 61 73 6f 6e 20 66 6f 72  lying reason for
20f70 20 74 68 65 20 65 72 72 6f 72 20 69 73 20 72 65   the error is re
20f80 74 75 72 6e 65 64 20 69 6d 6d 65 64 69 61 74 65  turned immediate
20f90 6c 79 2e 0a 2a 2a 20 3c 2f 6c 69 3e 0a 2a 2a 0a  ly..** </li>.**.
20fa0 2a 2a 20 3c 6c 69 3e 0a 2a 2a 20 5e 49 66 20 74  ** <li>.** ^If t
20fb0 68 65 20 73 70 65 63 69 66 69 63 20 76 61 6c 75  he specific valu
20fc0 65 20 62 6f 75 6e 64 20 74 6f 20 5b 70 61 72 61  e bound to [para
20fd0 6d 65 74 65 72 20 7c 20 68 6f 73 74 20 70 61 72  meter | host par
20fe0 61 6d 65 74 65 72 5d 20 69 6e 20 74 68 65 20 0a  ameter] in the .
20ff0 2a 2a 20 57 48 45 52 45 20 63 6c 61 75 73 65 20  ** WHERE clause 
21000 6d 69 67 68 74 20 69 6e 66 6c 75 65 6e 63 65 20  might influence 
21010 74 68 65 20 63 68 6f 69 63 65 20 6f 66 20 71 75  the choice of qu
21020 65 72 79 20 70 6c 61 6e 20 66 6f 72 20 61 20 73  ery plan for a s
21030 74 61 74 65 6d 65 6e 74 2c 0a 2a 2a 20 74 68 65  tatement,.** the
21040 6e 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20  n the statement 
21050 77 69 6c 6c 20 62 65 20 61 75 74 6f 6d 61 74 69  will be automati
21060 63 61 6c 6c 79 20 72 65 63 6f 6d 70 69 6c 65 64  cally recompiled
21070 2c 20 61 73 20 69 66 20 74 68 65 72 65 20 68 61  , as if there ha
21080 64 20 62 65 65 6e 20 0a 2a 2a 20 61 20 73 63 68  d been .** a sch
21090 65 6d 61 20 63 68 61 6e 67 65 2c 20 6f 6e 20 74  ema change, on t
210a0 68 65 20 66 69 72 73 74 20 20 5b 73 71 6c 69 74  he first  [sqlit
210b0 65 33 5f 73 74 65 70 28 29 5d 20 63 61 6c 6c 20  e3_step()] call 
210c0 66 6f 6c 6c 6f 77 69 6e 67 20 61 6e 79 20 63 68  following any ch
210d0 61 6e 67 65 0a 2a 2a 20 74 6f 20 74 68 65 20 5b  ange.** to the [
210e0 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 74 65 78  sqlite3_bind_tex
210f0 74 20 7c 20 62 69 6e 64 69 6e 67 73 5d 20 6f 66  t | bindings] of
21100 20 74 68 61 74 20 5b 70 61 72 61 6d 65 74 65 72   that [parameter
21110 5d 2e 20 0a 2a 2a 20 5e 54 68 65 20 73 70 65 63  ]. .** ^The spec
21120 69 66 69 63 20 76 61 6c 75 65 20 6f 66 20 57 48  ific value of WH
21130 45 52 45 2d 63 6c 61 75 73 65 20 5b 70 61 72 61  ERE-clause [para
21140 6d 65 74 65 72 5d 20 6d 69 67 68 74 20 69 6e 66  meter] might inf
21150 6c 75 65 6e 63 65 20 74 68 65 20 0a 2a 2a 20 63  luence the .** c
21160 68 6f 69 63 65 20 6f 66 20 71 75 65 72 79 20 70  hoice of query p
21170 6c 61 6e 20 69 66 20 74 68 65 20 70 61 72 61 6d  lan if the param
21180 65 74 65 72 20 69 73 20 74 68 65 20 6c 65 66 74  eter is the left
21190 2d 68 61 6e 64 20 73 69 64 65 20 6f 66 20 61 20  -hand side of a 
211a0 5b 4c 49 4b 45 5d 0a 2a 2a 20 6f 72 20 5b 47 4c  [LIKE].** or [GL
211b0 4f 42 5d 20 6f 70 65 72 61 74 6f 72 20 6f 72 20  OB] operator or 
211c0 69 66 20 74 68 65 20 70 61 72 61 6d 65 74 65 72  if the parameter
211d0 20 69 73 20 63 6f 6d 70 61 72 65 64 20 74 6f 20   is compared to 
211e0 61 6e 20 69 6e 64 65 78 65 64 20 63 6f 6c 75 6d  an indexed colum
211f0 6e 0a 2a 2a 20 61 6e 64 20 74 68 65 20 5b 53 51  n.** and the [SQ
21200 4c 49 54 45 5f 45 4e 41 42 4c 45 5f 53 54 41 54  LITE_ENABLE_STAT
21210 32 5d 20 63 6f 6d 70 69 6c 65 2d 74 69 6d 65 20  2] compile-time 
21220 6f 70 74 69 6f 6e 20 69 73 20 65 6e 61 62 6c 65  option is enable
21230 64 2e 0a 2a 2a 20 74 68 65 20 0a 2a 2a 20 3c 2f  d..** the .** </
21240 6c 69 3e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2f 0a  li>.** </ol>.*/.
21250 69 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70  int sqlite3_prep
21260 61 72 65 28 0a 20 20 73 71 6c 69 74 65 33 20 2a  are(.  sqlite3 *
21270 64 62 2c 20 20 20 20 20 20 20 20 20 20 20 20 2f  db,            /
21280 2a 20 44 61 74 61 62 61 73 65 20 68 61 6e 64 6c  * Database handl
21290 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  e */.  const cha
212a0 72 20 2a 7a 53 71 6c 2c 20 20 20 20 20 20 20 2f  r *zSql,       /
212b0 2a 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 2c  * SQL statement,
212c0 20 55 54 46 2d 38 20 65 6e 63 6f 64 65 64 20 2a   UTF-8 encoded *
212d0 2f 0a 20 20 69 6e 74 20 6e 42 79 74 65 2c 20 20  /.  int nByte,  
212e0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4d              /* M
212f0 61 78 69 6d 75 6d 20 6c 65 6e 67 74 68 20 6f 66  aximum length of
21300 20 7a 53 71 6c 20 69 6e 20 62 79 74 65 73 2e 20   zSql in bytes. 
21310 2a 2f 0a 20 20 73 71 6c 69 74 65 33 5f 73 74 6d  */.  sqlite3_stm
21320 74 20 2a 2a 70 70 53 74 6d 74 2c 20 20 2f 2a 20  t **ppStmt,  /* 
21330 4f 55 54 3a 20 53 74 61 74 65 6d 65 6e 74 20 68  OUT: Statement h
21340 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
21350 20 63 68 61 72 20 2a 2a 70 7a 54 61 69 6c 20 20   char **pzTail  
21360 20 20 20 2f 2a 20 4f 55 54 3a 20 50 6f 69 6e 74     /* OUT: Point
21370 65 72 20 74 6f 20 75 6e 75 73 65 64 20 70 6f 72  er to unused por
21380 74 69 6f 6e 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a  tion of zSql */.
21390 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 70  );.int sqlite3_p
213a0 72 65 70 61 72 65 5f 76 32 28 0a 20 20 73 71 6c  repare_v2(.  sql
213b0 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20  ite3 *db,       
213c0 20 20 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65       /* Database
213d0 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e   handle */.  con
213e0 73 74 20 63 68 61 72 20 2a 7a 53 71 6c 2c 20 20  st char *zSql,  
213f0 20 20 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74       /* SQL stat
21400 65 6d 65 6e 74 2c 20 55 54 46 2d 38 20 65 6e 63  ement, UTF-8 enc
21410 6f 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42  oded */.  int nB
21420 79 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20  yte,            
21430 20 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e    /* Maximum len
21440 67 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62  gth of zSql in b
21450 79 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74  ytes. */.  sqlit
21460 65 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74  e3_stmt **ppStmt
21470 2c 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65  ,  /* OUT: State
21480 6d 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20  ment handle */. 
21490 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 2a 70 7a   const char **pz
214a0 54 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a  Tail     /* OUT:
214b0 20 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73   Pointer to unus
214c0 65 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53  ed portion of zS
214d0 71 6c 20 2a 2f 0a 29 3b 0a 69 6e 74 20 73 71 6c  ql */.);.int sql
214e0 69 74 65 33 5f 70 72 65 70 61 72 65 31 36 28 0a  ite3_prepare16(.
214f0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
21500 20 20 20 20 20 20 20 20 20 20 2f 2a 20 44 61 74            /* Dat
21510 61 62 61 73 65 20 68 61 6e 64 6c 65 20 2a 2f 0a  abase handle */.
21520 20 20 63 6f 6e 73 74 20 76 6f 69 64 20 2a 7a 53    const void *zS
21530 71 6c 2c 20 20 20 20 20 20 20 2f 2a 20 53 51 4c  ql,       /* SQL
21540 20 73 74 61 74 65 6d 65 6e 74 2c 20 55 54 46 2d   statement, UTF-
21550 31 36 20 65 6e 63 6f 64 65 64 20 2a 2f 0a 20 20  16 encoded */.  
21560 69 6e 74 20 6e 42 79 74 65 2c 20 20 20 20 20 20  int nByte,      
21570 20 20 20 20 20 20 20 20 2f 2a 20 4d 61 78 69 6d          /* Maxim
21580 75 6d 20 6c 65 6e 67 74 68 20 6f 66 20 7a 53 71  um length of zSq
21590 6c 20 69 6e 20 62 79 74 65 73 2e 20 2a 2f 0a 20  l in bytes. */. 
215a0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 2a   sqlite3_stmt **
215b0 70 70 53 74 6d 74 2c 20 20 2f 2a 20 4f 55 54 3a  ppStmt,  /* OUT:
215c0 20 53 74 61 74 65 6d 65 6e 74 20 68 61 6e 64 6c   Statement handl
215d0 65 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 76 6f 69  e */.  const voi
215e0 64 20 2a 2a 70 7a 54 61 69 6c 20 20 20 20 20 2f  d **pzTail     /
215f0 2a 20 4f 55 54 3a 20 50 6f 69 6e 74 65 72 20 74  * OUT: Pointer t
21600 6f 20 75 6e 75 73 65 64 20 70 6f 72 74 69 6f 6e  o unused portion
21610 20 6f 66 20 7a 53 71 6c 20 2a 2f 0a 29 3b 0a 69   of zSql */.);.i
21620 6e 74 20 73 71 6c 69 74 65 33 5f 70 72 65 70 61  nt sqlite3_prepa
21630 72 65 31 36 5f 76 32 28 0a 20 20 73 71 6c 69 74  re16_v2(.  sqlit
21640 65 33 20 2a 64 62 2c 20 20 20 20 20 20 20 20 20  e3 *db,         
21650 20 20 20 2f 2a 20 44 61 74 61 62 61 73 65 20 68     /* Database h
21660 61 6e 64 6c 65 20 2a 2f 0a 20 20 63 6f 6e 73 74  andle */.  const
21670 20 76 6f 69 64 20 2a 7a 53 71 6c 2c 20 20 20 20   void *zSql,    
21680 20 20 20 2f 2a 20 53 51 4c 20 73 74 61 74 65 6d     /* SQL statem
21690 65 6e 74 2c 20 55 54 46 2d 31 36 20 65 6e 63 6f  ent, UTF-16 enco
216a0 64 65 64 20 2a 2f 0a 20 20 69 6e 74 20 6e 42 79  ded */.  int nBy
216b0 74 65 2c 20 20 20 20 20 20 20 20 20 20 20 20 20  te,             
216c0 20 2f 2a 20 4d 61 78 69 6d 75 6d 20 6c 65 6e 67   /* Maximum leng
216d0 74 68 20 6f 66 20 7a 53 71 6c 20 69 6e 20 62 79  th of zSql in by
216e0 74 65 73 2e 20 2a 2f 0a 20 20 73 71 6c 69 74 65  tes. */.  sqlite
216f0 33 5f 73 74 6d 74 20 2a 2a 70 70 53 74 6d 74 2c  3_stmt **ppStmt,
21700 20 20 2f 2a 20 4f 55 54 3a 20 53 74 61 74 65 6d    /* OUT: Statem
21710 65 6e 74 20 68 61 6e 64 6c 65 20 2a 2f 0a 20 20  ent handle */.  
21720 63 6f 6e 73 74 20 76 6f 69 64 20 2a 2a 70 7a 54  const void **pzT
21730 61 69 6c 20 20 20 20 20 2f 2a 20 4f 55 54 3a 20  ail     /* OUT: 
21740 50 6f 69 6e 74 65 72 20 74 6f 20 75 6e 75 73 65  Pointer to unuse
21750 64 20 70 6f 72 74 69 6f 6e 20 6f 66 20 7a 53 71  d portion of zSq
21760 6c 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  l */.);../*.** C
21770 41 50 49 33 52 45 46 3a 20 52 65 74 72 69 65 76  API3REF: Retriev
21780 69 6e 67 20 53 74 61 74 65 6d 65 6e 74 20 53 51  ing Statement SQ
21790 4c 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e  L.**.** ^This in
217a0 74 65 72 66 61 63 65 20 63 61 6e 20 62 65 20 75  terface can be u
217b0 73 65 64 20 74 6f 20 72 65 74 72 69 65 76 65 20  sed to retrieve 
217c0 61 20 73 61 76 65 64 20 63 6f 70 79 20 6f 66 20  a saved copy of 
217d0 74 68 65 20 6f 72 69 67 69 6e 61 6c 0a 2a 2a 20  the original.** 
217e0 53 51 4c 20 74 65 78 74 20 75 73 65 64 20 74 6f  SQL text used to
217f0 20 63 72 65 61 74 65 20 61 20 5b 70 72 65 70 61   create a [prepa
21800 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 69  red statement] i
21810 66 20 74 68 61 74 20 73 74 61 74 65 6d 65 6e 74  f that statement
21820 20 77 61 73 0a 2a 2a 20 63 6f 6d 70 69 6c 65 64   was.** compiled
21830 20 75 73 69 6e 67 20 65 69 74 68 65 72 20 5b 73   using either [s
21840 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
21850 32 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33  2()] or [sqlite3
21860 5f 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d  _prepare16_v2()]
21870 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
21880 2a 73 71 6c 69 74 65 33 5f 73 71 6c 28 73 71 6c  *sqlite3_sql(sql
21890 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74  ite3_stmt *pStmt
218a0 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
218b0 45 46 3a 20 44 65 74 65 72 6d 69 6e 65 20 49 66  EF: Determine If
218c0 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
218d0 74 20 57 72 69 74 65 73 20 54 68 65 20 44 61 74  t Writes The Dat
218e0 61 62 61 73 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  abase.**.** ^The
218f0 20 73 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65   sqlite3_stmt_re
21900 61 64 6f 6e 6c 79 28 58 29 20 69 6e 74 65 72 66  adonly(X) interf
21910 61 63 65 20 72 65 74 75 72 6e 73 20 74 72 75 65  ace returns true
21920 20 28 6e 6f 6e 2d 7a 65 72 6f 29 20 69 66 0a 2a   (non-zero) if.*
21930 2a 20 61 6e 64 20 6f 6e 6c 79 20 69 66 20 74 68  * and only if th
21940 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
21950 65 6d 65 6e 74 5d 20 58 20 6d 61 6b 65 73 20 6e  ement] X makes n
21960 6f 20 64 69 72 65 63 74 20 63 68 61 6e 67 65 73  o direct changes
21970 20 74 6f 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65   to.** the conte
21980 6e 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61  nt of the databa
21990 73 65 20 66 69 6c 65 2e 0a 2a 2a 0a 2a 2a 20 4e  se file..**.** N
219a0 6f 74 65 20 74 68 61 74 20 5b 61 70 70 6c 69 63  ote that [applic
219b0 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 53 51  ation-defined SQ
219c0 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20 6f 72 0a  L functions] or.
219d0 2a 2a 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c  ** [virtual tabl
219e0 65 73 5d 20 6d 69 67 68 74 20 63 68 61 6e 67 65  es] might change
219f0 20 74 68 65 20 64 61 74 61 62 61 73 65 20 69 6e   the database in
21a00 64 69 72 65 63 74 6c 79 20 61 73 20 61 20 73 69  directly as a si
21a10 64 65 20 65 66 66 65 63 74 2e 20 20 0a 2a 2a 20  de effect.  .** 
21a20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20 69  ^(For example, i
21a30 66 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e  f an application
21a40 20 64 65 66 69 6e 65 73 20 61 20 66 75 6e 63 74   defines a funct
21a50 69 6f 6e 20 22 65 76 61 6c 28 29 22 20 74 68 61  ion "eval()" tha
21a60 74 20 0a 2a 2a 20 63 61 6c 6c 73 20 5b 73 71 6c  t .** calls [sql
21a70 69 74 65 33 5f 65 78 65 63 28 29 5d 2c 20 74 68  ite3_exec()], th
21a80 65 6e 20 74 68 65 20 66 6f 6c 6c 6f 77 69 6e 67  en the following
21a90 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20 77   SQL statement w
21aa0 6f 75 6c 64 0a 2a 2a 20 63 68 61 6e 67 65 20 74  ould.** change t
21ab0 68 65 20 64 61 74 61 62 61 73 65 20 66 69 6c 65  he database file
21ac0 20 74 68 72 6f 75 67 68 20 73 69 64 65 2d 65 66   through side-ef
21ad0 66 65 63 74 73 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c  fects:.**.** <bl
21ae0 6f 63 6b 71 75 6f 74 65 3e 3c 70 72 65 3e 0a 2a  ockquote><pre>.*
21af0 2a 20 20 20 20 53 45 4c 45 43 54 20 65 76 61 6c  *    SELECT eval
21b00 28 27 44 45 4c 45 54 45 20 46 52 4f 4d 20 74 31  ('DELETE FROM t1
21b10 27 29 20 46 52 4f 4d 20 74 32 3b 0a 2a 2a 20 3c  ') FROM t2;.** <
21b20 2f 70 72 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74  /pre></blockquot
21b30 65 3e 0a 2a 2a 0a 2a 2a 20 42 75 74 20 62 65 63  e>.**.** But bec
21b40 61 75 73 65 20 74 68 65 20 5b 53 45 4c 45 43 54  ause the [SELECT
21b50 5d 20 73 74 61 74 65 6d 65 6e 74 20 64 6f 65 73  ] statement does
21b60 20 6e 6f 74 20 63 68 61 6e 67 65 20 74 68 65 20   not change the 
21b70 64 61 74 61 62 61 73 65 20 66 69 6c 65 0a 2a 2a  database file.**
21b80 20 64 69 72 65 63 74 6c 79 2c 20 73 71 6c 69 74   directly, sqlit
21b90 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
21ba0 28 29 20 77 6f 75 6c 64 20 73 74 69 6c 6c 20 72  () would still r
21bb0 65 74 75 72 6e 20 74 72 75 65 2e 29 5e 0a 2a 2a  eturn true.)^.**
21bc0 0a 2a 2a 20 5e 54 72 61 6e 73 61 63 74 69 6f 6e  .** ^Transaction
21bd0 20 63 6f 6e 74 72 6f 6c 20 73 74 61 74 65 6d 65   control stateme
21be0 6e 74 73 20 73 75 63 68 20 61 73 20 5b 42 45 47  nts such as [BEG
21bf0 49 4e 5d 2c 20 5b 43 4f 4d 4d 49 54 5d 2c 20 5b  IN], [COMMIT], [
21c00 52 4f 4c 4c 42 41 43 4b 5d 2c 0a 2a 2a 20 5b 53  ROLLBACK],.** [S
21c10 41 56 45 50 4f 49 4e 54 5d 2c 20 61 6e 64 20 5b  AVEPOINT], and [
21c20 52 45 4c 45 41 53 45 5d 20 63 61 75 73 65 20 73  RELEASE] cause s
21c30 71 6c 69 74 65 33 5f 73 74 6d 74 5f 72 65 61 64  qlite3_stmt_read
21c40 6f 6e 6c 79 28 29 20 74 6f 20 72 65 74 75 72 6e  only() to return
21c50 20 74 72 75 65 2c 0a 2a 2a 20 73 69 6e 63 65 20   true,.** since 
21c60 74 68 65 20 73 74 61 74 65 6d 65 6e 74 73 20 74  the statements t
21c70 68 65 6d 73 65 6c 76 65 73 20 64 6f 20 6e 6f 74  hemselves do not
21c80 20 61 63 74 75 61 6c 6c 79 20 6d 6f 64 69 66 79   actually modify
21c90 20 74 68 65 20 64 61 74 61 62 61 73 65 20 62 75   the database bu
21ca0 74 0a 2a 2a 20 72 61 74 68 65 72 20 74 68 65 79  t.** rather they
21cb0 20 63 6f 6e 74 72 6f 6c 20 74 68 65 20 74 69 6d   control the tim
21cc0 69 6e 67 20 6f 66 20 77 68 65 6e 20 6f 74 68 65  ing of when othe
21cd0 72 20 73 74 61 74 65 6d 65 6e 74 73 20 6d 6f 64  r statements mod
21ce0 69 66 79 20 74 68 65 20 0a 2a 2a 20 64 61 74 61  ify the .** data
21cf0 62 61 73 65 2e 20 20 5e 54 68 65 20 5b 41 54 54  base.  ^The [ATT
21d00 41 43 48 5d 20 61 6e 64 20 5b 44 45 54 41 43 48  ACH] and [DETACH
21d10 5d 20 73 74 61 74 65 6d 65 6e 74 73 20 61 6c 73  ] statements als
21d20 6f 20 63 61 75 73 65 0a 2a 2a 20 73 71 6c 69 74  o cause.** sqlit
21d30 65 33 5f 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79  e3_stmt_readonly
21d40 28 29 20 74 6f 20 72 65 74 75 72 6e 20 74 72 75  () to return tru
21d50 65 20 73 69 6e 63 65 2c 20 77 68 69 6c 65 20 74  e since, while t
21d60 68 6f 73 65 20 73 74 61 74 65 6d 65 6e 74 73 0a  hose statements.
21d70 2a 2a 20 63 68 61 6e 67 65 20 74 68 65 20 63 6f  ** change the co
21d80 6e 66 69 67 75 72 61 74 69 6f 6e 20 6f 66 20 61  nfiguration of a
21d90 20 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63   database connec
21da0 74 69 6f 6e 2c 20 74 68 65 79 20 64 6f 20 6e 6f  tion, they do no
21db0 74 20 6d 61 6b 65 20 0a 2a 2a 20 63 68 61 6e 67  t make .** chang
21dc0 65 73 20 74 6f 20 74 68 65 20 63 6f 6e 74 65 6e  es to the conten
21dd0 74 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73  t of the databas
21de0 65 20 66 69 6c 65 73 20 6f 6e 20 64 69 73 6b 2e  e files on disk.
21df0 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
21e00 73 74 6d 74 5f 72 65 61 64 6f 6e 6c 79 28 73 71  stmt_readonly(sq
21e10 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
21e20 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
21e30 52 45 46 3a 20 44 79 6e 61 6d 69 63 61 6c 6c 79  REF: Dynamically
21e40 20 54 79 70 65 64 20 56 61 6c 75 65 20 4f 62 6a   Typed Value Obj
21e50 65 63 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a  ect.** KEYWORDS:
21e60 20 7b 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69   {protected sqli
21e70 74 65 33 5f 76 61 6c 75 65 7d 20 7b 75 6e 70 72  te3_value} {unpr
21e80 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33 5f  otected sqlite3_
21e90 76 61 6c 75 65 7d 0a 2a 2a 0a 2a 2a 20 53 51 4c  value}.**.** SQL
21ea0 69 74 65 20 75 73 65 73 20 74 68 65 20 73 71 6c  ite uses the sql
21eb0 69 74 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63  ite3_value objec
21ec0 74 20 74 6f 20 72 65 70 72 65 73 65 6e 74 20 61  t to represent a
21ed0 6c 6c 20 76 61 6c 75 65 73 0a 2a 2a 20 74 68 61  ll values.** tha
21ee0 74 20 63 61 6e 20 62 65 20 73 74 6f 72 65 64 20  t can be stored 
21ef0 69 6e 20 61 20 64 61 74 61 62 61 73 65 20 74 61  in a database ta
21f00 62 6c 65 2e 20 53 51 4c 69 74 65 20 75 73 65 73  ble. SQLite uses
21f10 20 64 79 6e 61 6d 69 63 20 74 79 70 69 6e 67 0a   dynamic typing.
21f20 2a 2a 20 66 6f 72 20 74 68 65 20 76 61 6c 75 65  ** for the value
21f30 73 20 69 74 20 73 74 6f 72 65 73 2e 20 20 5e 56  s it stores.  ^V
21f40 61 6c 75 65 73 20 73 74 6f 72 65 64 20 69 6e 20  alues stored in 
21f50 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 6f 62  sqlite3_value ob
21f60 6a 65 63 74 73 0a 2a 2a 20 63 61 6e 20 62 65 20  jects.** can be 
21f70 69 6e 74 65 67 65 72 73 2c 20 66 6c 6f 61 74 69  integers, floati
21f80 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75 65 73 2c  ng point values,
21f90 20 73 74 72 69 6e 67 73 2c 20 42 4c 4f 42 73 2c   strings, BLOBs,
21fa0 20 6f 72 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20   or NULL..**.** 
21fb0 41 6e 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  An sqlite3_value
21fc0 20 6f 62 6a 65 63 74 20 6d 61 79 20 62 65 20 65   object may be e
21fd0 69 74 68 65 72 20 22 70 72 6f 74 65 63 74 65 64  ither "protected
21fe0 22 20 6f 72 20 22 75 6e 70 72 6f 74 65 63 74 65  " or "unprotecte
21ff0 64 22 2e 0a 2a 2a 20 53 6f 6d 65 20 69 6e 74 65  d"..** Some inte
22000 72 66 61 63 65 73 20 72 65 71 75 69 72 65 20 61  rfaces require a
22010 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
22020 65 33 5f 76 61 6c 75 65 2e 20 20 4f 74 68 65 72  e3_value.  Other
22030 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20 77   interfaces.** w
22040 69 6c 6c 20 61 63 63 65 70 74 20 65 69 74 68 65  ill accept eithe
22050 72 20 61 20 70 72 6f 74 65 63 74 65 64 20 6f 72  r a protected or
22060 20 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 20   an unprotected 
22070 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2e 0a 2a  sqlite3_value..*
22080 2a 20 45 76 65 72 79 20 69 6e 74 65 72 66 61 63  * Every interfac
22090 65 20 74 68 61 74 20 61 63 63 65 70 74 73 20 73  e that accepts s
220a0 71 6c 69 74 65 33 5f 76 61 6c 75 65 20 61 72 67  qlite3_value arg
220b0 75 6d 65 6e 74 73 20 73 70 65 63 69 66 69 65 73  uments specifies
220c0 0a 2a 2a 20 77 68 65 74 68 65 72 20 6f 72 20 6e  .** whether or n
220d0 6f 74 20 69 74 20 72 65 71 75 69 72 65 73 20 61  ot it requires a
220e0 20 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74   protected sqlit
220f0 65 33 5f 76 61 6c 75 65 2e 0a 2a 2a 0a 2a 2a 20  e3_value..**.** 
22100 54 68 65 20 74 65 72 6d 73 20 22 70 72 6f 74 65  The terms "prote
22110 63 74 65 64 22 20 61 6e 64 20 22 75 6e 70 72 6f  cted" and "unpro
22120 74 65 63 74 65 64 22 20 72 65 66 65 72 20 74 6f  tected" refer to
22130 20 77 68 65 74 68 65 72 20 6f 72 20 6e 6f 74 0a   whether or not.
22140 2a 2a 20 61 20 6d 75 74 65 78 20 69 73 20 68 65  ** a mutex is he
22150 6c 64 2e 20 20 41 6e 20 69 6e 74 65 72 6e 61 6c  ld.  An internal
22160 20 6d 75 74 65 78 20 69 73 20 68 65 6c 64 20 66   mutex is held f
22170 6f 72 20 61 20 70 72 6f 74 65 63 74 65 64 0a 2a  or a protected.*
22180 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
22190 6f 62 6a 65 63 74 20 62 75 74 20 6e 6f 20 6d 75  object but no mu
221a0 74 65 78 20 69 73 20 68 65 6c 64 20 66 6f 72 20  tex is held for 
221b0 61 6e 20 75 6e 70 72 6f 74 65 63 74 65 64 0a 2a  an unprotected.*
221c0 2a 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 20  * sqlite3_value 
221d0 6f 62 6a 65 63 74 2e 20 20 49 66 20 53 51 4c 69  object.  If SQLi
221e0 74 65 20 69 73 20 63 6f 6d 70 69 6c 65 64 20 74  te is compiled t
221f0 6f 20 62 65 20 73 69 6e 67 6c 65 2d 74 68 72 65  o be single-thre
22200 61 64 65 64 0a 2a 2a 20 28 77 69 74 68 20 5b 53  aded.** (with [S
22210 51 4c 49 54 45 5f 54 48 52 45 41 44 53 41 46 45  QLITE_THREADSAFE
22220 3d 30 5d 20 61 6e 64 20 77 69 74 68 20 5b 73 71  =0] and with [sq
22230 6c 69 74 65 33 5f 74 68 72 65 61 64 73 61 66 65  lite3_threadsafe
22240 28 29 5d 20 72 65 74 75 72 6e 69 6e 67 20 30 29  ()] returning 0)
22250 0a 2a 2a 20 6f 72 20 69 66 20 53 51 4c 69 74 65  .** or if SQLite
22260 20 69 73 20 72 75 6e 20 69 6e 20 6f 6e 65 20 6f   is run in one o
22270 66 20 72 65 64 75 63 65 64 20 6d 75 74 65 78 20  f reduced mutex 
22280 6d 6f 64 65 73 20 0a 2a 2a 20 5b 53 51 4c 49 54  modes .** [SQLIT
22290 45 5f 43 4f 4e 46 49 47 5f 53 49 4e 47 4c 45 54  E_CONFIG_SINGLET
222a0 48 52 45 41 44 5d 20 6f 72 20 5b 53 51 4c 49 54  HREAD] or [SQLIT
222b0 45 5f 43 4f 4e 46 49 47 5f 4d 55 4c 54 49 54 48  E_CONFIG_MULTITH
222c0 52 45 41 44 5d 0a 2a 2a 20 74 68 65 6e 20 74 68  READ].** then th
222d0 65 72 65 20 69 73 20 6e 6f 20 64 69 73 74 69 6e  ere is no distin
222e0 63 74 69 6f 6e 20 62 65 74 77 65 65 6e 20 70 72  ction between pr
222f0 6f 74 65 63 74 65 64 20 61 6e 64 20 75 6e 70 72  otected and unpr
22300 6f 74 65 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74  otected.** sqlit
22310 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73  e3_value objects
22320 20 61 6e 64 20 74 68 65 79 20 63 61 6e 20 62 65   and they can be
22330 20 75 73 65 64 20 69 6e 74 65 72 63 68 61 6e 67   used interchang
22340 65 61 62 6c 79 2e 20 20 48 6f 77 65 76 65 72 2c  eably.  However,
22350 0a 2a 2a 20 66 6f 72 20 6d 61 78 69 6d 75 6d 20  .** for maximum 
22360 63 6f 64 65 20 70 6f 72 74 61 62 69 6c 69 74 79  code portability
22370 20 69 74 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64   it is recommend
22380 65 64 20 74 68 61 74 20 61 70 70 6c 69 63 61 74  ed that applicat
22390 69 6f 6e 73 0a 2a 2a 20 73 74 69 6c 6c 20 6d 61  ions.** still ma
223a0 6b 65 20 74 68 65 20 64 69 73 74 69 6e 63 74 69  ke the distincti
223b0 6f 6e 20 62 65 74 77 65 65 6e 20 70 72 6f 74 65  on between prote
223c0 63 74 65 64 20 61 6e 64 20 75 6e 70 72 6f 74 65  cted and unprote
223d0 63 74 65 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  cted.** sqlite3_
223e0 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20 65 76  value objects ev
223f0 65 6e 20 77 68 65 6e 20 6e 6f 74 20 73 74 72 69  en when not stri
22400 63 74 6c 79 20 72 65 71 75 69 72 65 64 2e 0a 2a  ctly required..*
22410 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
22420 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 73 20  3_value objects 
22430 74 68 61 74 20 61 72 65 20 70 61 73 73 65 64 20  that are passed 
22440 61 73 20 70 61 72 61 6d 65 74 65 72 73 20 69 6e  as parameters in
22450 74 6f 20 74 68 65 0a 2a 2a 20 69 6d 70 6c 65 6d  to the.** implem
22460 65 6e 74 61 74 69 6f 6e 20 6f 66 20 5b 61 70 70  entation of [app
22470 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
22480 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 5d 20   SQL functions] 
22490 61 72 65 20 70 72 6f 74 65 63 74 65 64 2e 0a 2a  are protected..*
224a0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 76  * ^The sqlite3_v
224b0 61 6c 75 65 20 6f 62 6a 65 63 74 20 72 65 74 75  alue object retu
224c0 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
224d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65  te3_column_value
224e0 28 29 5d 20 69 73 20 75 6e 70 72 6f 74 65 63 74  ()] is unprotect
224f0 65 64 2e 0a 2a 2a 20 55 6e 70 72 6f 74 65 63 74  ed..** Unprotect
22500 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  ed sqlite3_value
22510 20 6f 62 6a 65 63 74 73 20 6d 61 79 20 6f 6e 6c   objects may onl
22520 79 20 62 65 20 75 73 65 64 20 77 69 74 68 0a 2a  y be used with.*
22530 2a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  * [sqlite3_resul
22540 74 5f 76 61 6c 75 65 28 29 5d 20 61 6e 64 20 5b  t_value()] and [
22550 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 76 61 6c  sqlite3_bind_val
22560 75 65 28 29 5d 2e 0a 2a 2a 20 54 68 65 20 5b 73  ue()]..** The [s
22570 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c 6f  qlite3_value_blo
22580 62 20 7c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  b | sqlite3_valu
22590 65 5f 74 79 70 65 28 29 5d 20 66 61 6d 69 6c 79  e_type()] family
225a0 20 6f 66 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65   of.** interface
225b0 73 20 72 65 71 75 69 72 65 20 70 72 6f 74 65 63  s require protec
225c0 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
225d0 65 20 6f 62 6a 65 63 74 73 2e 0a 2a 2f 0a 74 79  e objects..*/.ty
225e0 70 65 64 65 66 20 73 74 72 75 63 74 20 4d 65 6d  pedef struct Mem
225f0 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 3b 0a   sqlite3_value;.
22600 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
22610 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20 43 6f   SQL Function Co
22620 6e 74 65 78 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ntext Object.**.
22630 2a 2a 20 54 68 65 20 63 6f 6e 74 65 78 74 20 69  ** The context i
22640 6e 20 77 68 69 63 68 20 61 6e 20 53 51 4c 20 66  n which an SQL f
22650 75 6e 63 74 69 6f 6e 20 65 78 65 63 75 74 65 73  unction executes
22660 20 69 73 20 73 74 6f 72 65 64 20 69 6e 20 61 6e   is stored in an
22670 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74  .** sqlite3_cont
22680 65 78 74 20 6f 62 6a 65 63 74 2e 20 20 5e 41 20  ext object.  ^A 
22690 70 6f 69 6e 74 65 72 20 74 6f 20 61 6e 20 73 71  pointer to an sq
226a0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20 6f 62  lite3_context ob
226b0 6a 65 63 74 0a 2a 2a 20 69 73 20 61 6c 77 61 79  ject.** is alway
226c0 73 20 66 69 72 73 74 20 70 61 72 61 6d 65 74 65  s first paramete
226d0 72 20 74 6f 20 5b 61 70 70 6c 69 63 61 74 69 6f  r to [applicatio
226e0 6e 2d 64 65 66 69 6e 65 64 20 53 51 4c 20 66 75  n-defined SQL fu
226f0 6e 63 74 69 6f 6e 73 5d 2e 0a 2a 2a 20 54 68 65  nctions]..** The
22700 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66   application-def
22710 69 6e 65 64 20 53 51 4c 20 66 75 6e 63 74 69 6f  ined SQL functio
22720 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
22730 20 77 69 6c 6c 20 70 61 73 73 20 74 68 69 73 0a   will pass this.
22740 2a 2a 20 70 6f 69 6e 74 65 72 20 74 68 72 6f 75  ** pointer throu
22750 67 68 20 69 6e 74 6f 20 63 61 6c 6c 73 20 74 6f  gh into calls to
22760 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74   [sqlite3_result
22770 5f 69 6e 74 20 7c 20 73 71 6c 69 74 65 33 5f 72  _int | sqlite3_r
22780 65 73 75 6c 74 28 29 5d 2c 0a 2a 2a 20 5b 73 71  esult()],.** [sq
22790 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
227a0 63 6f 6e 74 65 78 74 28 29 5d 2c 20 5b 73 71 6c  context()], [sql
227b0 69 74 65 33 5f 75 73 65 72 5f 64 61 74 61 28 29  ite3_user_data()
227c0 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  ],.** [sqlite3_c
227d0 6f 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65  ontext_db_handle
227e0 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 67 65  ()], [sqlite3_ge
227f0 74 5f 61 75 78 64 61 74 61 28 29 5d 2c 0a 2a 2a  t_auxdata()],.**
22800 20 61 6e 64 2f 6f 72 20 5b 73 71 6c 69 74 65 33   and/or [sqlite3
22810 5f 73 65 74 5f 61 75 78 64 61 74 61 28 29 5d 2e  _set_auxdata()].
22820 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74 72 75  .*/.typedef stru
22830 63 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ct sqlite3_conte
22840 78 74 20 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  xt sqlite3_conte
22850 78 74 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  xt;../*.** CAPI3
22860 52 45 46 3a 20 42 69 6e 64 69 6e 67 20 56 61 6c  REF: Binding Val
22870 75 65 73 20 54 6f 20 50 72 65 70 61 72 65 64 20  ues To Prepared 
22880 53 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 4b 45  Statements.** KE
22890 59 57 4f 52 44 53 3a 20 7b 68 6f 73 74 20 70 61  YWORDS: {host pa
228a0 72 61 6d 65 74 65 72 7d 20 7b 68 6f 73 74 20 70  rameter} {host p
228b0 61 72 61 6d 65 74 65 72 73 7d 20 7b 68 6f 73 74  arameters} {host
228c0 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d 65 7d   parameter name}
228d0 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 53  .** KEYWORDS: {S
228e0 51 4c 20 70 61 72 61 6d 65 74 65 72 7d 20 7b 53  QL parameter} {S
228f0 51 4c 20 70 61 72 61 6d 65 74 65 72 73 7d 20 7b  QL parameters} {
22900 70 61 72 61 6d 65 74 65 72 20 62 69 6e 64 69 6e  parameter bindin
22910 67 7d 0a 2a 2a 0a 2a 2a 20 5e 28 49 6e 20 74 68  g}.**.** ^(In th
22920 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e 74 20  e SQL statement 
22930 74 65 78 74 20 69 6e 70 75 74 20 74 6f 20 5b 73  text input to [s
22940 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76  qlite3_prepare_v
22950 32 28 29 5d 20 61 6e 64 20 69 74 73 20 76 61 72  2()] and its var
22960 69 61 6e 74 73 2c 0a 2a 2a 20 6c 69 74 65 72 61  iants,.** litera
22970 6c 73 20 6d 61 79 20 62 65 20 72 65 70 6c 61 63  ls may be replac
22980 65 64 20 62 79 20 61 20 5b 70 61 72 61 6d 65 74  ed by a [paramet
22990 65 72 5d 20 74 68 61 74 20 6d 61 74 63 68 65 73  er] that matches
229a0 20 6f 6e 65 20 6f 66 20 66 6f 6c 6c 6f 77 69 6e   one of followin
229b0 67 0a 2a 2a 20 74 65 6d 70 6c 61 74 65 73 3a 0a  g.** templates:.
229c0 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c  **.** <ul>.** <l
229d0 69 3e 20 20 3f 0a 2a 2a 20 3c 6c 69 3e 20 20 3f  i>  ?.** <li>  ?
229e0 4e 4e 4e 0a 2a 2a 20 3c 6c 69 3e 20 20 3a 56 56  NNN.** <li>  :VV
229f0 56 0a 2a 2a 20 3c 6c 69 3e 20 20 40 56 56 56 0a  V.** <li>  @VVV.
22a00 2a 2a 20 3c 6c 69 3e 20 20 24 56 56 56 0a 2a 2a  ** <li>  $VVV.**
22a10 20 3c 2f 75 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20   </ul>.**.** In 
22a20 74 68 65 20 74 65 6d 70 6c 61 74 65 73 20 61 62  the templates ab
22a30 6f 76 65 2c 20 4e 4e 4e 20 72 65 70 72 65 73 65  ove, NNN represe
22a40 6e 74 73 20 61 6e 20 69 6e 74 65 67 65 72 20 6c  nts an integer l
22a50 69 74 65 72 61 6c 2c 0a 2a 2a 20 61 6e 64 20 56  iteral,.** and V
22a60 56 56 20 72 65 70 72 65 73 65 6e 74 73 20 61 6e  VV represents an
22a70 20 61 6c 70 68 61 6e 75 6d 65 72 69 63 20 69 64   alphanumeric id
22a80 65 6e 74 69 66 69 65 72 2e 29 5e 20 20 5e 54 68  entifier.)^  ^Th
22a90 65 20 76 61 6c 75 65 73 20 6f 66 20 74 68 65 73  e values of thes
22aa0 65 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73 20  e.** parameters 
22ab0 28 61 6c 73 6f 20 63 61 6c 6c 65 64 20 22 68 6f  (also called "ho
22ac0 73 74 20 70 61 72 61 6d 65 74 65 72 20 6e 61 6d  st parameter nam
22ad0 65 73 22 20 6f 72 20 22 53 51 4c 20 70 61 72 61  es" or "SQL para
22ae0 6d 65 74 65 72 73 22 29 0a 2a 2a 20 63 61 6e 20  meters").** can 
22af0 62 65 20 73 65 74 20 75 73 69 6e 67 20 74 68 65  be set using the
22b00 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28   sqlite3_bind_*(
22b10 29 20 72 6f 75 74 69 6e 65 73 20 64 65 66 69 6e  ) routines defin
22b20 65 64 20 68 65 72 65 2e 0a 2a 2a 0a 2a 2a 20 5e  ed here..**.** ^
22b30 54 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65  The first argume
22b40 6e 74 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65  nt to the sqlite
22b50 33 5f 62 69 6e 64 5f 2a 28 29 20 72 6f 75 74 69  3_bind_*() routi
22b60 6e 65 73 20 69 73 20 61 6c 77 61 79 73 0a 2a 2a  nes is always.**
22b70 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 74 68   a pointer to th
22b80 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 6d 74 5d  e [sqlite3_stmt]
22b90 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65 64   object returned
22ba0 20 66 72 6f 6d 0a 2a 2a 20 5b 73 71 6c 69 74 65   from.** [sqlite
22bb0 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20  3_prepare_v2()] 
22bc0 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73 2e  or its variants.
22bd0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 65 63 6f  .**.** ^The seco
22be0 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
22bf0 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20  he index of the 
22c00 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 74 6f  SQL parameter to
22c10 20 62 65 20 73 65 74 2e 0a 2a 2a 20 5e 54 68 65   be set..** ^The
22c20 20 6c 65 66 74 6d 6f 73 74 20 53 51 4c 20 70 61   leftmost SQL pa
22c30 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
22c40 6e 64 65 78 20 6f 66 20 31 2e 20 20 5e 57 68 65  ndex of 1.  ^Whe
22c50 6e 20 74 68 65 20 73 61 6d 65 20 6e 61 6d 65 64  n the same named
22c60 0a 2a 2a 20 53 51 4c 20 70 61 72 61 6d 65 74 65  .** SQL paramete
22c70 72 20 69 73 20 75 73 65 64 20 6d 6f 72 65 20 74  r is used more t
22c80 68 61 6e 20 6f 6e 63 65 2c 20 73 65 63 6f 6e 64  han once, second
22c90 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 0a   and subsequent.
22ca0 2a 2a 20 6f 63 63 75 72 72 65 6e 63 65 73 20 68  ** occurrences h
22cb0 61 76 65 20 74 68 65 20 73 61 6d 65 20 69 6e 64  ave the same ind
22cc0 65 78 20 61 73 20 74 68 65 20 66 69 72 73 74 20  ex as the first 
22cd0 6f 63 63 75 72 72 65 6e 63 65 2e 0a 2a 2a 20 5e  occurrence..** ^
22ce0 54 68 65 20 69 6e 64 65 78 20 66 6f 72 20 6e 61  The index for na
22cf0 6d 65 64 20 70 61 72 61 6d 65 74 65 72 73 20 63  med parameters c
22d00 61 6e 20 62 65 20 6c 6f 6f 6b 65 64 20 75 70 20  an be looked up 
22d10 75 73 69 6e 67 20 74 68 65 0a 2a 2a 20 5b 73 71  using the.** [sq
22d20 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d  lite3_bind_param
22d30 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 20 41 50  eter_index()] AP
22d40 49 20 69 66 20 64 65 73 69 72 65 64 2e 20 20 5e  I if desired.  ^
22d50 54 68 65 20 69 6e 64 65 78 0a 2a 2a 20 66 6f 72  The index.** for
22d60 20 22 3f 4e 4e 4e 22 20 70 61 72 61 6d 65 74 65   "?NNN" paramete
22d70 72 73 20 69 73 20 74 68 65 20 76 61 6c 75 65 20  rs is the value 
22d80 6f 66 20 4e 4e 4e 2e 0a 2a 2a 20 5e 54 68 65 20  of NNN..** ^The 
22d90 4e 4e 4e 20 76 61 6c 75 65 20 6d 75 73 74 20 62  NNN value must b
22da0 65 20 62 65 74 77 65 65 6e 20 31 20 61 6e 64 20  e between 1 and 
22db0 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 69 6d  the [sqlite3_lim
22dc0 69 74 28 29 5d 0a 2a 2a 20 70 61 72 61 6d 65 74  it()].** paramet
22dd0 65 72 20 5b 53 51 4c 49 54 45 5f 4c 49 4d 49 54  er [SQLITE_LIMIT
22de0 5f 56 41 52 49 41 42 4c 45 5f 4e 55 4d 42 45 52  _VARIABLE_NUMBER
22df0 5d 20 28 64 65 66 61 75 6c 74 20 76 61 6c 75 65  ] (default value
22e00 3a 20 39 39 39 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  : 999)..**.** ^T
22e10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
22e20 74 20 69 73 20 74 68 65 20 76 61 6c 75 65 20 74  t is the value t
22e30 6f 20 62 69 6e 64 20 74 6f 20 74 68 65 20 70 61  o bind to the pa
22e40 72 61 6d 65 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e  rameter..**.** ^
22e50 28 49 6e 20 74 68 6f 73 65 20 72 6f 75 74 69 6e  (In those routin
22e60 65 73 20 74 68 61 74 20 68 61 76 65 20 61 20 66  es that have a f
22e70 6f 75 72 74 68 20 61 72 67 75 6d 65 6e 74 2c 20  ourth argument, 
22e80 69 74 73 20 76 61 6c 75 65 20 69 73 20 74 68 65  its value is the
22e90 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  .** number of by
22ea0 74 65 73 20 69 6e 20 74 68 65 20 70 61 72 61 6d  tes in the param
22eb0 65 74 65 72 2e 20 20 54 6f 20 62 65 20 63 6c 65  eter.  To be cle
22ec0 61 72 3a 20 74 68 65 20 76 61 6c 75 65 20 69 73  ar: the value is
22ed0 20 74 68 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f   the.** number o
22ee0 66 20 3c 75 3e 62 79 74 65 73 3c 2f 75 3e 20 69  f <u>bytes</u> i
22ef0 6e 20 74 68 65 20 76 61 6c 75 65 2c 20 6e 6f 74  n the value, not
22f00 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
22f10 68 61 72 61 63 74 65 72 73 2e 29 5e 0a 2a 2a 20  haracters.)^.** 
22f20 5e 49 66 20 74 68 65 20 66 6f 75 72 74 68 20 70  ^If the fourth p
22f30 61 72 61 6d 65 74 65 72 20 69 73 20 6e 65 67 61  arameter is nega
22f40 74 69 76 65 2c 20 74 68 65 20 6c 65 6e 67 74 68  tive, the length
22f50 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67 20 69   of the string i
22f60 73 0a 2a 2a 20 74 68 65 20 6e 75 6d 62 65 72 20  s.** the number 
22f70 6f 66 20 62 79 74 65 73 20 75 70 20 74 6f 20 74  of bytes up to t
22f80 68 65 20 66 69 72 73 74 20 7a 65 72 6f 20 74 65  he first zero te
22f90 72 6d 69 6e 61 74 6f 72 2e 0a 2a 2a 0a 2a 2a 20  rminator..**.** 
22fa0 5e 54 68 65 20 66 69 66 74 68 20 61 72 67 75 6d  ^The fifth argum
22fb0 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f 62  ent to sqlite3_b
22fc0 69 6e 64 5f 62 6c 6f 62 28 29 2c 20 73 71 6c 69  ind_blob(), sqli
22fd0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 29 2c  te3_bind_text(),
22fe0 20 61 6e 64 0a 2a 2a 20 73 71 6c 69 74 65 33 5f   and.** sqlite3_
22ff0 62 69 6e 64 5f 74 65 78 74 31 36 28 29 20 69 73  bind_text16() is
23000 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 75 73   a destructor us
23010 65 64 20 74 6f 20 64 69 73 70 6f 73 65 20 6f 66  ed to dispose of
23020 20 74 68 65 20 42 4c 4f 42 20 6f 72 0a 2a 2a 20   the BLOB or.** 
23030 73 74 72 69 6e 67 20 61 66 74 65 72 20 53 51 4c  string after SQL
23040 69 74 65 20 68 61 73 20 66 69 6e 69 73 68 65 64  ite has finished
23050 20 77 69 74 68 20 69 74 2e 20 20 5e 54 68 65 20   with it.  ^The 
23060 64 65 73 74 72 75 63 74 6f 72 20 69 73 20 63 61  destructor is ca
23070 6c 6c 65 64 0a 2a 2a 20 74 6f 20 64 69 73 70 6f  lled.** to dispo
23080 73 65 20 6f 66 20 74 68 65 20 42 4c 4f 42 20 6f  se of the BLOB o
23090 72 20 73 74 72 69 6e 67 20 65 76 65 6e 20 69 66  r string even if
230a0 20 74 68 65 20 63 61 6c 6c 20 74 6f 20 73 71 6c   the call to sql
230b0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 28 29  ite3_bind_blob()
230c0 2c 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 62 69 6e  ,.** sqlite3_bin
230d0 64 5f 74 65 78 74 28 29 2c 20 6f 72 20 73 71 6c  d_text(), or sql
230e0 69 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36  ite3_bind_text16
230f0 28 29 20 66 61 69 6c 73 2e 20 20 0a 2a 2a 20 5e  () fails.  .** ^
23100 49 66 20 74 68 65 20 66 69 66 74 68 20 61 72 67  If the fifth arg
23110 75 6d 65 6e 74 20 69 73 0a 2a 2a 20 74 68 65 20  ument is.** the 
23120 73 70 65 63 69 61 6c 20 76 61 6c 75 65 20 5b 53  special value [S
23130 51 4c 49 54 45 5f 53 54 41 54 49 43 5d 2c 20 74  QLITE_STATIC], t
23140 68 65 6e 20 53 51 4c 69 74 65 20 61 73 73 75 6d  hen SQLite assum
23150 65 73 20 74 68 61 74 20 74 68 65 0a 2a 2a 20 69  es that the.** i
23160 6e 66 6f 72 6d 61 74 69 6f 6e 20 69 73 20 69 6e  nformation is in
23170 20 73 74 61 74 69 63 2c 20 75 6e 6d 61 6e 61 67   static, unmanag
23180 65 64 20 73 70 61 63 65 20 61 6e 64 20 64 6f 65  ed space and doe
23190 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62 65  s not need to be
231a0 20 66 72 65 65 64 2e 0a 2a 2a 20 5e 49 66 20 74   freed..** ^If t
231b0 68 65 20 66 69 66 74 68 20 61 72 67 75 6d 65 6e  he fifth argumen
231c0 74 20 68 61 73 20 74 68 65 20 76 61 6c 75 65 20  t has the value 
231d0 5b 53 51 4c 49 54 45 5f 54 52 41 4e 53 49 45 4e  [SQLITE_TRANSIEN
231e0 54 5d 2c 20 74 68 65 6e 0a 2a 2a 20 53 51 4c 69  T], then.** SQLi
231f0 74 65 20 6d 61 6b 65 73 20 69 74 73 20 6f 77 6e  te makes its own
23200 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
23210 20 74 68 65 20 64 61 74 61 20 69 6d 6d 65 64 69   the data immedi
23220 61 74 65 6c 79 2c 20 62 65 66 6f 72 65 0a 2a 2a  ately, before.**
23230 20 74 68 65 20 73 71 6c 69 74 65 33 5f 62 69 6e   the sqlite3_bin
23240 64 5f 2a 28 29 20 72 6f 75 74 69 6e 65 20 72 65  d_*() routine re
23250 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
23260 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 7a  e sqlite3_bind_z
23270 65 72 6f 62 6c 6f 62 28 29 20 72 6f 75 74 69 6e  eroblob() routin
23280 65 20 62 69 6e 64 73 20 61 20 42 4c 4f 42 20 6f  e binds a BLOB o
23290 66 20 6c 65 6e 67 74 68 20 4e 20 74 68 61 74 0a  f length N that.
232a0 2a 2a 20 69 73 20 66 69 6c 6c 65 64 20 77 69 74  ** is filled wit
232b0 68 20 7a 65 72 6f 65 73 2e 20 20 5e 41 20 7a 65  h zeroes.  ^A ze
232c0 72 6f 62 6c 6f 62 20 75 73 65 73 20 61 20 66 69  roblob uses a fi
232d0 78 65 64 20 61 6d 6f 75 6e 74 20 6f 66 20 6d 65  xed amount of me
232e0 6d 6f 72 79 0a 2a 2a 20 28 6a 75 73 74 20 61 6e  mory.** (just an
232f0 20 69 6e 74 65 67 65 72 20 74 6f 20 68 6f 6c 64   integer to hold
23300 20 69 74 73 20 73 69 7a 65 29 20 77 68 69 6c 65   its size) while
23310 20 69 74 20 69 73 20 62 65 69 6e 67 20 70 72 6f   it is being pro
23320 63 65 73 73 65 64 2e 0a 2a 2a 20 5a 65 72 6f 62  cessed..** Zerob
23330 6c 6f 62 73 20 61 72 65 20 69 6e 74 65 6e 64 65  lobs are intende
23340 64 20 74 6f 20 73 65 72 76 65 20 61 73 20 70 6c  d to serve as pl
23350 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20 42  aceholders for B
23360 4c 4f 42 73 20 77 68 6f 73 65 0a 2a 2a 20 63 6f  LOBs whose.** co
23370 6e 74 65 6e 74 20 69 73 20 6c 61 74 65 72 20 77  ntent is later w
23380 72 69 74 74 65 6e 20 75 73 69 6e 67 0a 2a 2a 20  ritten using.** 
23390 5b 73 71 6c 69 74 65 33 5f 62 6c 6f 62 5f 6f 70  [sqlite3_blob_op
233a0 65 6e 20 7c 20 69 6e 63 72 65 6d 65 6e 74 61 6c  en | incremental
233b0 20 42 4c 4f 42 20 49 2f 4f 5d 20 72 6f 75 74 69   BLOB I/O] routi
233c0 6e 65 73 2e 0a 2a 2a 20 5e 41 20 6e 65 67 61 74  nes..** ^A negat
233d0 69 76 65 20 76 61 6c 75 65 20 66 6f 72 20 74 68  ive value for th
233e0 65 20 7a 65 72 6f 62 6c 6f 62 20 72 65 73 75 6c  e zeroblob resul
233f0 74 73 20 69 6e 20 61 20 7a 65 72 6f 2d 6c 65 6e  ts in a zero-len
23400 67 74 68 20 42 4c 4f 42 2e 0a 2a 2a 0a 2a 2a 20  gth BLOB..**.** 
23410 5e 49 66 20 61 6e 79 20 6f 66 20 74 68 65 20 73  ^If any of the s
23420 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a 28 29 20  qlite3_bind_*() 
23430 72 6f 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c  routines are cal
23440 6c 65 64 20 77 69 74 68 20 61 20 4e 55 4c 4c 20  led with a NULL 
23450 70 6f 69 6e 74 65 72 0a 2a 2a 20 66 6f 72 20 74  pointer.** for t
23460 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
23470 74 65 6d 65 6e 74 5d 20 6f 72 20 77 69 74 68 20  tement] or with 
23480 61 20 70 72 65 70 61 72 65 64 20 73 74 61 74 65  a prepared state
23490 6d 65 6e 74 20 66 6f 72 20 77 68 69 63 68 0a 2a  ment for which.*
234a0 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  * [sqlite3_step(
234b0 29 5d 20 68 61 73 20 62 65 65 6e 20 63 61 6c 6c  )] has been call
234c0 65 64 20 6d 6f 72 65 20 72 65 63 65 6e 74 6c 79  ed more recently
234d0 20 74 68 61 6e 20 5b 73 71 6c 69 74 65 33 5f 72   than [sqlite3_r
234e0 65 73 65 74 28 29 5d 2c 0a 2a 2a 20 74 68 65 6e  eset()],.** then
234f0 20 74 68 65 20 63 61 6c 6c 20 77 69 6c 6c 20 72   the call will r
23500 65 74 75 72 6e 20 5b 53 51 4c 49 54 45 5f 4d 49  eturn [SQLITE_MI
23510 53 55 53 45 5d 2e 20 20 49 66 20 61 6e 79 20 73  SUSE].  If any s
23520 71 6c 69 74 65 33 5f 62 69 6e 64 5f 28 29 0a 2a  qlite3_bind_().*
23530 2a 20 72 6f 75 74 69 6e 65 20 69 73 20 70 61 73  * routine is pas
23540 73 65 64 20 61 20 5b 70 72 65 70 61 72 65 64 20  sed a [prepared 
23550 73 74 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20  statement] that 
23560 68 61 73 20 62 65 65 6e 20 66 69 6e 61 6c 69 7a  has been finaliz
23570 65 64 2c 20 74 68 65 0a 2a 2a 20 72 65 73 75 6c  ed, the.** resul
23580 74 20 69 73 20 75 6e 64 65 66 69 6e 65 64 20 61  t is undefined a
23590 6e 64 20 70 72 6f 62 61 62 6c 79 20 68 61 72 6d  nd probably harm
235a0 66 75 6c 2e 0a 2a 2a 0a 2a 2a 20 5e 42 69 6e 64  ful..**.** ^Bind
235b0 69 6e 67 73 20 61 72 65 20 6e 6f 74 20 63 6c 65  ings are not cle
235c0 61 72 65 64 20 62 79 20 74 68 65 20 5b 73 71 6c  ared by the [sql
235d0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 72 6f  ite3_reset()] ro
235e0 75 74 69 6e 65 2e 0a 2a 2a 20 5e 55 6e 62 6f 75  utine..** ^Unbou
235f0 6e 64 20 70 61 72 61 6d 65 74 65 72 73 20 61 72  nd parameters ar
23600 65 20 69 6e 74 65 72 70 72 65 74 65 64 20 61 73  e interpreted as
23610 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   NULL..**.** ^Th
23620 65 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 2a  e sqlite3_bind_*
23630 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e   routines return
23640 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20 6f 6e 20   [SQLITE_OK] on 
23650 73 75 63 63 65 73 73 20 6f 72 20 61 6e 0a 2a 2a  success or an.**
23660 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 20 69 66   [error code] if
23670 20 61 6e 79 74 68 69 6e 67 20 67 6f 65 73 20 77   anything goes w
23680 72 6f 6e 67 2e 0a 2a 2a 20 5e 5b 53 51 4c 49 54  rong..** ^[SQLIT
23690 45 5f 52 41 4e 47 45 5d 20 69 73 20 72 65 74 75  E_RANGE] is retu
236a0 72 6e 65 64 20 69 66 20 74 68 65 20 70 61 72 61  rned if the para
236b0 6d 65 74 65 72 0a 2a 2a 20 69 6e 64 65 78 20 69  meter.** index i
236c0 73 20 6f 75 74 20 6f 66 20 72 61 6e 67 65 2e 20  s out of range. 
236d0 20 5e 5b 53 51 4c 49 54 45 5f 4e 4f 4d 45 4d 5d   ^[SQLITE_NOMEM]
236e0 20 69 73 20 72 65 74 75 72 6e 65 64 20 69 66 20   is returned if 
236f0 6d 61 6c 6c 6f 63 28 29 20 66 61 69 6c 73 2e 0a  malloc() fails..
23700 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23710 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61  [sqlite3_bind_pa
23720 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d  rameter_count()]
23730 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69  ,.** [sqlite3_bi
23740 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e 61 6d  nd_parameter_nam
23750 65 28 29 5d 2c 20 61 6e 64 20 5b 73 71 6c 69 74  e()], and [sqlit
23760 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65  e3_bind_paramete
23770 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 69  r_index()]..*/.i
23780 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f  nt sqlite3_bind_
23790 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 73 74 6d  blob(sqlite3_stm
237a0 74 2a 2c 20 69 6e 74 2c 20 63 6f 6e 73 74 20 76  t*, int, const v
237b0 6f 69 64 2a 2c 20 69 6e 74 20 6e 2c 20 76 6f 69  oid*, int n, voi
237c0 64 28 2a 29 28 76 6f 69 64 2a 29 29 3b 0a 69 6e  d(*)(void*));.in
237d0 74 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 64  t sqlite3_bind_d
237e0 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 73 74  ouble(sqlite3_st
237f0 6d 74 2a 2c 20 69 6e 74 2c 20 64 6f 75 62 6c 65  mt*, int, double
23800 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62  );.int sqlite3_b
23810 69 6e 64 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f  ind_int(sqlite3_
23820 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 69 6e 74 29  stmt*, int, int)
23830 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69  ;.int sqlite3_bi
23840 6e 64 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  nd_int64(sqlite3
23850 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c 20 73 71 6c  _stmt*, int, sql
23860 69 74 65 33 5f 69 6e 74 36 34 29 3b 0a 69 6e 74  ite3_int64);.int
23870 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 6e 75   sqlite3_bind_nu
23880 6c 6c 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  ll(sqlite3_stmt*
23890 2c 20 69 6e 74 29 3b 0a 69 6e 74 20 73 71 6c 69  , int);.int sqli
238a0 74 65 33 5f 62 69 6e 64 5f 74 65 78 74 28 73 71  te3_bind_text(sq
238b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
238c0 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
238d0 6e 74 20 6e 2c 20 76 6f 69 64 28 2a 29 28 76 6f  nt n, void(*)(vo
238e0 69 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74  id*));.int sqlit
238f0 65 33 5f 62 69 6e 64 5f 74 65 78 74 31 36 28 73  e3_bind_text16(s
23900 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
23910 74 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20  t, const void*, 
23920 69 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69  int, void(*)(voi
23930 64 2a 29 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  d*));.int sqlite
23940 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 73 71 6c  3_bind_value(sql
23950 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 2c  ite3_stmt*, int,
23960 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 76   const sqlite3_v
23970 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
23980 74 65 33 5f 62 69 6e 64 5f 7a 65 72 6f 62 6c 6f  te3_bind_zeroblo
23990 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
239a0 20 69 6e 74 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f   int, int n);../
239b0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 4e  *.** CAPI3REF: N
239c0 75 6d 62 65 72 20 4f 66 20 53 51 4c 20 50 61 72  umber Of SQL Par
239d0 61 6d 65 74 65 72 73 0a 2a 2a 0a 2a 2a 20 5e 54  ameters.**.** ^T
239e0 68 69 73 20 72 6f 75 74 69 6e 65 20 63 61 6e 20  his routine can 
239f0 62 65 20 75 73 65 64 20 74 6f 20 66 69 6e 64 20  be used to find 
23a00 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 5b 53  the number of [S
23a10 51 4c 20 70 61 72 61 6d 65 74 65 72 73 5d 0a 2a  QL parameters].*
23a20 2a 20 69 6e 20 61 20 5b 70 72 65 70 61 72 65 64  * in a [prepared
23a30 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 53 51   statement].  SQ
23a40 4c 20 70 61 72 61 6d 65 74 65 72 73 20 61 72 65  L parameters are
23a50 20 74 6f 6b 65 6e 73 20 6f 66 20 74 68 65 0a 2a   tokens of the.*
23a60 2a 20 66 6f 72 6d 20 22 3f 22 2c 20 22 3f 4e 4e  * form "?", "?NN
23a70 4e 22 2c 20 22 3a 41 41 41 22 2c 20 22 24 41 41  N", ":AAA", "$AA
23a80 41 22 2c 20 6f 72 20 22 40 41 41 41 22 20 74 68  A", or "@AAA" th
23a90 61 74 20 73 65 72 76 65 20 61 73 0a 2a 2a 20 70  at serve as.** p
23aa0 6c 61 63 65 68 6f 6c 64 65 72 73 20 66 6f 72 20  laceholders for 
23ab0 76 61 6c 75 65 73 20 74 68 61 74 20 61 72 65 20  values that are 
23ac0 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23ad0 6f 62 20 7c 20 62 6f 75 6e 64 5d 0a 2a 2a 20 74  ob | bound].** t
23ae0 6f 20 74 68 65 20 70 61 72 61 6d 65 74 65 72 73  o the parameters
23af0 20 61 74 20 61 20 6c 61 74 65 72 20 74 69 6d 65   at a later time
23b00 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 72  ..**.** ^(This r
23b10 6f 75 74 69 6e 65 20 61 63 74 75 61 6c 6c 79 20  outine actually 
23b20 72 65 74 75 72 6e 73 20 74 68 65 20 69 6e 64 65  returns the inde
23b30 78 20 6f 66 20 74 68 65 20 6c 61 72 67 65 73 74  x of the largest
23b40 20 28 72 69 67 68 74 6d 6f 73 74 29 0a 2a 2a 20   (rightmost).** 
23b50 70 61 72 61 6d 65 74 65 72 2e 20 46 6f 72 20 61  parameter. For a
23b60 6c 6c 20 66 6f 72 6d 73 20 65 78 63 65 70 74 20  ll forms except 
23b70 3f 4e 4e 4e 2c 20 74 68 69 73 20 77 69 6c 6c 20  ?NNN, this will 
23b80 63 6f 72 72 65 73 70 6f 6e 64 20 74 6f 20 74 68  correspond to th
23b90 65 0a 2a 2a 20 6e 75 6d 62 65 72 20 6f 66 20 75  e.** number of u
23ba0 6e 69 71 75 65 20 70 61 72 61 6d 65 74 65 72 73  nique parameters
23bb0 2e 20 20 49 66 20 70 61 72 61 6d 65 74 65 72 73  .  If parameters
23bc0 20 6f 66 20 74 68 65 20 3f 4e 4e 4e 20 66 6f 72   of the ?NNN for
23bd0 6d 20 61 72 65 20 75 73 65 64 2c 0a 2a 2a 20 74  m are used,.** t
23be0 68 65 72 65 20 6d 61 79 20 62 65 20 67 61 70 73  here may be gaps
23bf0 20 69 6e 20 74 68 65 20 6c 69 73 74 2e 29 5e 0a   in the list.)^.
23c00 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f 3a 20  **.** See also: 
23c10 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c  [sqlite3_bind_bl
23c20 6f 62 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28  ob|sqlite3_bind(
23c30 29 5d 2c 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  )],.** [sqlite3_
23c40 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 6e  bind_parameter_n
23c50 61 6d 65 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b  ame()], and.** [
23c60 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
23c70 61 6d 65 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e  ameter_index()].
23c80 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
23c90 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f 63  bind_parameter_c
23ca0 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f 73 74 6d  ount(sqlite3_stm
23cb0 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  t*);../*.** CAPI
23cc0 33 52 45 46 3a 20 4e 61 6d 65 20 4f 66 20 41 20  3REF: Name Of A 
23cd0 48 6f 73 74 20 50 61 72 61 6d 65 74 65 72 0a 2a  Host Parameter.*
23ce0 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
23cf0 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72  3_bind_parameter
23d00 5f 6e 61 6d 65 28 50 2c 4e 29 20 69 6e 74 65 72  _name(P,N) inter
23d10 66 61 63 65 20 72 65 74 75 72 6e 73 0a 2a 2a 20  face returns.** 
23d20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
23d30 4e 2d 74 68 20 5b 53 51 4c 20 70 61 72 61 6d 65  N-th [SQL parame
23d40 74 65 72 5d 20 69 6e 20 74 68 65 20 5b 70 72 65  ter] in the [pre
23d50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d  pared statement]
23d60 20 50 2e 0a 2a 2a 20 5e 28 53 51 4c 20 70 61 72   P..** ^(SQL par
23d70 61 6d 65 74 65 72 73 20 6f 66 20 74 68 65 20 66  ameters of the f
23d80 6f 72 6d 20 22 3f 4e 4e 4e 22 20 6f 72 20 22 3a  orm "?NNN" or ":
23d90 41 41 41 22 20 6f 72 20 22 40 41 41 41 22 20 6f  AAA" or "@AAA" o
23da0 72 20 22 24 41 41 41 22 0a 2a 2a 20 68 61 76 65  r "$AAA".** have
23db0 20 61 20 6e 61 6d 65 20 77 68 69 63 68 20 69 73   a name which is
23dc0 20 74 68 65 20 73 74 72 69 6e 67 20 22 3f 4e 4e   the string "?NN
23dd0 4e 22 20 6f 72 20 22 3a 41 41 41 22 20 6f 72 20  N" or ":AAA" or 
23de0 22 40 41 41 41 22 20 6f 72 20 22 24 41 41 41 22  "@AAA" or "$AAA"
23df0 0a 2a 2a 20 72 65 73 70 65 63 74 69 76 65 6c 79  .** respectively
23e00 2e 0a 2a 2a 20 49 6e 20 6f 74 68 65 72 20 77 6f  ..** In other wo
23e10 72 64 73 2c 20 74 68 65 20 69 6e 69 74 69 61 6c  rds, the initial
23e20 20 22 3a 22 20 6f 72 20 22 24 22 20 6f 72 20 22   ":" or "$" or "
23e30 40 22 20 6f 72 20 22 3f 22 0a 2a 2a 20 69 73 20  @" or "?".** is 
23e40 69 6e 63 6c 75 64 65 64 20 61 73 20 70 61 72 74  included as part
23e50 20 6f 66 20 74 68 65 20 6e 61 6d 65 2e 29 5e 0a   of the name.)^.
23e60 2a 2a 20 5e 50 61 72 61 6d 65 74 65 72 73 20 6f  ** ^Parameters o
23e70 66 20 74 68 65 20 66 6f 72 6d 20 22 3f 22 20 77  f the form "?" w
23e80 69 74 68 6f 75 74 20 61 20 66 6f 6c 6c 6f 77 69  ithout a followi
23e90 6e 67 20 69 6e 74 65 67 65 72 20 68 61 76 65 20  ng integer have 
23ea0 6e 6f 20 6e 61 6d 65 0a 2a 2a 20 61 6e 64 20 61  no name.** and a
23eb0 72 65 20 72 65 66 65 72 72 65 64 20 74 6f 20 61  re referred to a
23ec0 73 20 22 6e 61 6d 65 6c 65 73 73 22 20 6f 72 20  s "nameless" or 
23ed0 22 61 6e 6f 6e 79 6d 6f 75 73 20 70 61 72 61 6d  "anonymous param
23ee0 65 74 65 72 73 22 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eters"..**.** ^T
23ef0 68 65 20 66 69 72 73 74 20 68 6f 73 74 20 70 61  he first host pa
23f00 72 61 6d 65 74 65 72 20 68 61 73 20 61 6e 20 69  rameter has an i
23f10 6e 64 65 78 20 6f 66 20 31 2c 20 6e 6f 74 20 30  ndex of 1, not 0
23f20 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
23f30 76 61 6c 75 65 20 4e 20 69 73 20 6f 75 74 20 6f  value N is out o
23f40 66 20 72 61 6e 67 65 20 6f 72 20 69 66 20 74 68  f range or if th
23f50 65 20 4e 2d 74 68 20 70 61 72 61 6d 65 74 65 72  e N-th parameter
23f60 20 69 73 0a 2a 2a 20 6e 61 6d 65 6c 65 73 73 2c   is.** nameless,
23f70 20 74 68 65 6e 20 4e 55 4c 4c 20 69 73 20 72 65   then NULL is re
23f80 74 75 72 6e 65 64 2e 20 20 5e 54 68 65 20 72 65  turned.  ^The re
23f90 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 69 73  turned string is
23fa0 0a 2a 2a 20 61 6c 77 61 79 73 20 69 6e 20 55 54  .** always in UT
23fb0 46 2d 38 20 65 6e 63 6f 64 69 6e 67 20 65 76 65  F-8 encoding eve
23fc0 6e 20 69 66 20 74 68 65 20 6e 61 6d 65 64 20 70  n if the named p
23fd0 61 72 61 6d 65 74 65 72 20 77 61 73 0a 2a 2a 20  arameter was.** 
23fe0 6f 72 69 67 69 6e 61 6c 6c 79 20 73 70 65 63 69  originally speci
23ff0 66 69 65 64 20 61 73 20 55 54 46 2d 31 36 20 69  fied as UTF-16 i
24000 6e 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  n [sqlite3_prepa
24010 72 65 31 36 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73  re16()] or.** [s
24020 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
24030 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 53 65  _v2()]..**.** Se
24040 65 20 61 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33  e also: [sqlite3
24050 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73 71 6c 69 74  _bind_blob|sqlit
24060 65 33 5f 62 69 6e 64 28 29 5d 2c 0a 2a 2a 20 5b  e3_bind()],.** [
24070 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f 70 61 72  sqlite3_bind_par
24080 61 6d 65 74 65 72 5f 63 6f 75 6e 74 28 29 5d 2c  ameter_count()],
24090 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c 69 74 65 33   and.** [sqlite3
240a0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
240b0 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f 0a 63 6f 6e  index()]..*/.con
240c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
240d0 5f 62 69 6e 64 5f 70 61 72 61 6d 65 74 65 72 5f  _bind_parameter_
240e0 6e 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d  name(sqlite3_stm
240f0 74 2a 2c 20 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a  t*, int);../*.**
24100 20 43 41 50 49 33 52 45 46 3a 20 49 6e 64 65 78   CAPI3REF: Index
24110 20 4f 66 20 41 20 50 61 72 61 6d 65 74 65 72 20   Of A Parameter 
24120 57 69 74 68 20 41 20 47 69 76 65 6e 20 4e 61 6d  With A Given Nam
24130 65 0a 2a 2a 0a 2a 2a 20 5e 52 65 74 75 72 6e 20  e.**.** ^Return 
24140 74 68 65 20 69 6e 64 65 78 20 6f 66 20 61 6e 20  the index of an 
24150 53 51 4c 20 70 61 72 61 6d 65 74 65 72 20 67 69  SQL parameter gi
24160 76 65 6e 20 69 74 73 20 6e 61 6d 65 2e 20 20 5e  ven its name.  ^
24170 54 68 65 0a 2a 2a 20 69 6e 64 65 78 20 76 61 6c  The.** index val
24180 75 65 20 72 65 74 75 72 6e 65 64 20 69 73 20 73  ue returned is s
24190 75 69 74 61 62 6c 65 20 66 6f 72 20 75 73 65 20  uitable for use 
241a0 61 73 20 74 68 65 20 73 65 63 6f 6e 64 0a 2a 2a  as the second.**
241b0 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 5b 73   parameter to [s
241c0 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
241d0 7c 73 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d  |sqlite3_bind()]
241e0 2e 20 20 5e 41 20 7a 65 72 6f 0a 2a 2a 20 69 73  .  ^A zero.** is
241f0 20 72 65 74 75 72 6e 65 64 20 69 66 20 6e 6f 20   returned if no 
24200 6d 61 74 63 68 69 6e 67 20 70 61 72 61 6d 65 74  matching paramet
24210 65 72 20 69 73 20 66 6f 75 6e 64 2e 20 20 5e 54  er is found.  ^T
24220 68 65 20 70 61 72 61 6d 65 74 65 72 0a 2a 2a 20  he parameter.** 
24230 6e 61 6d 65 20 6d 75 73 74 20 62 65 20 67 69 76  name must be giv
24240 65 6e 20 69 6e 20 55 54 46 2d 38 20 65 76 65 6e  en in UTF-8 even
24250 20 69 66 20 74 68 65 20 6f 72 69 67 69 6e 61 6c   if the original
24260 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20 77 61   statement.** wa
24270 73 20 70 72 65 70 61 72 65 64 20 66 72 6f 6d 20  s prepared from 
24280 55 54 46 2d 31 36 20 74 65 78 74 20 75 73 69 6e  UTF-16 text usin
24290 67 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61  g [sqlite3_prepa
242a0 72 65 31 36 5f 76 32 28 29 5d 2e 0a 2a 2a 0a 2a  re16_v2()]..**.*
242b0 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
242c0 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c 73  ite3_bind_blob|s
242d0 71 6c 69 74 65 33 5f 62 69 6e 64 28 29 5d 2c 0a  qlite3_bind()],.
242e0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  ** [sqlite3_bind
242f0 5f 70 61 72 61 6d 65 74 65 72 5f 63 6f 75 6e 74  _parameter_count
24300 28 29 5d 2c 20 61 6e 64 0a 2a 2a 20 5b 73 71 6c  ()], and.** [sql
24310 69 74 65 33 5f 62 69 6e 64 5f 70 61 72 61 6d 65  ite3_bind_parame
24320 74 65 72 5f 69 6e 64 65 78 28 29 5d 2e 0a 2a 2f  ter_index()]..*/
24330 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 62 69 6e  .int sqlite3_bin
24340 64 5f 70 61 72 61 6d 65 74 65 72 5f 69 6e 64 65  d_parameter_inde
24350 78 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  x(sqlite3_stmt*,
24360 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61   const char *zNa
24370 6d 65 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  me);../*.** CAPI
24380 33 52 45 46 3a 20 52 65 73 65 74 20 41 6c 6c 20  3REF: Reset All 
24390 42 69 6e 64 69 6e 67 73 20 4f 6e 20 41 20 50 72  Bindings On A Pr
243a0 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
243b0 0a 2a 2a 0a 2a 2a 20 5e 43 6f 6e 74 72 61 72 79  .**.** ^Contrary
243c0 20 74 6f 20 74 68 65 20 69 6e 74 75 69 74 69 6f   to the intuitio
243d0 6e 20 6f 66 20 6d 61 6e 79 2c 20 5b 73 71 6c 69  n of many, [sqli
243e0 74 65 33 5f 72 65 73 65 74 28 29 5d 20 64 6f 65  te3_reset()] doe
243f0 73 20 6e 6f 74 20 72 65 73 65 74 0a 2a 2a 20 74  s not reset.** t
24400 68 65 20 5b 73 71 6c 69 74 65 33 5f 62 69 6e 64  he [sqlite3_bind
24410 5f 62 6c 6f 62 20 7c 20 62 69 6e 64 69 6e 67 73  _blob | bindings
24420 5d 20 6f 6e 20 61 20 5b 70 72 65 70 61 72 65 64  ] on a [prepared
24430 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a 2a 2a 20   statement]..** 
24440 5e 55 73 65 20 74 68 69 73 20 72 6f 75 74 69 6e  ^Use this routin
24450 65 20 74 6f 20 72 65 73 65 74 20 61 6c 6c 20 68  e to reset all h
24460 6f 73 74 20 70 61 72 61 6d 65 74 65 72 73 20 74  ost parameters t
24470 6f 20 4e 55 4c 4c 2e 0a 2a 2f 0a 69 6e 74 20 73  o NULL..*/.int s
24480 71 6c 69 74 65 33 5f 63 6c 65 61 72 5f 62 69 6e  qlite3_clear_bin
24490 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73 74  dings(sqlite3_st
244a0 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  mt*);../*.** CAP
244b0 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 4f 66  I3REF: Number Of
244c0 20 43 6f 6c 75 6d 6e 73 20 49 6e 20 41 20 52 65   Columns In A Re
244d0 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a 2a 20 5e  sult Set.**.** ^
244e0 52 65 74 75 72 6e 20 74 68 65 20 6e 75 6d 62 65  Return the numbe
244f0 72 20 6f 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20  r of columns in 
24500 74 68 65 20 72 65 73 75 6c 74 20 73 65 74 20 72  the result set r
24510 65 74 75 72 6e 65 64 20 62 79 20 74 68 65 0a 2a  eturned by the.*
24520 2a 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  * [prepared stat
24530 65 6d 65 6e 74 5d 2e 20 5e 54 68 69 73 20 72 6f  ement]. ^This ro
24540 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 30 20  utine returns 0 
24550 69 66 20 70 53 74 6d 74 20 69 73 20 61 6e 20 53  if pStmt is an S
24560 51 4c 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  QL.** statement 
24570 74 68 61 74 20 64 6f 65 73 20 6e 6f 74 20 72 65  that does not re
24580 74 75 72 6e 20 64 61 74 61 20 28 66 6f 72 20 65  turn data (for e
24590 78 61 6d 70 6c 65 20 61 6e 20 5b 55 50 44 41 54  xample an [UPDAT
245a0 45 5d 29 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61  E])..**.** See a
245b0 6c 73 6f 3a 20 5b 73 71 6c 69 74 65 33 5f 64 61  lso: [sqlite3_da
245c0 74 61 5f 63 6f 75 6e 74 28 29 5d 0a 2a 2f 0a 69  ta_count()].*/.i
245d0 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
245e0 6e 5f 63 6f 75 6e 74 28 73 71 6c 69 74 65 33 5f  n_count(sqlite3_
245f0 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a 0a 2f  stmt *pStmt);../
24600 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 43  *.** CAPI3REF: C
24610 6f 6c 75 6d 6e 20 4e 61 6d 65 73 20 49 6e 20 41  olumn Names In A
24620 20 52 65 73 75 6c 74 20 53 65 74 0a 2a 2a 0a 2a   Result Set.**.*
24630 2a 20 5e 54 68 65 73 65 20 72 6f 75 74 69 6e 65  * ^These routine
24640 73 20 72 65 74 75 72 6e 20 74 68 65 20 6e 61 6d  s return the nam
24650 65 20 61 73 73 69 67 6e 65 64 20 74 6f 20 61 20  e assigned to a 
24660 70 61 72 74 69 63 75 6c 61 72 20 63 6f 6c 75 6d  particular colum
24670 6e 0a 2a 2a 20 69 6e 20 74 68 65 20 72 65 73 75  n.** in the resu
24680 6c 74 20 73 65 74 20 6f 66 20 61 20 5b 53 45 4c  lt set of a [SEL
24690 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 2e 20  ECT] statement. 
246a0 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63 6f   ^The sqlite3_co
246b0 6c 75 6d 6e 5f 6e 61 6d 65 28 29 0a 2a 2a 20 69  lumn_name().** i
246c0 6e 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73  nterface returns
246d0 20 61 20 70 6f 69 6e 74 65 72 20 74 6f 20 61 20   a pointer to a 
246e0 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 65 64 20  zero-terminated 
246f0 55 54 46 2d 38 20 73 74 72 69 6e 67 0a 2a 2a 20  UTF-8 string.** 
24700 61 6e 64 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  and sqlite3_colu
24710 6d 6e 5f 6e 61 6d 65 31 36 28 29 20 72 65 74 75  mn_name16() retu
24720 72 6e 73 20 61 20 70 6f 69 6e 74 65 72 20 74 6f  rns a pointer to
24730 20 61 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74   a zero-terminat
24740 65 64 0a 2a 2a 20 55 54 46 2d 31 36 20 73 74 72  ed.** UTF-16 str
24750 69 6e 67 2e 20 20 5e 54 68 65 20 66 69 72 73 74  ing.  ^The first
24760 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
24770 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74  e [prepared stat
24780 65 6d 65 6e 74 5d 0a 2a 2a 20 74 68 61 74 20 69  ement].** that i
24790 6d 70 6c 65 6d 65 6e 74 73 20 74 68 65 20 5b 53  mplements the [S
247a0 45 4c 45 43 54 5d 20 73 74 61 74 65 6d 65 6e 74  ELECT] statement
247b0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
247c0 72 61 6d 65 74 65 72 20 69 73 20 74 68 65 0a 2a  rameter is the.*
247d0 2a 20 63 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e  * column number.
247e0 20 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20    ^The leftmost 
247f0 63 6f 6c 75 6d 6e 20 69 73 20 6e 75 6d 62 65 72  column is number
24800 20 30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 72   0..**.** ^The r
24810 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20 70  eturned string p
24820 6f 69 6e 74 65 72 20 69 73 20 76 61 6c 69 64 20  ointer is valid 
24830 75 6e 74 69 6c 20 65 69 74 68 65 72 20 74 68 65  until either the
24840 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
24850 6d 65 6e 74 5d 0a 2a 2a 20 69 73 20 64 65 73 74  ment].** is dest
24860 72 6f 79 65 64 20 62 79 20 5b 73 71 6c 69 74 65  royed by [sqlite
24870 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 6f 72  3_finalize()] or
24880 20 75 6e 74 69 6c 20 74 68 65 20 73 74 61 74 65   until the state
24890 6d 65 6e 74 20 69 73 20 61 75 74 6f 6d 61 74 69  ment is automati
248a0 63 61 6c 6c 79 0a 2a 2a 20 72 65 70 72 65 70 61  cally.** reprepa
248b0 72 65 64 20 62 79 20 74 68 65 20 66 69 72 73 74  red by the first
248c0 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65   call to [sqlite
248d0 33 5f 73 74 65 70 28 29 5d 20 66 6f 72 20 61 20  3_step()] for a 
248e0 70 61 72 74 69 63 75 6c 61 72 20 72 75 6e 0a 2a  particular run.*
248f0 2a 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20 6e  * or until the n
24900 65 78 74 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 73  ext call to.** s
24910 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61  qlite3_column_na
24920 6d 65 28 29 20 6f 72 20 73 71 6c 69 74 65 33 5f  me() or sqlite3_
24930 63 6f 6c 75 6d 6e 5f 6e 61 6d 65 31 36 28 29 20  column_name16() 
24940 6f 6e 20 74 68 65 20 73 61 6d 65 20 63 6f 6c 75  on the same colu
24950 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 73 71  mn..**.** ^If sq
24960 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 20 66  lite3_malloc() f
24970 61 69 6c 73 20 64 75 72 69 6e 67 20 74 68 65 20  ails during the 
24980 70 72 6f 63 65 73 73 69 6e 67 20 6f 66 20 65 69  processing of ei
24990 74 68 65 72 20 72 6f 75 74 69 6e 65 0a 2a 2a 20  ther routine.** 
249a0 28 66 6f 72 20 65 78 61 6d 70 6c 65 20 64 75 72  (for example dur
249b0 69 6e 67 20 61 20 63 6f 6e 76 65 72 73 69 6f 6e  ing a conversion
249c0 20 66 72 6f 6d 20 55 54 46 2d 38 20 74 6f 20 55   from UTF-8 to U
249d0 54 46 2d 31 36 29 20 74 68 65 6e 20 61 0a 2a 2a  TF-16) then a.**
249e0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73   NULL pointer is
249f0 20 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a   returned..**.**
24a00 20 5e 54 68 65 20 6e 61 6d 65 20 6f 66 20 61 20   ^The name of a 
24a10 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 69 73  result column is
24a20 20 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68   the value of th
24a30 65 20 22 41 53 22 20 63 6c 61 75 73 65 20 66 6f  e "AS" clause fo
24a40 72 0a 2a 2a 20 74 68 61 74 20 63 6f 6c 75 6d 6e  r.** that column
24a50 2c 20 69 66 20 74 68 65 72 65 20 69 73 20 61 6e  , if there is an
24a60 20 41 53 20 63 6c 61 75 73 65 2e 20 20 49 66 20   AS clause.  If 
24a70 74 68 65 72 65 20 69 73 20 6e 6f 20 41 53 20 63  there is no AS c
24a80 6c 61 75 73 65 0a 2a 2a 20 74 68 65 6e 20 74 68  lause.** then th
24a90 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f  e name of the co
24aa0 6c 75 6d 6e 20 69 73 20 75 6e 73 70 65 63 69 66  lumn is unspecif
24ab0 69 65 64 20 61 6e 64 20 6d 61 79 20 63 68 61 6e  ied and may chan
24ac0 67 65 20 66 72 6f 6d 0a 2a 2a 20 6f 6e 65 20 72  ge from.** one r
24ad0 65 6c 65 61 73 65 20 6f 66 20 53 51 4c 69 74 65  elease of SQLite
24ae0 20 74 6f 20 74 68 65 20 6e 65 78 74 2e 0a 2a 2f   to the next..*/
24af0 0a 63 6f 6e 73 74 20 63 68 61 72 20 2a 73 71 6c  .const char *sql
24b00 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 6e 61 6d 65  ite3_column_name
24b10 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
24b20 69 6e 74 20 4e 29 3b 0a 63 6f 6e 73 74 20 76 6f  int N);.const vo
24b30 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
24b40 6d 6e 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65  mn_name16(sqlite
24b50 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 4e 29 3b  3_stmt*, int N);
24b60 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46  ../*.** CAPI3REF
24b70 3a 20 53 6f 75 72 63 65 20 4f 66 20 44 61 74 61  : Source Of Data
24b80 20 49 6e 20 41 20 51 75 65 72 79 20 52 65 73 75   In A Query Resu
24b90 6c 74 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  lt.**.** ^These 
24ba0 72 6f 75 74 69 6e 65 73 20 70 72 6f 76 69 64 65  routines provide
24bb0 20 61 20 6d 65 61 6e 73 20 74 6f 20 64 65 74 65   a means to dete
24bc0 72 6d 69 6e 65 20 74 68 65 20 64 61 74 61 62 61  rmine the databa
24bd0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 0a 2a  se, table, and.*
24be0 2a 20 74 61 62 6c 65 20 63 6f 6c 75 6d 6e 20 74  * table column t
24bf0 68 61 74 20 69 73 20 74 68 65 20 6f 72 69 67 69  hat is the origi
24c00 6e 20 6f 66 20 61 20 70 61 72 74 69 63 75 6c 61  n of a particula
24c10 72 20 72 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20  r result column 
24c20 69 6e 0a 2a 2a 20 5b 53 45 4c 45 43 54 5d 20 73  in.** [SELECT] s
24c30 74 61 74 65 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  tatement..** ^Th
24c40 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20 64 61  e name of the da
24c50 74 61 62 61 73 65 20 6f 72 20 74 61 62 6c 65 20  tabase or table 
24c60 6f 72 20 63 6f 6c 75 6d 6e 20 63 61 6e 20 62 65  or column can be
24c70 20 72 65 74 75 72 6e 65 64 20 61 73 0a 2a 2a 20   returned as.** 
24c80 65 69 74 68 65 72 20 61 20 55 54 46 2d 38 20 6f  either a UTF-8 o
24c90 72 20 55 54 46 2d 31 36 20 73 74 72 69 6e 67 2e  r UTF-16 string.
24ca0 20 20 5e 54 68 65 20 5f 64 61 74 61 62 61 73 65    ^The _database
24cb0 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74 75 72  _ routines retur
24cc0 6e 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73  n.** the databas
24cd0 65 20 6e 61 6d 65 2c 20 74 68 65 20 5f 74 61 62  e name, the _tab
24ce0 6c 65 5f 20 72 6f 75 74 69 6e 65 73 20 72 65 74  le_ routines ret
24cf0 75 72 6e 20 74 68 65 20 74 61 62 6c 65 20 6e 61  urn the table na
24d00 6d 65 2c 20 61 6e 64 0a 2a 2a 20 74 68 65 20 6f  me, and.** the o
24d10 72 69 67 69 6e 5f 20 72 6f 75 74 69 6e 65 73 20  rigin_ routines 
24d20 72 65 74 75 72 6e 20 74 68 65 20 63 6f 6c 75 6d  return the colum
24d30 6e 20 6e 61 6d 65 2e 0a 2a 2a 20 5e 54 68 65 20  n name..** ^The 
24d40 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e 67 20  returned string 
24d50 69 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 74  is valid until t
24d60 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  he [prepared sta
24d70 74 65 6d 65 6e 74 5d 20 69 73 20 64 65 73 74 72  tement] is destr
24d80 6f 79 65 64 0a 2a 2a 20 75 73 69 6e 67 20 5b 73  oyed.** using [s
24d90 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
24da0 29 5d 20 6f 72 20 75 6e 74 69 6c 20 74 68 65 20  )] or until the 
24db0 73 74 61 74 65 6d 65 6e 74 20 69 73 20 61 75 74  statement is aut
24dc0 6f 6d 61 74 69 63 61 6c 6c 79 0a 2a 2a 20 72 65  omatically.** re
24dd0 70 72 65 70 61 72 65 64 20 62 79 20 74 68 65 20  prepared by the 
24de0 66 69 72 73 74 20 63 61 6c 6c 20 74 6f 20 5b 73  first call to [s
24df0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 66  qlite3_step()] f
24e00 6f 72 20 61 20 70 61 72 74 69 63 75 6c 61 72 20  or a particular 
24e10 72 75 6e 0a 2a 2a 20 6f 72 20 75 6e 74 69 6c 20  run.** or until 
24e20 74 68 65 20 73 61 6d 65 20 69 6e 66 6f 72 6d 61  the same informa
24e30 74 69 6f 6e 20 69 73 20 72 65 71 75 65 73 74 65  tion is requeste
24e40 64 0a 2a 2a 20 61 67 61 69 6e 20 69 6e 20 61 20  d.** again in a 
24e50 64 69 66 66 65 72 65 6e 74 20 65 6e 63 6f 64 69  different encodi
24e60 6e 67 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6e  ng..**.** ^The n
24e70 61 6d 65 73 20 72 65 74 75 72 6e 65 64 20 61 72  ames returned ar
24e80 65 20 74 68 65 20 6f 72 69 67 69 6e 61 6c 20 75  e the original u
24e90 6e 2d 61 6c 69 61 73 65 64 20 6e 61 6d 65 73 20  n-aliased names 
24ea0 6f 66 20 74 68 65 0a 2a 2a 20 64 61 74 61 62 61  of the.** databa
24eb0 73 65 2c 20 74 61 62 6c 65 2c 20 61 6e 64 20 63  se, table, and c
24ec0 6f 6c 75 6d 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  olumn..**.** ^Th
24ed0 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74  e first argument
24ee0 20 74 6f 20 74 68 65 73 65 20 69 6e 74 65 72 66   to these interf
24ef0 61 63 65 73 20 69 73 20 61 20 5b 70 72 65 70 61  aces is a [prepa
24f00 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
24f10 2a 2a 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69  ** ^These functi
24f20 6f 6e 73 20 72 65 74 75 72 6e 20 69 6e 66 6f 72  ons return infor
24f30 6d 61 74 69 6f 6e 20 61 62 6f 75 74 20 74 68 65  mation about the
24f40 20 4e 74 68 20 72 65 73 75 6c 74 20 63 6f 6c 75   Nth result colu
24f50 6d 6e 20 72 65 74 75 72 6e 65 64 20 62 79 0a 2a  mn returned by.*
24f60 2a 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 2c  * the statement,
24f70 20 77 68 65 72 65 20 4e 20 69 73 20 74 68 65 20   where N is the 
24f80 73 65 63 6f 6e 64 20 66 75 6e 63 74 69 6f 6e 20  second function 
24f90 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20 5e 54 68  argument..** ^Th
24fa0 65 20 6c 65 66 74 2d 6d 6f 73 74 20 63 6f 6c 75  e left-most colu
24fb0 6d 6e 20 69 73 20 63 6f 6c 75 6d 6e 20 30 20 66  mn is column 0 f
24fc0 6f 72 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65  or these routine
24fd0 73 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65  s..**.** ^If the
24fe0 20 4e 74 68 20 63 6f 6c 75 6d 6e 20 72 65 74 75   Nth column retu
24ff0 72 6e 65 64 20 62 79 20 74 68 65 20 73 74 61 74  rned by the stat
25000 65 6d 65 6e 74 20 69 73 20 61 6e 20 65 78 70 72  ement is an expr
25010 65 73 73 69 6f 6e 20 6f 72 0a 2a 2a 20 73 75 62  ession or.** sub
25020 71 75 65 72 79 20 61 6e 64 20 69 73 20 6e 6f 74  query and is not
25030 20 61 20 63 6f 6c 75 6d 6e 20 76 61 6c 75 65 2c   a column value,
25040 20 74 68 65 6e 20 61 6c 6c 20 6f 66 20 74 68 65   then all of the
25050 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 72 65 74  se functions ret
25060 75 72 6e 0a 2a 2a 20 4e 55 4c 4c 2e 20 20 5e 54  urn.** NULL.  ^T
25070 68 65 73 65 20 72 6f 75 74 69 6e 65 20 6d 69 67  hese routine mig
25080 68 74 20 61 6c 73 6f 20 72 65 74 75 72 6e 20 4e  ht also return N
25090 55 4c 4c 20 69 66 20 61 20 6d 65 6d 6f 72 79 20  ULL if a memory 
250a0 61 6c 6c 6f 63 61 74 69 6f 6e 20 65 72 72 6f 72  allocation error
250b0 0a 2a 2a 20 6f 63 63 75 72 73 2e 20 20 5e 4f 74  .** occurs.  ^Ot
250c0 68 65 72 77 69 73 65 2c 20 74 68 65 79 20 72 65  herwise, they re
250d0 74 75 72 6e 20 74 68 65 20 6e 61 6d 65 20 6f 66  turn the name of
250e0 20 74 68 65 20 61 74 74 61 63 68 65 64 20 64 61   the attached da
250f0 74 61 62 61 73 65 2c 20 74 61 62 6c 65 2c 0a 2a  tabase, table,.*
25100 2a 20 6f 72 20 63 6f 6c 75 6d 6e 20 74 68 61 74  * or column that
25110 20 71 75 65 72 79 20 72 65 73 75 6c 74 20 63 6f   query result co
25120 6c 75 6d 6e 20 77 61 73 20 65 78 74 72 61 63 74  lumn was extract
25130 65 64 20 66 72 6f 6d 2e 0a 2a 2a 0a 2a 2a 20 5e  ed from..**.** ^
25140 41 73 20 77 69 74 68 20 61 6c 6c 20 6f 74 68 65  As with all othe
25150 72 20 53 51 4c 69 74 65 20 41 50 49 73 2c 20 74  r SQLite APIs, t
25160 68 6f 73 65 20 77 68 6f 73 65 20 6e 61 6d 65 73  hose whose names
25170 20 65 6e 64 20 77 69 74 68 20 22 31 36 22 20 72   end with "16" r
25180 65 74 75 72 6e 0a 2a 2a 20 55 54 46 2d 31 36 20  eturn.** UTF-16 
25190 65 6e 63 6f 64 65 64 20 73 74 72 69 6e 67 73 20  encoded strings 
251a0 61 6e 64 20 74 68 65 20 6f 74 68 65 72 20 66 75  and the other fu
251b0 6e 63 74 69 6f 6e 73 20 72 65 74 75 72 6e 20 55  nctions return U
251c0 54 46 2d 38 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  TF-8..**.** ^The
251d0 73 65 20 41 50 49 73 20 61 72 65 20 6f 6e 6c 79  se APIs are only
251e0 20 61 76 61 69 6c 61 62 6c 65 20 69 66 20 74 68   available if th
251f0 65 20 6c 69 62 72 61 72 79 20 77 61 73 20 63 6f  e library was co
25200 6d 70 69 6c 65 64 20 77 69 74 68 20 74 68 65 0a  mpiled with the.
25210 2a 2a 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c  ** [SQLITE_ENABL
25220 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54 41 44 41 54  E_COLUMN_METADAT
25230 41 5d 20 43 2d 70 72 65 70 72 6f 63 65 73 73 6f  A] C-preprocesso
25240 72 20 73 79 6d 62 6f 6c 2e 0a 2a 2a 0a 2a 2a 20  r symbol..**.** 
25250 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 74  If two or more t
25260 68 72 65 61 64 73 20 63 61 6c 6c 20 6f 6e 65 20  hreads call one 
25270 6f 72 20 6d 6f 72 65 20 6f 66 20 74 68 65 73 65  or more of these
25280 20 72 6f 75 74 69 6e 65 73 20 61 67 61 69 6e 73   routines agains
25290 74 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 70 72  t the same.** pr
252a0 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
252b0 20 61 6e 64 20 63 6f 6c 75 6d 6e 20 61 74 20 74   and column at t
252c0 68 65 20 73 61 6d 65 20 74 69 6d 65 20 74 68 65  he same time the
252d0 6e 20 74 68 65 20 72 65 73 75 6c 74 73 20 61 72  n the results ar
252e0 65 0a 2a 2a 20 75 6e 64 65 66 69 6e 65 64 2e 0a  e.** undefined..
252f0 2a 2a 0a 2a 2a 20 49 66 20 74 77 6f 20 6f 72 20  **.** If two or 
25300 6d 6f 72 65 20 74 68 72 65 61 64 73 20 63 61 6c  more threads cal
25310 6c 20 6f 6e 65 20 6f 72 20 6d 6f 72 65 0a 2a 2a  l one or more.**
25320 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e   [sqlite3_column
25330 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65 20 7c  _database_name |
25340 20 63 6f 6c 75 6d 6e 20 6d 65 74 61 64 61 74 61   column metadata
25350 20 69 6e 74 65 72 66 61 63 65 73 5d 0a 2a 2a 20   interfaces].** 
25360 66 6f 72 20 74 68 65 20 73 61 6d 65 20 5b 70 72  for the same [pr
25370 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
25380 5d 20 61 6e 64 20 72 65 73 75 6c 74 20 63 6f 6c  ] and result col
25390 75 6d 6e 0a 2a 2a 20 61 74 20 74 68 65 20 73 61  umn.** at the sa
253a0 6d 65 20 74 69 6d 65 20 74 68 65 6e 20 74 68 65  me time then the
253b0 20 72 65 73 75 6c 74 73 20 61 72 65 20 75 6e 64   results are und
253c0 65 66 69 6e 65 64 2e 0a 2a 2f 0a 63 6f 6e 73 74  efined..*/.const
253d0 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33 5f 63   char *sqlite3_c
253e0 6f 6c 75 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e  olumn_database_n
253f0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
25400 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
25410 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25420 6d 6e 5f 64 61 74 61 62 61 73 65 5f 6e 61 6d 65  mn_database_name
25430 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25440 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 63 68 61  ,int);.const cha
25450 72 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  r *sqlite3_colum
25460 6e 5f 74 61 62 6c 65 5f 6e 61 6d 65 28 73 71 6c  n_table_name(sql
25470 69 74 65 33 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b  ite3_stmt*,int);
25480 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c  .const void *sql
25490 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 61 62 6c  ite3_column_tabl
254a0 65 5f 6e 61 6d 65 31 36 28 73 71 6c 69 74 65 33  e_name16(sqlite3
254b0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
254c0 73 74 20 63 68 61 72 20 2a 73 71 6c 69 74 65 33  st char *sqlite3
254d0 5f 63 6f 6c 75 6d 6e 5f 6f 72 69 67 69 6e 5f 6e  _column_origin_n
254e0 61 6d 65 28 73 71 6c 69 74 65 33 5f 73 74 6d 74  ame(sqlite3_stmt
254f0 2a 2c 69 6e 74 29 3b 0a 63 6f 6e 73 74 20 76 6f  *,int);.const vo
25500 69 64 20 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75  id *sqlite3_colu
25510 6d 6e 5f 6f 72 69 67 69 6e 5f 6e 61 6d 65 31 36  mn_origin_name16
25520 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 69  (sqlite3_stmt*,i
25530 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  nt);../*.** CAPI
25540 33 52 45 46 3a 20 44 65 63 6c 61 72 65 64 20 44  3REF: Declared D
25550 61 74 61 74 79 70 65 20 4f 66 20 41 20 51 75 65  atatype Of A Que
25560 72 79 20 52 65 73 75 6c 74 0a 2a 2a 0a 2a 2a 20  ry Result.**.** 
25570 5e 28 54 68 65 20 66 69 72 73 74 20 70 61 72 61  ^(The first para
25580 6d 65 74 65 72 20 69 73 20 61 20 5b 70 72 65 70  meter is a [prep
25590 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e  ared statement].
255a0 0a 2a 2a 20 49 66 20 74 68 69 73 20 73 74 61 74  .** If this stat
255b0 65 6d 65 6e 74 20 69 73 20 61 20 5b 53 45 4c 45  ement is a [SELE
255c0 43 54 5d 20 73 74 61 74 65 6d 65 6e 74 20 61 6e  CT] statement an
255d0 64 20 74 68 65 20 4e 74 68 20 63 6f 6c 75 6d 6e  d the Nth column
255e0 20 6f 66 20 74 68 65 0a 2a 2a 20 72 65 74 75 72   of the.** retur
255f0 6e 65 64 20 72 65 73 75 6c 74 20 73 65 74 20 6f  ned result set o
25600 66 20 74 68 61 74 20 5b 53 45 4c 45 43 54 5d 20  f that [SELECT] 
25610 69 73 20 61 20 74 61 62 6c 65 20 63 6f 6c 75 6d  is a table colum
25620 6e 20 28 6e 6f 74 20 61 6e 0a 2a 2a 20 65 78 70  n (not an.** exp
25630 72 65 73 73 69 6f 6e 20 6f 72 20 73 75 62 71 75  ression or subqu
25640 65 72 79 29 20 74 68 65 6e 20 74 68 65 20 64 65  ery) then the de
25650 63 6c 61 72 65 64 20 74 79 70 65 20 6f 66 20 74  clared type of t
25660 68 65 20 74 61 62 6c 65 0a 2a 2a 20 63 6f 6c 75  he table.** colu
25670 6d 6e 20 69 73 20 72 65 74 75 72 6e 65 64 2e 29  mn is returned.)
25680 5e 20 20 5e 49 66 20 74 68 65 20 4e 74 68 20 63  ^  ^If the Nth c
25690 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65 73  olumn of the res
256a0 75 6c 74 20 73 65 74 20 69 73 20 61 6e 0a 2a 2a  ult set is an.**
256b0 20 65 78 70 72 65 73 73 69 6f 6e 20 6f 72 20 73   expression or s
256c0 75 62 71 75 65 72 79 2c 20 74 68 65 6e 20 61 20  ubquery, then a 
256d0 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20 69 73 20  NULL pointer is 
256e0 72 65 74 75 72 6e 65 64 2e 0a 2a 2a 20 5e 54 68  returned..** ^Th
256f0 65 20 72 65 74 75 72 6e 65 64 20 73 74 72 69 6e  e returned strin
25700 67 20 69 73 20 61 6c 77 61 79 73 20 55 54 46 2d  g is always UTF-
25710 38 20 65 6e 63 6f 64 65 64 2e 0a 2a 2a 0a 2a 2a  8 encoded..**.**
25720 20 5e 28 46 6f 72 20 65 78 61 6d 70 6c 65 2c 20   ^(For example, 
25730 67 69 76 65 6e 20 74 68 65 20 64 61 74 61 62 61  given the databa
25740 73 65 20 73 63 68 65 6d 61 3a 0a 2a 2a 0a 2a 2a  se schema:.**.**
25750 20 43 52 45 41 54 45 20 54 41 42 4c 45 20 74 31   CREATE TABLE t1
25760 28 63 31 20 56 41 52 49 41 4e 54 29 3b 0a 2a 2a  (c1 VARIANT);.**
25770 0a 2a 2a 20 61 6e 64 20 74 68 65 20 66 6f 6c 6c  .** and the foll
25780 6f 77 69 6e 67 20 73 74 61 74 65 6d 65 6e 74 20  owing statement 
25790 74 6f 20 62 65 20 63 6f 6d 70 69 6c 65 64 3a 0a  to be compiled:.
257a0 2a 2a 0a 2a 2a 20 53 45 4c 45 43 54 20 63 31 20  **.** SELECT c1 
257b0 2b 20 31 2c 20 63 31 20 46 52 4f 4d 20 74 31 3b  + 1, c1 FROM t1;
257c0 0a 2a 2a 0a 2a 2a 20 74 68 69 73 20 72 6f 75 74  .**.** this rout
257d0 69 6e 65 20 77 6f 75 6c 64 20 72 65 74 75 72 6e  ine would return
257e0 20 74 68 65 20 73 74 72 69 6e 67 20 22 56 41 52   the string "VAR
257f0 49 41 4e 54 22 20 66 6f 72 20 74 68 65 20 73 65  IANT" for the se
25800 63 6f 6e 64 20 72 65 73 75 6c 74 0a 2a 2a 20 63  cond result.** c
25810 6f 6c 75 6d 6e 20 28 69 3d 3d 31 29 2c 20 61 6e  olumn (i==1), an
25820 64 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  d a NULL pointer
25830 20 66 6f 72 20 74 68 65 20 66 69 72 73 74 20 72   for the first r
25840 65 73 75 6c 74 20 63 6f 6c 75 6d 6e 20 28 69 3d  esult column (i=
25850 3d 30 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 51  =0).)^.**.** ^SQ
25860 4c 69 74 65 20 75 73 65 73 20 64 79 6e 61 6d 69  Lite uses dynami
25870 63 20 72 75 6e 2d 74 69 6d 65 20 74 79 70 69 6e  c run-time typin
25880 67 2e 20 20 5e 53 6f 20 6a 75 73 74 20 62 65 63  g.  ^So just bec
25890 61 75 73 65 20 61 20 63 6f 6c 75 6d 6e 0a 2a 2a  ause a column.**
258a0 20 69 73 20 64 65 63 6c 61 72 65 64 20 74 6f 20   is declared to 
258b0 63 6f 6e 74 61 69 6e 20 61 20 70 61 72 74 69 63  contain a partic
258c0 75 6c 61 72 20 74 79 70 65 20 64 6f 65 73 20 6e  ular type does n
258d0 6f 74 20 6d 65 61 6e 20 74 68 61 74 20 74 68 65  ot mean that the
258e0 0a 2a 2a 20 64 61 74 61 20 73 74 6f 72 65 64 20  .** data stored 
258f0 69 6e 20 74 68 61 74 20 63 6f 6c 75 6d 6e 20 69  in that column i
25900 73 20 6f 66 20 74 68 65 20 64 65 63 6c 61 72 65  s of the declare
25910 64 20 74 79 70 65 2e 20 20 53 51 4c 69 74 65 20  d type.  SQLite 
25920 69 73 0a 2a 2a 20 73 74 72 6f 6e 67 6c 79 20 74  is.** strongly t
25930 79 70 65 64 2c 20 62 75 74 20 74 68 65 20 74 79  yped, but the ty
25940 70 69 6e 67 20 69 73 20 64 79 6e 61 6d 69 63 20  ping is dynamic 
25950 6e 6f 74 20 73 74 61 74 69 63 2e 20 20 5e 54 79  not static.  ^Ty
25960 70 65 0a 2a 2a 20 69 73 20 61 73 73 6f 63 69 61  pe.** is associa
25970 74 65 64 20 77 69 74 68 20 69 6e 64 69 76 69 64  ted with individ
25980 75 61 6c 20 76 61 6c 75 65 73 2c 20 6e 6f 74 20  ual values, not 
25990 77 69 74 68 20 74 68 65 20 63 6f 6e 74 61 69 6e  with the contain
259a0 65 72 73 0a 2a 2a 20 75 73 65 64 20 74 6f 20 68  ers.** used to h
259b0 6f 6c 64 20 74 68 6f 73 65 20 76 61 6c 75 65 73  old those values
259c0 2e 0a 2a 2f 0a 63 6f 6e 73 74 20 63 68 61 72 20  ..*/.const char 
259d0 2a 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f  *sqlite3_column_
259e0 64 65 63 6c 74 79 70 65 28 73 71 6c 69 74 65 33  decltype(sqlite3
259f0 5f 73 74 6d 74 2a 2c 69 6e 74 29 3b 0a 63 6f 6e  _stmt*,int);.con
25a00 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  st void *sqlite3
25a10 5f 63 6f 6c 75 6d 6e 5f 64 65 63 6c 74 79 70 65  _column_decltype
25a20 31 36 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a  16(sqlite3_stmt*
25a30 2c 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  ,int);../*.** CA
25a40 50 49 33 52 45 46 3a 20 45 76 61 6c 75 61 74 65  PI3REF: Evaluate
25a50 20 41 6e 20 53 51 4c 20 53 74 61 74 65 6d 65 6e   An SQL Statemen
25a60 74 0a 2a 2a 0a 2a 2a 20 41 66 74 65 72 20 61 20  t.**.** After a 
25a70 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
25a80 65 6e 74 5d 20 68 61 73 20 62 65 65 6e 20 70 72  ent] has been pr
25a90 65 70 61 72 65 64 20 75 73 69 6e 67 20 65 69 74  epared using eit
25aa0 68 65 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f  her.** [sqlite3_
25ab0 70 72 65 70 61 72 65 5f 76 32 28 29 5d 20 6f 72  prepare_v2()] or
25ac0 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25ad0 65 31 36 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65  e16_v2()] or one
25ae0 20 6f 66 20 74 68 65 20 6c 65 67 61 63 79 0a 2a   of the legacy.*
25af0 2a 20 69 6e 74 65 72 66 61 63 65 73 20 5b 73 71  * interfaces [sq
25b00 6c 69 74 65 33 5f 70 72 65 70 61 72 65 28 29 5d  lite3_prepare()]
25b10 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
25b20 70 61 72 65 31 36 28 29 5d 2c 20 74 68 69 73 20  pare16()], this 
25b30 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 6d 75 73 74  function.** must
25b40 20 62 65 20 63 61 6c 6c 65 64 20 6f 6e 65 20 6f   be called one o
25b50 72 20 6d 6f 72 65 20 74 69 6d 65 73 20 74 6f 20  r more times to 
25b60 65 76 61 6c 75 61 74 65 20 74 68 65 20 73 74 61  evaluate the sta
25b70 74 65 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 54 68  tement..**.** Th
25b80 65 20 64 65 74 61 69 6c 73 20 6f 66 20 74 68 65  e details of the
25b90 20 62 65 68 61 76 69 6f 72 20 6f 66 20 74 68 65   behavior of the
25ba0 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 20   sqlite3_step() 
25bb0 69 6e 74 65 72 66 61 63 65 20 64 65 70 65 6e 64  interface depend
25bc0 0a 2a 2a 20 6f 6e 20 77 68 65 74 68 65 72 20 74  .** on whether t
25bd0 68 65 20 73 74 61 74 65 6d 65 6e 74 20 77 61 73  he statement was
25be0 20 70 72 65 70 61 72 65 64 20 75 73 69 6e 67 20   prepared using 
25bf0 74 68 65 20 6e 65 77 65 72 20 22 76 32 22 20 69  the newer "v2" i
25c00 6e 74 65 72 66 61 63 65 0a 2a 2a 20 5b 73 71 6c  nterface.** [sql
25c10 69 74 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28  ite3_prepare_v2(
25c20 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f  )] and [sqlite3_
25c30 70 72 65 70 61 72 65 31 36 5f 76 32 28 29 5d 20  prepare16_v2()] 
25c40 6f 72 20 74 68 65 20 6f 6c 64 65 72 20 6c 65 67  or the older leg
25c50 61 63 79 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  acy.** interface
25c60 20 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72   [sqlite3_prepar
25c70 65 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65  e()] and [sqlite
25c80 33 5f 70 72 65 70 61 72 65 31 36 28 29 5d 2e 20  3_prepare16()]. 
25c90 20 54 68 65 20 75 73 65 20 6f 66 20 74 68 65 0a   The use of the.
25ca0 2a 2a 20 6e 65 77 20 22 76 32 22 20 69 6e 74 65  ** new "v2" inte
25cb0 72 66 61 63 65 20 69 73 20 72 65 63 6f 6d 6d 65  rface is recomme
25cc0 6e 64 65 64 20 66 6f 72 20 6e 65 77 20 61 70 70  nded for new app
25cd0 6c 69 63 61 74 69 6f 6e 73 20 62 75 74 20 74 68  lications but th
25ce0 65 20 6c 65 67 61 63 79 0a 2a 2a 20 69 6e 74 65  e legacy.** inte
25cf0 72 66 61 63 65 20 77 69 6c 6c 20 63 6f 6e 74 69  rface will conti
25d00 6e 75 65 20 74 6f 20 62 65 20 73 75 70 70 6f 72  nue to be suppor
25d10 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 49 6e 20 74  ted..**.** ^In t
25d20 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65 72 66  he legacy interf
25d30 61 63 65 2c 20 74 68 65 20 72 65 74 75 72 6e 20  ace, the return 
25d40 76 61 6c 75 65 20 77 69 6c 6c 20 62 65 20 65 69  value will be ei
25d50 74 68 65 72 20 5b 53 51 4c 49 54 45 5f 42 55 53  ther [SQLITE_BUS
25d60 59 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 44  Y],.** [SQLITE_D
25d70 4f 4e 45 5d 2c 20 5b 53 51 4c 49 54 45 5f 52 4f  ONE], [SQLITE_RO
25d80 57 5d 2c 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f  W], [SQLITE_ERRO
25d90 52 5d 2c 20 6f 72 20 5b 53 51 4c 49 54 45 5f 4d  R], or [SQLITE_M
25da0 49 53 55 53 45 5d 2e 0a 2a 2a 20 5e 57 69 74 68  ISUSE]..** ^With
25db0 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66   the "v2" interf
25dc0 61 63 65 2c 20 61 6e 79 20 6f 66 20 74 68 65 20  ace, any of the 
25dd0 6f 74 68 65 72 20 5b 72 65 73 75 6c 74 20 63 6f  other [result co
25de0 64 65 73 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65  des] or.** [exte
25df0 6e 64 65 64 20 72 65 73 75 6c 74 20 63 6f 64 65  nded result code
25e00 73 5d 20 6d 69 67 68 74 20 62 65 20 72 65 74 75  s] might be retu
25e10 72 6e 65 64 20 61 73 20 77 65 6c 6c 2e 0a 2a 2a  rned as well..**
25e20 0a 2a 2a 20 5e 5b 53 51 4c 49 54 45 5f 42 55 53  .** ^[SQLITE_BUS
25e30 59 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68  Y] means that th
25e40 65 20 64 61 74 61 62 61 73 65 20 65 6e 67 69 6e  e database engin
25e50 65 20 77 61 73 20 75 6e 61 62 6c 65 20 74 6f 20  e was unable to 
25e60 61 63 71 75 69 72 65 20 74 68 65 0a 2a 2a 20 64  acquire the.** d
25e70 61 74 61 62 61 73 65 20 6c 6f 63 6b 73 20 69 74  atabase locks it
25e80 20 6e 65 65 64 73 20 74 6f 20 64 6f 20 69 74 73   needs to do its
25e90 20 6a 6f 62 2e 20 20 5e 49 66 20 74 68 65 20 73   job.  ^If the s
25ea0 74 61 74 65 6d 65 6e 74 20 69 73 20 61 20 5b 43  tatement is a [C
25eb0 4f 4d 4d 49 54 5d 0a 2a 2a 20 6f 72 20 6f 63 63  OMMIT].** or occ
25ec0 75 72 73 20 6f 75 74 73 69 64 65 20 6f 66 20 61  urs outside of a
25ed0 6e 20 65 78 70 6c 69 63 69 74 20 74 72 61 6e 73  n explicit trans
25ee0 61 63 74 69 6f 6e 2c 20 74 68 65 6e 20 79 6f 75  action, then you
25ef0 20 63 61 6e 20 72 65 74 72 79 20 74 68 65 0a 2a   can retry the.*
25f00 2a 20 73 74 61 74 65 6d 65 6e 74 2e 20 20 49 66  * statement.  If
25f10 20 74 68 65 20 73 74 61 74 65 6d 65 6e 74 20 69   the statement i
25f20 73 20 6e 6f 74 20 61 20 5b 43 4f 4d 4d 49 54 5d  s not a [COMMIT]
25f30 20 61 6e 64 20 6f 63 63 75 72 73 20 77 69 74 68   and occurs with
25f40 69 6e 20 61 0a 2a 2a 20 65 78 70 6c 69 63 69 74  in a.** explicit
25f50 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 74 68 65   transaction the
25f60 6e 20 79 6f 75 20 73 68 6f 75 6c 64 20 72 6f 6c  n you should rol
25f70 6c 62 61 63 6b 20 74 68 65 20 74 72 61 6e 73 61  lback the transa
25f80 63 74 69 6f 6e 20 62 65 66 6f 72 65 0a 2a 2a 20  ction before.** 
25f90 63 6f 6e 74 69 6e 75 69 6e 67 2e 0a 2a 2a 0a 2a  continuing..**.*
25fa0 2a 20 5e 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  * ^[SQLITE_DONE]
25fb0 20 6d 65 61 6e 73 20 74 68 61 74 20 74 68 65 20   means that the 
25fc0 73 74 61 74 65 6d 65 6e 74 20 68 61 73 20 66 69  statement has fi
25fd0 6e 69 73 68 65 64 20 65 78 65 63 75 74 69 6e 67  nished executing
25fe0 0a 2a 2a 20 73 75 63 63 65 73 73 66 75 6c 6c 79  .** successfully
25ff0 2e 20 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28  .  sqlite3_step(
26000 29 20 73 68 6f 75 6c 64 20 6e 6f 74 20 62 65 20  ) should not be 
26010 63 61 6c 6c 65 64 20 61 67 61 69 6e 20 6f 6e 20  called again on 
26020 74 68 69 73 20 76 69 72 74 75 61 6c 0a 2a 2a 20  this virtual.** 
26030 6d 61 63 68 69 6e 65 20 77 69 74 68 6f 75 74 20  machine without 
26040 66 69 72 73 74 20 63 61 6c 6c 69 6e 67 20 5b 73  first calling [s
26050 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
26060 74 6f 20 72 65 73 65 74 20 74 68 65 20 76 69 72  to reset the vir
26070 74 75 61 6c 0a 2a 2a 20 6d 61 63 68 69 6e 65 20  tual.** machine 
26080 62 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74  back to its init
26090 69 61 6c 20 73 74 61 74 65 2e 0a 2a 2a 0a 2a 2a  ial state..**.**
260a0 20 5e 49 66 20 74 68 65 20 53 51 4c 20 73 74 61   ^If the SQL sta
260b0 74 65 6d 65 6e 74 20 62 65 69 6e 67 20 65 78 65  tement being exe
260c0 63 75 74 65 64 20 72 65 74 75 72 6e 73 20 61 6e  cuted returns an
260d0 79 20 64 61 74 61 2c 20 74 68 65 6e 20 5b 53 51  y data, then [SQ
260e0 4c 49 54 45 5f 52 4f 57 5d 0a 2a 2a 20 69 73 20  LITE_ROW].** is 
260f0 72 65 74 75 72 6e 65 64 20 65 61 63 68 20 74 69  returned each ti
26100 6d 65 20 61 20 6e 65 77 20 72 6f 77 20 6f 66 20  me a new row of 
26110 64 61 74 61 20 69 73 20 72 65 61 64 79 20 66 6f  data is ready fo
26120 72 20 70 72 6f 63 65 73 73 69 6e 67 20 62 79 20  r processing by 
26130 74 68 65 0a 2a 2a 20 63 61 6c 6c 65 72 2e 20 54  the.** caller. T
26140 68 65 20 76 61 6c 75 65 73 20 6d 61 79 20 62 65  he values may be
26150 20 61 63 63 65 73 73 65 64 20 75 73 69 6e 67 20   accessed using 
26160 74 68 65 20 5b 63 6f 6c 75 6d 6e 20 61 63 63 65  the [column acce
26170 73 73 20 66 75 6e 63 74 69 6f 6e 73 5d 2e 0a 2a  ss functions]..*
26180 2a 20 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29  * sqlite3_step()
26190 20 69 73 20 63 61 6c 6c 65 64 20 61 67 61 69 6e   is called again
261a0 20 74 6f 20 72 65 74 72 69 65 76 65 20 74 68 65   to retrieve the
261b0 20 6e 65 78 74 20 72 6f 77 20 6f 66 20 64 61 74   next row of dat
261c0 61 2e 0a 2a 2a 0a 2a 2a 20 5e 5b 53 51 4c 49 54  a..**.** ^[SQLIT
261d0 45 5f 45 52 52 4f 52 5d 20 6d 65 61 6e 73 20 74  E_ERROR] means t
261e0 68 61 74 20 61 20 72 75 6e 2d 74 69 6d 65 20 65  hat a run-time e
261f0 72 72 6f 72 20 28 73 75 63 68 20 61 73 20 61 20  rror (such as a 
26200 63 6f 6e 73 74 72 61 69 6e 74 0a 2a 2a 20 76 69  constraint.** vi
26210 6f 6c 61 74 69 6f 6e 29 20 68 61 73 20 6f 63 63  olation) has occ
26220 75 72 72 65 64 2e 20 20 73 71 6c 69 74 65 33 5f  urred.  sqlite3_
26230 73 74 65 70 28 29 20 73 68 6f 75 6c 64 20 6e 6f  step() should no
26240 74 20 62 65 20 63 61 6c 6c 65 64 20 61 67 61 69  t be called agai
26250 6e 20 6f 6e 0a 2a 2a 20 74 68 65 20 56 4d 2e 20  n on.** the VM. 
26260 4d 6f 72 65 20 69 6e 66 6f 72 6d 61 74 69 6f 6e  More information
26270 20 6d 61 79 20 62 65 20 66 6f 75 6e 64 20 62 79   may be found by
26280 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74 65   calling [sqlite
26290 33 5f 65 72 72 6d 73 67 28 29 5d 2e 0a 2a 2a 20  3_errmsg()]..** 
262a0 5e 57 69 74 68 20 74 68 65 20 6c 65 67 61 63 79  ^With the legacy
262b0 20 69 6e 74 65 72 66 61 63 65 2c 20 61 20 6d 6f   interface, a mo
262c0 72 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f  re specific erro
262d0 72 20 63 6f 64 65 20 28 66 6f 72 20 65 78 61 6d  r code (for exam
262e0 70 6c 65 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f  ple,.** [SQLITE_
262f0 49 4e 54 45 52 52 55 50 54 5d 2c 20 5b 53 51 4c  INTERRUPT], [SQL
26300 49 54 45 5f 53 43 48 45 4d 41 5d 2c 20 5b 53 51  ITE_SCHEMA], [SQ
26310 4c 49 54 45 5f 43 4f 52 52 55 50 54 5d 2c 20 61  LITE_CORRUPT], a
26320 6e 64 20 73 6f 20 66 6f 72 74 68 29 0a 2a 2a 20  nd so forth).** 
26330 63 61 6e 20 62 65 20 6f 62 74 61 69 6e 65 64 20  can be obtained 
26340 62 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69  by calling [sqli
26350 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f 6e 20  te3_reset()] on 
26360 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64  the.** [prepared
26370 20 73 74 61 74 65 6d 65 6e 74 5d 2e 20 20 5e 49   statement].  ^I
26380 6e 20 74 68 65 20 22 76 32 22 20 69 6e 74 65 72  n the "v2" inter
26390 66 61 63 65 2c 0a 2a 2a 20 74 68 65 20 6d 6f 72  face,.** the mor
263a0 65 20 73 70 65 63 69 66 69 63 20 65 72 72 6f 72  e specific error
263b0 20 63 6f 64 65 20 69 73 20 72 65 74 75 72 6e 65   code is returne
263c0 64 20 64 69 72 65 63 74 6c 79 20 62 79 20 73 71  d directly by sq
263d0 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 0a 2a 2a  lite3_step()..**
263e0 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4d 49 53 55  .** [SQLITE_MISU
263f0 53 45 5d 20 6d 65 61 6e 73 20 74 68 61 74 20 74  SE] means that t
26400 68 65 20 74 68 69 73 20 72 6f 75 74 69 6e 65 20  he this routine 
26410 77 61 73 20 63 61 6c 6c 65 64 20 69 6e 61 70 70  was called inapp
26420 72 6f 70 72 69 61 74 65 6c 79 2e 0a 2a 2a 20 50  ropriately..** P
26430 65 72 68 61 70 73 20 69 74 20 77 61 73 20 63 61  erhaps it was ca
26440 6c 6c 65 64 20 6f 6e 20 61 20 5b 70 72 65 70 61  lled on a [prepa
26450 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 74  red statement] t
26460 68 61 74 20 68 61 73 0a 2a 2a 20 61 6c 72 65 61  hat has.** alrea
26470 64 79 20 62 65 65 6e 20 5b 73 71 6c 69 74 65 33  dy been [sqlite3
26480 5f 66 69 6e 61 6c 69 7a 65 20 7c 20 66 69 6e 61  _finalize | fina
26490 6c 69 7a 65 64 5d 20 6f 72 20 6f 6e 20 6f 6e 65  lized] or on one
264a0 20 74 68 61 74 20 68 61 64 0a 2a 2a 20 70 72 65   that had.** pre
264b0 76 69 6f 75 73 6c 79 20 72 65 74 75 72 6e 65 64  viously returned
264c0 20 5b 53 51 4c 49 54 45 5f 45 52 52 4f 52 5d 20   [SQLITE_ERROR] 
264d0 6f 72 20 5b 53 51 4c 49 54 45 5f 44 4f 4e 45 5d  or [SQLITE_DONE]
264e0 2e 20 20 4f 72 20 69 74 20 63 6f 75 6c 64 0a 2a  .  Or it could.*
264f0 2a 20 62 65 20 74 68 65 20 63 61 73 65 20 74 68  * be the case th
26500 61 74 20 74 68 65 20 73 61 6d 65 20 64 61 74 61  at the same data
26510 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  base connection 
26520 69 73 20 62 65 69 6e 67 20 75 73 65 64 20 62 79  is being used by
26530 20 74 77 6f 20 6f 72 0a 2a 2a 20 6d 6f 72 65 20   two or.** more 
26540 74 68 72 65 61 64 73 20 61 74 20 74 68 65 20 73  threads at the s
26550 61 6d 65 20 6d 6f 6d 65 6e 74 20 69 6e 20 74 69  ame moment in ti
26560 6d 65 2e 0a 2a 2a 0a 2a 2a 20 46 6f 72 20 61 6c  me..**.** For al
26570 6c 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51  l versions of SQ
26580 4c 69 74 65 20 75 70 20 74 6f 20 61 6e 64 20 69  Lite up to and i
26590 6e 63 6c 75 64 69 6e 67 20 33 2e 36 2e 32 33 2e  ncluding 3.6.23.
265a0 31 2c 20 61 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20  1, a call to.** 
265b0 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29  [sqlite3_reset()
265c0 5d 20 77 61 73 20 72 65 71 75 69 72 65 64 20 61  ] was required a
265d0 66 74 65 72 20 73 71 6c 69 74 65 33 5f 73 74 65  fter sqlite3_ste
265e0 70 28 29 20 72 65 74 75 72 6e 65 64 20 61 6e 79  p() returned any
265f0 74 68 69 6e 67 0a 2a 2a 20 6f 74 68 65 72 20 74  thing.** other t
26600 68 61 6e 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d  han [SQLITE_ROW]
26610 20 62 65 66 6f 72 65 20 61 6e 79 20 73 75 62 73   before any subs
26620 65 71 75 65 6e 74 20 69 6e 76 6f 63 61 74 69 6f  equent invocatio
26630 6e 20 6f 66 0a 2a 2a 20 73 71 6c 69 74 65 33 5f  n of.** sqlite3_
26640 73 74 65 70 28 29 2e 20 20 46 61 69 6c 75 72 65  step().  Failure
26650 20 74 6f 20 72 65 73 65 74 20 74 68 65 20 70 72   to reset the pr
26660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
26670 20 75 73 69 6e 67 20 0a 2a 2a 20 5b 73 71 6c 69   using .** [sqli
26680 74 65 33 5f 72 65 73 65 74 28 29 5d 20 77 6f 75  te3_reset()] wou
26690 6c 64 20 72 65 73 75 6c 74 20 69 6e 20 61 6e 20  ld result in an 
266a0 5b 53 51 4c 49 54 45 5f 4d 49 53 55 53 45 5d 20  [SQLITE_MISUSE] 
266b0 72 65 74 75 72 6e 20 66 72 6f 6d 0a 2a 2a 20 73  return from.** s
266c0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 2e 20 20  qlite3_step().  
266d0 42 75 74 20 61 66 74 65 72 20 76 65 72 73 69 6f  But after versio
266e0 6e 20 33 2e 36 2e 32 33 2e 31 2c 20 73 71 6c 69  n 3.6.23.1, sqli
266f0 74 65 33 5f 73 74 65 70 28 29 20 62 65 67 61 6e  te3_step() began
26700 0a 2a 2a 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c  .** calling [sql
26710 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 61 75  ite3_reset()] au
26720 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 20 74  tomatically in t
26730 68 69 73 20 63 69 72 63 75 6d 73 74 61 6e 63 65  his circumstance
26740 20 72 61 74 68 65 72 0a 2a 2a 20 74 68 61 6e 20   rather.** than 
26750 72 65 74 75 72 6e 69 6e 67 20 5b 53 51 4c 49 54  returning [SQLIT
26760 45 5f 4d 49 53 55 53 45 5d 2e 20 20 54 68 69 73  E_MISUSE].  This
26770 20 69 73 20 6e 6f 74 20 63 6f 6e 73 69 64 65 72   is not consider
26780 65 64 20 61 20 63 6f 6d 70 61 74 69 62 69 6c 69  ed a compatibili
26790 74 79 0a 2a 2a 20 62 72 65 61 6b 20 62 65 63 61  ty.** break beca
267a0 75 73 65 20 61 6e 79 20 61 70 70 6c 69 63 61 74  use any applicat
267b0 69 6f 6e 20 74 68 61 74 20 65 76 65 72 20 72 65  ion that ever re
267c0 63 65 69 76 65 73 20 61 6e 20 53 51 4c 49 54 45  ceives an SQLITE
267d0 5f 4d 49 53 55 53 45 20 65 72 72 6f 72 0a 2a 2a  _MISUSE error.**
267e0 20 69 73 20 62 72 6f 6b 65 6e 20 62 79 20 64 65   is broken by de
267f0 66 69 6e 69 74 69 6f 6e 2e 20 20 54 68 65 20 5b  finition.  The [
26800 53 51 4c 49 54 45 5f 4f 4d 49 54 5f 41 55 54 4f  SQLITE_OMIT_AUTO
26810 52 45 53 45 54 5d 20 63 6f 6d 70 69 6c 65 2d 74  RESET] compile-t
26820 69 6d 65 20 6f 70 74 69 6f 6e 0a 2a 2a 20 63 61  ime option.** ca
26830 6e 20 62 65 20 75 73 65 64 20 74 6f 20 72 65 73  n be used to res
26840 74 6f 72 65 20 74 68 65 20 6c 65 67 61 63 79 20  tore the legacy 
26850 62 65 68 61 76 69 6f 72 2e 0a 2a 2a 0a 2a 2a 20  behavior..**.** 
26860 3c 62 3e 47 6f 6f 66 79 20 49 6e 74 65 72 66 61  <b>Goofy Interfa
26870 63 65 20 41 6c 65 72 74 3a 3c 2f 62 3e 20 49 6e  ce Alert:</b> In
26880 20 74 68 65 20 6c 65 67 61 63 79 20 69 6e 74 65   the legacy inte
26890 72 66 61 63 65 2c 20 74 68 65 20 73 71 6c 69 74  rface, the sqlit
268a0 65 33 5f 73 74 65 70 28 29 0a 2a 2a 20 41 50 49  e3_step().** API
268b0 20 61 6c 77 61 79 73 20 72 65 74 75 72 6e 73 20   always returns 
268c0 61 20 67 65 6e 65 72 69 63 20 65 72 72 6f 72 20  a generic error 
268d0 63 6f 64 65 2c 20 5b 53 51 4c 49 54 45 5f 45 52  code, [SQLITE_ER
268e0 52 4f 52 5d 2c 20 66 6f 6c 6c 6f 77 69 6e 67 20  ROR], following 
268f0 61 6e 79 0a 2a 2a 20 65 72 72 6f 72 20 6f 74 68  any.** error oth
26900 65 72 20 74 68 61 6e 20 5b 53 51 4c 49 54 45 5f  er than [SQLITE_
26910 42 55 53 59 5d 20 61 6e 64 20 5b 53 51 4c 49 54  BUSY] and [SQLIT
26920 45 5f 4d 49 53 55 53 45 5d 2e 20 20 59 6f 75 20  E_MISUSE].  You 
26930 6d 75 73 74 20 63 61 6c 6c 0a 2a 2a 20 5b 73 71  must call.** [sq
26940 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20 6f  lite3_reset()] o
26950 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c  r [sqlite3_final
26960 69 7a 65 28 29 5d 20 69 6e 20 6f 72 64 65 72 20  ize()] in order 
26970 74 6f 20 66 69 6e 64 20 6f 6e 65 20 6f 66 20 74  to find one of t
26980 68 65 0a 2a 2a 20 73 70 65 63 69 66 69 63 20 5b  he.** specific [
26990 65 72 72 6f 72 20 63 6f 64 65 73 5d 20 74 68 61  error codes] tha
269a0 74 20 62 65 74 74 65 72 20 64 65 73 63 72 69 62  t better describ
269b0 65 73 20 74 68 65 20 65 72 72 6f 72 2e 0a 2a 2a  es the error..**
269c0 20 57 65 20 61 64 6d 69 74 20 74 68 61 74 20 74   We admit that t
269d0 68 69 73 20 69 73 20 61 20 67 6f 6f 66 79 20 64  his is a goofy d
269e0 65 73 69 67 6e 2e 20 20 54 68 65 20 70 72 6f 62  esign.  The prob
269f0 6c 65 6d 20 68 61 73 20 62 65 65 6e 20 66 69 78  lem has been fix
26a00 65 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 22  ed.** with the "
26a10 76 32 22 20 69 6e 74 65 72 66 61 63 65 2e 20 20  v2" interface.  
26a20 49 66 20 79 6f 75 20 70 72 65 70 61 72 65 20 61  If you prepare a
26a30 6c 6c 20 6f 66 20 79 6f 75 72 20 53 51 4c 20 73  ll of your SQL s
26a40 74 61 74 65 6d 65 6e 74 73 0a 2a 2a 20 75 73 69  tatements.** usi
26a50 6e 67 20 65 69 74 68 65 72 20 5b 73 71 6c 69 74  ng either [sqlit
26a60 65 33 5f 70 72 65 70 61 72 65 5f 76 32 28 29 5d  e3_prepare_v2()]
26a70 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 70 72 65   or [sqlite3_pre
26a80 70 61 72 65 31 36 5f 76 32 28 29 5d 20 69 6e 73  pare16_v2()] ins
26a90 74 65 61 64 0a 2a 2a 20 6f 66 20 74 68 65 20 6c  tead.** of the l
26aa0 65 67 61 63 79 20 5b 73 71 6c 69 74 65 33 5f 70  egacy [sqlite3_p
26ab0 72 65 70 61 72 65 28 29 5d 20 61 6e 64 20 5b 73  repare()] and [s
26ac0 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65 31 36  qlite3_prepare16
26ad0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 73 2c 0a  ()] interfaces,.
26ae0 2a 2a 20 74 68 65 6e 20 74 68 65 20 6d 6f 72 65  ** then the more
26af0 20 73 70 65 63 69 66 69 63 20 5b 65 72 72 6f 72   specific [error
26b00 20 63 6f 64 65 73 5d 20 61 72 65 20 72 65 74 75   codes] are retu
26b10 72 6e 65 64 20 64 69 72 65 63 74 6c 79 0a 2a 2a  rned directly.**
26b20 20 62 79 20 73 71 6c 69 74 65 33 5f 73 74 65 70   by sqlite3_step
26b30 28 29 2e 20 20 54 68 65 20 75 73 65 20 6f 66 20  ().  The use of 
26b40 74 68 65 20 22 76 32 22 20 69 6e 74 65 72 66 61  the "v2" interfa
26b50 63 65 20 69 73 20 72 65 63 6f 6d 6d 65 6e 64 65  ce is recommende
26b60 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65  d..*/.int sqlite
26b70 33 5f 73 74 65 70 28 73 71 6c 69 74 65 33 5f 73  3_step(sqlite3_s
26b80 74 6d 74 2a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41  tmt*);../*.** CA
26b90 50 49 33 52 45 46 3a 20 4e 75 6d 62 65 72 20 6f  PI3REF: Number o
26ba0 66 20 63 6f 6c 75 6d 6e 73 20 69 6e 20 61 20 72  f columns in a r
26bb0 65 73 75 6c 74 20 73 65 74 0a 2a 2a 0a 2a 2a 20  esult set.**.** 
26bc0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64 61 74  ^The sqlite3_dat
26bd0 61 5f 63 6f 75 6e 74 28 50 29 20 69 6e 74 65 72  a_count(P) inter
26be0 66 61 63 65 20 72 65 74 75 72 6e 73 20 74 68 65  face returns the
26bf0 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75 6d   number of colum
26c00 6e 73 20 69 6e 20 74 68 65 0a 2a 2a 20 63 75 72  ns in the.** cur
26c10 72 65 6e 74 20 72 6f 77 20 6f 66 20 74 68 65 20  rent row of the 
26c20 72 65 73 75 6c 74 20 73 65 74 20 6f 66 20 5b 70  result set of [p
26c30 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
26c40 74 5d 20 50 2e 0a 2a 2a 20 5e 49 66 20 70 72 65  t] P..** ^If pre
26c50 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20  pared statement 
26c60 50 20 64 6f 65 73 20 6e 6f 74 20 68 61 76 65 20  P does not have 
26c70 72 65 73 75 6c 74 73 20 72 65 61 64 79 20 74 6f  results ready to
26c80 20 72 65 74 75 72 6e 0a 2a 2a 20 28 76 69 61 20   return.** (via 
26c90 63 61 6c 6c 73 20 74 6f 20 74 68 65 20 5b 73 71  calls to the [sq
26ca0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74  lite3_column_int
26cb0 20 7c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d   | sqlite3_colum
26cc0 6e 5f 2a 28 29 5d 20 6f 66 0a 2a 2a 20 69 6e 74  n_*()] of.** int
26cd0 65 72 66 61 63 65 73 29 20 74 68 65 6e 20 73 71  erfaces) then sq
26ce0 6c 69 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74  lite3_data_count
26cf0 28 50 29 20 72 65 74 75 72 6e 73 20 30 2e 0a 2a  (P) returns 0..*
26d00 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 64  * ^The sqlite3_d
26d10 61 74 61 5f 63 6f 75 6e 74 28 50 29 20 72 6f 75  ata_count(P) rou
26d20 74 69 6e 65 20 61 6c 73 6f 20 72 65 74 75 72 6e  tine also return
26d30 73 20 30 20 69 66 20 50 20 69 73 20 61 20 4e 55  s 0 if P is a NU
26d40 4c 4c 20 70 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a  LL pointer..**.*
26d50 2a 20 53 65 65 20 61 6c 73 6f 3a 20 5b 73 71 6c  * See also: [sql
26d60 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75 6e  ite3_column_coun
26d70 74 28 29 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  t()].*/.int sqli
26d80 74 65 33 5f 64 61 74 61 5f 63 6f 75 6e 74 28 73  te3_data_count(s
26d90 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
26da0 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
26db0 33 52 45 46 3a 20 46 75 6e 64 61 6d 65 6e 74 61  3REF: Fundamenta
26dc0 6c 20 44 61 74 61 74 79 70 65 73 0a 2a 2a 20 4b  l Datatypes.** K
26dd0 45 59 57 4f 52 44 53 3a 20 53 51 4c 49 54 45 5f  EYWORDS: SQLITE_
26de0 54 45 58 54 0a 2a 2a 0a 2a 2a 20 5e 28 45 76 65  TEXT.**.** ^(Eve
26df0 72 79 20 76 61 6c 75 65 20 69 6e 20 53 51 4c 69  ry value in SQLi
26e00 74 65 20 68 61 73 20 6f 6e 65 20 6f 66 20 66 69  te has one of fi
26e10 76 65 20 66 75 6e 64 61 6d 65 6e 74 61 6c 20 64  ve fundamental d
26e20 61 74 61 74 79 70 65 73 3a 0a 2a 2a 0a 2a 2a 20  atatypes:.**.** 
26e30 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d  <ul>.** <li> 64-
26e40 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
26e50 65 72 0a 2a 2a 20 3c 6c 69 3e 20 36 34 2d 62 69  er.** <li> 64-bi
26e60 74 20 49 45 45 45 20 66 6c 6f 61 74 69 6e 67 20  t IEEE floating 
26e70 70 6f 69 6e 74 20 6e 75 6d 62 65 72 0a 2a 2a 20  point number.** 
26e80 3c 6c 69 3e 20 73 74 72 69 6e 67 0a 2a 2a 20 3c  <li> string.** <
26e90 6c 69 3e 20 42 4c 4f 42 0a 2a 2a 20 3c 6c 69 3e  li> BLOB.** <li>
26ea0 20 4e 55 4c 4c 0a 2a 2a 20 3c 2f 75 6c 3e 29 5e   NULL.** </ul>)^
26eb0 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20 63 6f 6e  .**.** These con
26ec0 73 74 61 6e 74 73 20 61 72 65 20 63 6f 64 65 73  stants are codes
26ed0 20 66 6f 72 20 65 61 63 68 20 6f 66 20 74 68 6f   for each of tho
26ee0 73 65 20 74 79 70 65 73 2e 0a 2a 2a 0a 2a 2a 20  se types..**.** 
26ef0 4e 6f 74 65 20 74 68 61 74 20 74 68 65 20 53 51  Note that the SQ
26f00 4c 49 54 45 5f 54 45 58 54 20 63 6f 6e 73 74 61  LITE_TEXT consta
26f10 6e 74 20 77 61 73 20 61 6c 73 6f 20 75 73 65 64  nt was also used
26f20 20 69 6e 20 53 51 4c 69 74 65 20 76 65 72 73 69   in SQLite versi
26f30 6f 6e 20 32 0a 2a 2a 20 66 6f 72 20 61 20 63 6f  on 2.** for a co
26f40 6d 70 6c 65 74 65 6c 79 20 64 69 66 66 65 72 65  mpletely differe
26f50 6e 74 20 6d 65 61 6e 69 6e 67 2e 20 20 53 6f 66  nt meaning.  Sof
26f60 74 77 61 72 65 20 74 68 61 74 20 6c 69 6e 6b 73  tware that links
26f70 20 61 67 61 69 6e 73 74 20 62 6f 74 68 0a 2a 2a   against both.**
26f80 20 53 51 4c 69 74 65 20 76 65 72 73 69 6f 6e 20   SQLite version 
26f90 32 20 61 6e 64 20 53 51 4c 69 74 65 20 76 65 72  2 and SQLite ver
26fa0 73 69 6f 6e 20 33 20 73 68 6f 75 6c 64 20 75 73  sion 3 should us
26fb0 65 20 53 51 4c 49 54 45 33 5f 54 45 58 54 2c 20  e SQLITE3_TEXT, 
26fc0 6e 6f 74 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 45  not.** SQLITE_TE
26fd0 58 54 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  XT..*/.#define S
26fe0 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 20 31  QLITE_INTEGER  1
26ff0 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
27000 46 4c 4f 41 54 20 20 20 20 32 0a 23 64 65 66 69  FLOAT    2.#defi
27010 6e 65 20 53 51 4c 49 54 45 5f 42 4c 4f 42 20 20  ne SQLITE_BLOB  
27020 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53 51 4c     4.#define SQL
27030 49 54 45 5f 4e 55 4c 4c 20 20 20 20 20 35 0a 23  ITE_NULL     5.#
27040 69 66 64 65 66 20 53 51 4c 49 54 45 5f 54 45 58  ifdef SQLITE_TEX
27050 54 0a 23 20 75 6e 64 65 66 20 53 51 4c 49 54 45  T.# undef SQLITE
27060 5f 54 45 58 54 0a 23 65 6c 73 65 0a 23 20 64 65  _TEXT.#else.# de
27070 66 69 6e 65 20 53 51 4c 49 54 45 5f 54 45 58 54  fine SQLITE_TEXT
27080 20 20 20 20 20 33 0a 23 65 6e 64 69 66 0a 23 64       3.#endif.#d
27090 65 66 69 6e 65 20 53 51 4c 49 54 45 33 5f 54 45  efine SQLITE3_TE
270a0 58 54 20 20 20 20 20 33 0a 0a 2f 2a 0a 2a 2a 20  XT     3../*.** 
270b0 43 41 50 49 33 52 45 46 3a 20 52 65 73 75 6c 74  CAPI3REF: Result
270c0 20 56 61 6c 75 65 73 20 46 72 6f 6d 20 41 20 51   Values From A Q
270d0 75 65 72 79 0a 2a 2a 20 4b 45 59 57 4f 52 44 53  uery.** KEYWORDS
270e0 3a 20 7b 63 6f 6c 75 6d 6e 20 61 63 63 65 73 73  : {column access
270f0 20 66 75 6e 63 74 69 6f 6e 73 7d 0a 2a 2a 0a 2a   functions}.**.*
27100 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
27110 20 66 6f 72 6d 20 74 68 65 20 22 72 65 73 75 6c   form the "resul
27120 74 20 73 65 74 22 20 69 6e 74 65 72 66 61 63 65  t set" interface
27130 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72  ..**.** ^These r
27140 6f 75 74 69 6e 65 73 20 72 65 74 75 72 6e 20 69  outines return i
27150 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75 74  nformation about
27160 20 61 20 73 69 6e 67 6c 65 20 63 6f 6c 75 6d 6e   a single column
27170 20 6f 66 20 74 68 65 20 63 75 72 72 65 6e 74 0a   of the current.
27180 2a 2a 20 72 65 73 75 6c 74 20 72 6f 77 20 6f 66  ** result row of
27190 20 61 20 71 75 65 72 79 2e 20 20 5e 49 6e 20 65   a query.  ^In e
271a0 76 65 72 79 20 63 61 73 65 20 74 68 65 20 66 69  very case the fi
271b0 72 73 74 20 61 72 67 75 6d 65 6e 74 20 69 73 20  rst argument is 
271c0 61 20 70 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20  a pointer.** to 
271d0 74 68 65 20 5b 70 72 65 70 61 72 65 64 20 73 74  the [prepared st
271e0 61 74 65 6d 65 6e 74 5d 20 74 68 61 74 20 69 73  atement] that is
271f0 20 62 65 69 6e 67 20 65 76 61 6c 75 61 74 65 64   being evaluated
27200 20 28 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 73   (the [sqlite3_s
27210 74 6d 74 2a 5d 0a 2a 2a 20 74 68 61 74 20 77 61  tmt*].** that wa
27220 73 20 72 65 74 75 72 6e 65 64 20 66 72 6f 6d 20  s returned from 
27230 5b 73 71 6c 69 74 65 33 5f 70 72 65 70 61 72 65  [sqlite3_prepare
27240 5f 76 32 28 29 5d 20 6f 72 20 6f 6e 65 20 6f 66  _v2()] or one of
27250 20 69 74 73 20 76 61 72 69 61 6e 74 73 29 0a 2a   its variants).*
27260 2a 20 61 6e 64 20 74 68 65 20 73 65 63 6f 6e 64  * and the second
27270 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74 68 65   argument is the
27280 20 69 6e 64 65 78 20 6f 66 20 74 68 65 20 63 6f   index of the co
27290 6c 75 6d 6e 20 66 6f 72 20 77 68 69 63 68 20 69  lumn for which i
272a0 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 73 68  nformation.** sh
272b0 6f 75 6c 64 20 62 65 20 72 65 74 75 72 6e 65 64  ould be returned
272c0 2e 20 5e 54 68 65 20 6c 65 66 74 6d 6f 73 74 20  . ^The leftmost 
272d0 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65 20 72 65  column of the re
272e0 73 75 6c 74 20 73 65 74 20 68 61 73 20 74 68 65  sult set has the
272f0 20 69 6e 64 65 78 20 30 2e 0a 2a 2a 20 5e 54 68   index 0..** ^Th
27300 65 20 6e 75 6d 62 65 72 20 6f 66 20 63 6f 6c 75  e number of colu
27310 6d 6e 73 20 69 6e 20 74 68 65 20 72 65 73 75 6c  mns in the resul
27320 74 20 63 61 6e 20 62 65 20 64 65 74 65 72 6d 69  t can be determi
27330 6e 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71  ned using.** [sq
27340 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 63 6f 75  lite3_column_cou
27350 6e 74 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20  nt()]..**.** If 
27360 74 68 65 20 53 51 4c 20 73 74 61 74 65 6d 65 6e  the SQL statemen
27370 74 20 64 6f 65 73 20 6e 6f 74 20 63 75 72 72 65  t does not curre
27380 6e 74 6c 79 20 70 6f 69 6e 74 20 74 6f 20 61 20  ntly point to a 
27390 76 61 6c 69 64 20 72 6f 77 2c 20 6f 72 20 69 66  valid row, or if
273a0 20 74 68 65 0a 2a 2a 20 63 6f 6c 75 6d 6e 20 69   the.** column i
273b0 6e 64 65 78 20 69 73 20 6f 75 74 20 6f 66 20 72  ndex is out of r
273c0 61 6e 67 65 2c 20 74 68 65 20 72 65 73 75 6c 74  ange, the result
273d0 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
273e0 2a 20 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73  * These routines
273f0 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 63 61 6c   may only be cal
27400 6c 65 64 20 77 68 65 6e 20 74 68 65 20 6d 6f 73  led when the mos
27410 74 20 72 65 63 65 6e 74 20 63 61 6c 6c 20 74 6f  t recent call to
27420 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 74 65  .** [sqlite3_ste
27430 70 28 29 5d 20 68 61 73 20 72 65 74 75 72 6e 65  p()] has returne
27440 64 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 20 61  d [SQLITE_ROW] a
27450 6e 64 20 6e 65 69 74 68 65 72 0a 2a 2a 20 5b 73  nd neither.** [s
27460 71 6c 69 74 65 33 5f 72 65 73 65 74 28 29 5d 20  qlite3_reset()] 
27470 6e 6f 72 20 5b 73 71 6c 69 74 65 33 5f 66 69 6e  nor [sqlite3_fin
27480 61 6c 69 7a 65 28 29 5d 20 68 61 76 65 20 62 65  alize()] have be
27490 65 6e 20 63 61 6c 6c 65 64 20 73 75 62 73 65 71  en called subseq
274a0 75 65 6e 74 6c 79 2e 0a 2a 2a 20 49 66 20 61 6e  uently..** If an
274b0 79 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69  y of these routi
274c0 6e 65 73 20 61 72 65 20 63 61 6c 6c 65 64 20 61  nes are called a
274d0 66 74 65 72 20 5b 73 71 6c 69 74 65 33 5f 72 65  fter [sqlite3_re
274e0 73 65 74 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71  set()] or.** [sq
274f0 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29  lite3_finalize()
27500 5d 20 6f 72 20 61 66 74 65 72 20 5b 73 71 6c 69  ] or after [sqli
27510 74 65 33 5f 73 74 65 70 28 29 5d 20 68 61 73 20  te3_step()] has 
27520 72 65 74 75 72 6e 65 64 0a 2a 2a 20 73 6f 6d 65  returned.** some
27530 74 68 69 6e 67 20 6f 74 68 65 72 20 74 68 61 6e  thing other than
27540 20 5b 53 51 4c 49 54 45 5f 52 4f 57 5d 2c 20 74   [SQLITE_ROW], t
27550 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
27560 6e 64 65 66 69 6e 65 64 2e 0a 2a 2a 20 49 66 20  ndefined..** If 
27570 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
27580 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73   or [sqlite3_res
27590 65 74 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65  et()] or [sqlite
275a0 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 0a 2a 2a  3_finalize()].**
275b0 20 61 72 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d   are called from
275c0 20 61 20 64 69 66 66 65 72 65 6e 74 20 74 68 72   a different thr
275d0 65 61 64 20 77 68 69 6c 65 20 61 6e 79 20 6f 66  ead while any of
275e0 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73 0a   these routines.
275f0 2a 2a 20 61 72 65 20 70 65 6e 64 69 6e 67 2c 20  ** are pending, 
27600 74 68 65 6e 20 74 68 65 20 72 65 73 75 6c 74 73  then the results
27610 20 61 72 65 20 75 6e 64 65 66 69 6e 65 64 2e 0a   are undefined..
27620 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
27630 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29  e3_column_type()
27640 20 72 6f 75 74 69 6e 65 20 72 65 74 75 72 6e 73   routine returns
27650 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f   the.** [SQLITE_
27660 49 4e 54 45 47 45 52 20 7c 20 64 61 74 61 74 79  INTEGER | dataty
27670 70 65 20 63 6f 64 65 5d 20 66 6f 72 20 74 68 65  pe code] for the
27680 20 69 6e 69 74 69 61 6c 20 64 61 74 61 20 74 79   initial data ty
27690 70 65 0a 2a 2a 20 6f 66 20 74 68 65 20 72 65 73  pe.** of the res
276a0 75 6c 74 20 63 6f 6c 75 6d 6e 2e 20 20 5e 54 68  ult column.  ^Th
276b0 65 20 72 65 74 75 72 6e 65 64 20 76 61 6c 75 65  e returned value
276c0 20 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49   is one of [SQLI
276d0 54 45 5f 49 4e 54 45 47 45 52 5d 2c 0a 2a 2a 20  TE_INTEGER],.** 
276e0 5b 53 51 4c 49 54 45 5f 46 4c 4f 41 54 5d 2c 20  [SQLITE_FLOAT], 
276f0 5b 53 51 4c 49 54 45 5f 54 45 58 54 5d 2c 20 5b  [SQLITE_TEXT], [
27700 53 51 4c 49 54 45 5f 42 4c 4f 42 5d 2c 20 6f 72  SQLITE_BLOB], or
27710 20 5b 53 51 4c 49 54 45 5f 4e 55 4c 4c 5d 2e 20   [SQLITE_NULL]. 
27720 20 54 68 65 20 76 61 6c 75 65 0a 2a 2a 20 72 65   The value.** re
27730 74 75 72 6e 65 64 20 62 79 20 73 71 6c 69 74 65  turned by sqlite
27740 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28 29 20  3_column_type() 
27750 69 73 20 6f 6e 6c 79 20 6d 65 61 6e 69 6e 67 66  is only meaningf
27760 75 6c 20 69 66 20 6e 6f 20 74 79 70 65 0a 2a 2a  ul if no type.**
27770 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 68 61 76   conversions hav
27780 65 20 6f 63 63 75 72 72 65 64 20 61 73 20 64 65  e occurred as de
27790 73 63 72 69 62 65 64 20 62 65 6c 6f 77 2e 20 20  scribed below.  
277a0 41 66 74 65 72 20 61 20 74 79 70 65 20 63 6f 6e  After a type con
277b0 76 65 72 73 69 6f 6e 2c 0a 2a 2a 20 74 68 65 20  version,.** the 
277c0 76 61 6c 75 65 20 72 65 74 75 72 6e 65 64 20 62  value returned b
277d0 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  y sqlite3_column
277e0 5f 74 79 70 65 28 29 20 69 73 20 75 6e 64 65 66  _type() is undef
277f0 69 6e 65 64 2e 20 20 46 75 74 75 72 65 0a 2a 2a  ined.  Future.**
27800 20 76 65 72 73 69 6f 6e 73 20 6f 66 20 53 51 4c   versions of SQL
27810 69 74 65 20 6d 61 79 20 63 68 61 6e 67 65 20 74  ite may change t
27820 68 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73  he behavior of s
27830 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79  qlite3_column_ty
27840 70 65 28 29 0a 2a 2a 20 66 6f 6c 6c 6f 77 69 6e  pe().** followin
27850 67 20 61 20 74 79 70 65 20 63 6f 6e 76 65 72 73  g a type convers
27860 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ion..**.** ^If t
27870 68 65 20 72 65 73 75 6c 74 20 69 73 20 61 20 42  he result is a B
27880 4c 4f 42 20 6f 72 20 55 54 46 2d 38 20 73 74 72  LOB or UTF-8 str
27890 69 6e 67 20 74 68 65 6e 20 74 68 65 20 73 71 6c  ing then the sql
278a0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65  ite3_column_byte
278b0 73 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 20 72  s().** routine r
278c0 65 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65  eturns the numbe
278d0 72 20 6f 66 20 62 79 74 65 73 20 69 6e 20 74 68  r of bytes in th
278e0 61 74 20 42 4c 4f 42 20 6f 72 20 73 74 72 69 6e  at BLOB or strin
278f0 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72 65  g..** ^If the re
27900 73 75 6c 74 20 69 73 20 61 20 55 54 46 2d 31 36  sult is a UTF-16
27910 20 73 74 72 69 6e 67 2c 20 74 68 65 6e 20 73 71   string, then sq
27920 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27930 65 73 28 29 20 63 6f 6e 76 65 72 74 73 0a 2a 2a  es() converts.**
27940 20 74 68 65 20 73 74 72 69 6e 67 20 74 6f 20 55   the string to U
27950 54 46 2d 38 20 61 6e 64 20 74 68 65 6e 20 72 65  TF-8 and then re
27960 74 75 72 6e 73 20 74 68 65 20 6e 75 6d 62 65 72  turns the number
27970 20 6f 66 20 62 79 74 65 73 2e 0a 2a 2a 20 5e 49   of bytes..** ^I
27980 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20  f the result is 
27990 61 20 6e 75 6d 65 72 69 63 20 76 61 6c 75 65 20  a numeric value 
279a0 74 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c  then sqlite3_col
279b0 75 6d 6e 5f 62 79 74 65 73 28 29 20 75 73 65 73  umn_bytes() uses
279c0 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70  .** [sqlite3_snp
279d0 72 69 6e 74 66 28 29 5d 20 74 6f 20 63 6f 6e 76  rintf()] to conv
279e0 65 72 74 20 74 68 61 74 20 76 61 6c 75 65 20 74  ert that value t
279f0 6f 20 61 20 55 54 46 2d 38 20 73 74 72 69 6e 67  o a UTF-8 string
27a00 20 61 6e 64 20 72 65 74 75 72 6e 73 0a 2a 2a 20   and returns.** 
27a10 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79  the number of by
27a20 74 65 73 20 69 6e 20 74 68 61 74 20 73 74 72 69  tes in that stri
27a30 6e 67 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  ng..** ^If the r
27a40 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 2c 20 74  esult is NULL, t
27a50 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
27a60 6d 6e 5f 62 79 74 65 73 28 29 20 72 65 74 75 72  mn_bytes() retur
27a70 6e 73 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e  ns zero..**.** ^
27a80 49 66 20 74 68 65 20 72 65 73 75 6c 74 20 69 73  If the result is
27a90 20 61 20 42 4c 4f 42 20 6f 72 20 55 54 46 2d 31   a BLOB or UTF-1
27aa0 36 20 73 74 72 69 6e 67 20 74 68 65 6e 20 74 68  6 string then th
27ab0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  e sqlite3_column
27ac0 5f 62 79 74 65 73 31 36 28 29 0a 2a 2a 20 72 6f  _bytes16().** ro
27ad0 75 74 69 6e 65 20 72 65 74 75 72 6e 73 20 74 68  utine returns th
27ae0 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65  e number of byte
27af0 73 20 69 6e 20 74 68 61 74 20 42 4c 4f 42 20 6f  s in that BLOB o
27b00 72 20 73 74 72 69 6e 67 2e 0a 2a 2a 20 5e 49 66  r string..** ^If
27b10 20 74 68 65 20 72 65 73 75 6c 74 20 69 73 20 61   the result is a
27b20 20 55 54 46 2d 38 20 73 74 72 69 6e 67 2c 20 74   UTF-8 string, t
27b30 68 65 6e 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  hen sqlite3_colu
27b40 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 63 6f 6e  mn_bytes16() con
27b50 76 65 72 74 73 0a 2a 2a 20 74 68 65 20 73 74 72  verts.** the str
27b60 69 6e 67 20 74 6f 20 55 54 46 2d 31 36 20 61 6e  ing to UTF-16 an
27b70 64 20 74 68 65 6e 20 72 65 74 75 72 6e 73 20 74  d then returns t
27b80 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
27b90 65 73 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 72  es..** ^If the r
27ba0 65 73 75 6c 74 20 69 73 20 61 20 6e 75 6d 65 72  esult is a numer
27bb0 69 63 20 76 61 6c 75 65 20 74 68 65 6e 20 73 71  ic value then sq
27bc0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
27bd0 65 73 31 36 28 29 20 75 73 65 73 0a 2a 2a 20 5b  es16() uses.** [
27be0 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e 74 66  sqlite3_snprintf
27bf0 28 29 5d 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ()] to convert t
27c00 68 61 74 20 76 61 6c 75 65 20 74 6f 20 61 20 55  hat value to a U
27c10 54 46 2d 31 36 20 73 74 72 69 6e 67 20 61 6e 64  TF-16 string and
27c20 20 72 65 74 75 72 6e 73 0a 2a 2a 20 74 68 65 20   returns.** the 
27c30 6e 75 6d 62 65 72 20 6f 66 20 62 79 74 65 73 20  number of bytes 
27c40 69 6e 20 74 68 61 74 20 73 74 72 69 6e 67 2e 0a  in that string..
27c50 2a 2a 20 5e 49 66 20 74 68 65 20 72 65 73 75 6c  ** ^If the resul
27c60 74 20 69 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20  t is NULL, then 
27c70 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
27c80 79 74 65 73 31 36 28 29 20 72 65 74 75 72 6e 73  ytes16() returns
27c90 20 7a 65 72 6f 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   zero..**.** ^Th
27ca0 65 20 76 61 6c 75 65 73 20 72 65 74 75 72 6e 65  e values returne
27cb0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
27cc0 6c 75 6d 6e 5f 62 79 74 65 73 28 29 5d 20 61 6e  lumn_bytes()] an
27cd0 64 20 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63  d .** [sqlite3_c
27ce0 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 5d  olumn_bytes16()]
27cf0 20 64 6f 20 6e 6f 74 20 69 6e 63 6c 75 64 65 20   do not include 
27d00 74 68 65 20 7a 65 72 6f 20 74 65 72 6d 69 6e 61  the zero termina
27d10 74 6f 72 73 20 61 74 20 74 68 65 20 65 6e 64 0a  tors at the end.
27d20 2a 2a 20 6f 66 20 74 68 65 20 73 74 72 69 6e 67  ** of the string
27d30 2e 20 20 5e 46 6f 72 20 63 6c 61 72 69 74 79 3a  .  ^For clarity:
27d40 20 74 68 65 20 76 61 6c 75 65 73 20 72 65 74 75   the values retu
27d50 72 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69  rned by.** [sqli
27d60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
27d70 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
27d80 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73 31 36 28  _column_bytes16(
27d90 29 5d 20 61 72 65 20 74 68 65 20 6e 75 6d 62 65  )] are the numbe
27da0 72 20 6f 66 0a 2a 2a 20 62 79 74 65 73 20 69 6e  r of.** bytes in
27db0 20 74 68 65 20 73 74 72 69 6e 67 2c 20 6e 6f 74   the string, not
27dc0 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 63   the number of c
27dd0 68 61 72 61 63 74 65 72 73 2e 0a 2a 2a 0a 2a 2a  haracters..**.**
27de0 20 5e 53 74 72 69 6e 67 73 20 72 65 74 75 72 6e   ^Strings return
27df0 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f  ed by sqlite3_co
27e00 6c 75 6d 6e 5f 74 65 78 74 28 29 20 61 6e 64 20  lumn_text() and 
27e10 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
27e20 65 78 74 31 36 28 29 2c 0a 2a 2a 20 65 76 65 6e  ext16(),.** even
27e30 20 65 6d 70 74 79 20 73 74 72 69 6e 67 73 2c 20   empty strings, 
27e40 61 72 65 20 61 6c 77 61 79 73 20 7a 65 72 6f 20  are always zero 
27e50 74 65 72 6d 69 6e 61 74 65 64 2e 20 20 5e 54 68  terminated.  ^Th
27e60 65 20 72 65 74 75 72 6e 0a 2a 2a 20 76 61 6c 75  e return.** valu
27e70 65 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 63  e from sqlite3_c
27e80 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29 20 66 6f 72  olumn_blob() for
27e90 20 61 20 7a 65 72 6f 2d 6c 65 6e 67 74 68 20 42   a zero-length B
27ea0 4c 4f 42 20 69 73 20 61 20 4e 55 4c 4c 20 70 6f  LOB is a NULL po
27eb0 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  inter..**.** ^Th
27ec0 65 20 6f 62 6a 65 63 74 20 72 65 74 75 72 6e 65  e object returne
27ed0 64 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f  d by [sqlite3_co
27ee0 6c 75 6d 6e 5f 76 61 6c 75 65 28 29 5d 20 69 73  lumn_value()] is
27ef0 20 61 6e 0a 2a 2a 20 5b 75 6e 70 72 6f 74 65 63   an.** [unprotec
27f00 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  ted sqlite3_valu
27f10 65 5d 20 6f 62 6a 65 63 74 2e 20 20 41 6e 20 75  e] object.  An u
27f20 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
27f30 65 33 5f 76 61 6c 75 65 20 6f 62 6a 65 63 74 0a  e3_value object.
27f40 2a 2a 20 6d 61 79 20 6f 6e 6c 79 20 62 65 20 75  ** may only be u
27f50 73 65 64 20 77 69 74 68 20 5b 73 71 6c 69 74 65  sed with [sqlite
27f60 33 5f 62 69 6e 64 5f 76 61 6c 75 65 28 29 5d 20  3_bind_value()] 
27f70 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 65 73  and [sqlite3_res
27f80 75 6c 74 5f 76 61 6c 75 65 28 29 5d 2e 0a 2a 2a  ult_value()]..**
27f90 20 49 66 20 74 68 65 20 5b 75 6e 70 72 6f 74 65   If the [unprote
27fa0 63 74 65 64 20 73 71 6c 69 74 65 33 5f 76 61 6c  cted sqlite3_val
27fb0 75 65 5d 20 6f 62 6a 65 63 74 20 72 65 74 75 72  ue] object retur
27fc0 6e 65 64 20 62 79 0a 2a 2a 20 5b 73 71 6c 69 74  ned by.** [sqlit
27fd0 65 33 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28  e3_column_value(
27fe0 29 5d 20 69 73 20 75 73 65 64 20 69 6e 20 61 6e  )] is used in an
27ff0 79 20 6f 74 68 65 72 20 77 61 79 2c 20 69 6e 63  y other way, inc
28000 6c 75 64 69 6e 67 20 63 61 6c 6c 73 0a 2a 2a 20  luding calls.** 
28010 74 6f 20 72 6f 75 74 69 6e 65 73 20 6c 69 6b 65  to routines like
28020 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f   [sqlite3_value_
28030 69 6e 74 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33  int()], [sqlite3
28040 5f 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 0a  _value_text()],.
28050 2a 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 76  ** or [sqlite3_v
28060 61 6c 75 65 5f 62 79 74 65 73 28 29 5d 2c 20 74  alue_bytes()], t
28070 68 65 6e 20 74 68 65 20 62 65 68 61 76 69 6f 72  hen the behavior
28080 20 69 73 20 75 6e 64 65 66 69 6e 65 64 2e 0a 2a   is undefined..*
28090 2a 0a 2a 2a 20 54 68 65 73 65 20 72 6f 75 74 69  *.** These routi
280a0 6e 65 73 20 61 74 74 65 6d 70 74 20 74 6f 20 63  nes attempt to c
280b0 6f 6e 76 65 72 74 20 74 68 65 20 76 61 6c 75 65  onvert the value
280c0 20 77 68 65 72 65 20 61 70 70 72 6f 70 72 69 61   where appropria
280d0 74 65 2e 20 20 5e 46 6f 72 0a 2a 2a 20 65 78 61  te.  ^For.** exa
280e0 6d 70 6c 65 2c 20 69 66 20 74 68 65 20 69 6e 74  mple, if the int
280f0 65 72 6e 61 6c 20 72 65 70 72 65 73 65 6e 74 61  ernal representa
28100 74 69 6f 6e 20 69 73 20 46 4c 4f 41 54 20 61 6e  tion is FLOAT an
28110 64 20 61 20 74 65 78 74 20 72 65 73 75 6c 74 0a  d a text result.
28120 2a 2a 20 69 73 20 72 65 71 75 65 73 74 65 64 2c  ** is requested,
28130 20 5b 73 71 6c 69 74 65 33 5f 73 6e 70 72 69 6e   [sqlite3_snprin
28140 74 66 28 29 5d 20 69 73 20 75 73 65 64 20 69 6e  tf()] is used in
28150 74 65 72 6e 61 6c 6c 79 20 74 6f 20 70 65 72 66  ternally to perf
28160 6f 72 6d 20 74 68 65 0a 2a 2a 20 63 6f 6e 76 65  orm the.** conve
28170 72 73 69 6f 6e 20 61 75 74 6f 6d 61 74 69 63 61  rsion automatica
28180 6c 6c 79 2e 20 20 5e 28 54 68 65 20 66 6f 6c 6c  lly.  ^(The foll
28190 6f 77 69 6e 67 20 74 61 62 6c 65 20 64 65 74 61  owing table deta
281a0 69 6c 73 20 74 68 65 20 63 6f 6e 76 65 72 73 69  ils the conversi
281b0 6f 6e 73 0a 2a 2a 20 74 68 61 74 20 61 72 65 20  ons.** that are 
281c0 61 70 70 6c 69 65 64 3a 0a 2a 2a 0a 2a 2a 20 3c  applied:.**.** <
281d0 62 6c 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c  blockquote>.** <
281e0 74 61 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22  table border="1"
281f0 3e 0a 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 49 6e  >.** <tr><th> In
28200 74 65 72 6e 61 6c 3c 62 72 3e 54 79 70 65 20 3c  ternal<br>Type <
28210 74 68 3e 20 52 65 71 75 65 73 74 65 64 3c 62 72  th> Requested<br
28220 3e 54 79 70 65 20 3c 74 68 3e 20 20 43 6f 6e 76  >Type <th>  Conv
28230 65 72 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 3c 74 72  ersion.**.** <tr
28240 3e 3c 74 64 3e 20 20 4e 55 4c 4c 20 20 20 20 3c  ><td>  NULL    <
28250 74 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74  td> INTEGER   <t
28260 64 3e 20 52 65 73 75 6c 74 20 69 73 20 30 0a 2a  d> Result is 0.*
28270 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 4e 55 4c 4c  * <tr><td>  NULL
28280 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f 41 54 20      <td>  FLOAT 
28290 20 20 20 3c 74 64 3e 20 52 65 73 75 6c 74 20 69     <td> Result i
282a0 73 20 30 2e 30 0a 2a 2a 20 3c 74 72 3e 3c 74 64  s 0.0.** <tr><td
282b0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
282c0 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20 52    TEXT    <td> R
282d0 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
282e0 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
282f0 3e 20 20 4e 55 4c 4c 20 20 20 20 3c 74 64 3e 20  >  NULL    <td> 
28300 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 52    BLOB    <td> R
28310 65 73 75 6c 74 20 69 73 20 4e 55 4c 4c 20 70 6f  esult is NULL po
28320 69 6e 74 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64  inter.** <tr><td
28330 3e 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20  > INTEGER  <td> 
28340 20 46 4c 4f 41 54 20 20 20 20 3c 74 64 3e 20 43   FLOAT    <td> C
28350 6f 6e 76 65 72 74 20 66 72 6f 6d 20 69 6e 74 65  onvert from inte
28360 67 65 72 20 74 6f 20 66 6c 6f 61 74 0a 2a 2a 20  ger to float.** 
28370 3c 74 72 3e 3c 74 64 3e 20 49 4e 54 45 47 45 52  <tr><td> INTEGER
28380 20 20 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20    <td>   TEXT   
28390 20 3c 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64   <td> ASCII rend
283a0 65 72 69 6e 67 20 6f 66 20 74 68 65 20 69 6e 74  ering of the int
283b0 65 67 65 72 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e  eger.** <tr><td>
283c0 20 49 4e 54 45 47 45 52 20 20 3c 74 64 3e 20 20   INTEGER  <td>  
283d0 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 53 61   BLOB    <td> Sa
283e0 6d 65 20 61 73 20 49 4e 54 45 47 45 52 2d 3e 54  me as INTEGER->T
283f0 45 58 54 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20  EXT.** <tr><td> 
28400 20 46 4c 4f 41 54 20 20 20 3c 74 64 3e 20 49 4e   FLOAT   <td> IN
28410 54 45 47 45 52 20 20 20 3c 74 64 3e 20 43 6f 6e  TEGER   <td> Con
28420 76 65 72 74 20 66 72 6f 6d 20 66 6c 6f 61 74 20  vert from float 
28430 74 6f 20 69 6e 74 65 67 65 72 0a 2a 2a 20 3c 74  to integer.** <t
28440 72 3e 3c 74 64 3e 20 20 46 4c 4f 41 54 20 20 20  r><td>  FLOAT   
28450 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28460 74 64 3e 20 41 53 43 49 49 20 72 65 6e 64 65 72  td> ASCII render
28470 69 6e 67 20 6f 66 20 74 68 65 20 66 6c 6f 61 74  ing of the float
28480 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 46 4c  .** <tr><td>  FL
28490 4f 41 54 20 20 20 3c 74 64 3e 20 20 20 42 4c 4f  OAT   <td>   BLO
284a0 42 20 20 20 20 3c 74 64 3e 20 53 61 6d 65 20 61  B    <td> Same a
284b0 73 20 46 4c 4f 41 54 2d 3e 54 45 58 54 0a 2a 2a  s FLOAT->TEXT.**
284c0 20 3c 74 72 3e 3c 74 64 3e 20 20 54 45 58 54 20   <tr><td>  TEXT 
284d0 20 20 20 3c 74 64 3e 20 49 4e 54 45 47 45 52 20     <td> INTEGER 
284e0 20 20 3c 74 64 3e 20 55 73 65 20 61 74 6f 69 28    <td> Use atoi(
284f0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 54  ).** <tr><td>  T
28500 45 58 54 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  EXT    <td>  FLO
28510 41 54 20 20 20 20 3c 74 64 3e 20 55 73 65 20 61  AT    <td> Use a
28520 74 6f 66 28 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64  tof().** <tr><td
28530 3e 20 20 54 45 58 54 20 20 20 20 3c 74 64 3e 20  >  TEXT    <td> 
28540 20 20 42 4c 4f 42 20 20 20 20 3c 74 64 3e 20 4e    BLOB    <td> N
28550 6f 20 63 68 61 6e 67 65 0a 2a 2a 20 3c 74 72 3e  o change.** <tr>
28560 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20 3c 74  <td>  BLOB    <t
28570 64 3e 20 49 4e 54 45 47 45 52 20 20 20 3c 74 64  d> INTEGER   <td
28580 3e 20 43 6f 6e 76 65 72 74 20 74 6f 20 54 45 58  > Convert to TEX
28590 54 20 74 68 65 6e 20 75 73 65 20 61 74 6f 69 28  T then use atoi(
285a0 29 0a 2a 2a 20 3c 74 72 3e 3c 74 64 3e 20 20 42  ).** <tr><td>  B
285b0 4c 4f 42 20 20 20 20 3c 74 64 3e 20 20 46 4c 4f  LOB    <td>  FLO
285c0 41 54 20 20 20 20 3c 74 64 3e 20 43 6f 6e 76 65  AT    <td> Conve
285d0 72 74 20 74 6f 20 54 45 58 54 20 74 68 65 6e 20  rt to TEXT then 
285e0 75 73 65 20 61 74 6f 66 28 29 0a 2a 2a 20 3c 74  use atof().** <t
285f0 72 3e 3c 74 64 3e 20 20 42 4c 4f 42 20 20 20 20  r><td>  BLOB    
28600 3c 74 64 3e 20 20 20 54 45 58 54 20 20 20 20 3c  <td>   TEXT    <
28610 74 64 3e 20 41 64 64 20 61 20 7a 65 72 6f 20 74  td> Add a zero t
28620 65 72 6d 69 6e 61 74 6f 72 20 69 66 20 6e 65 65  erminator if nee
28630 64 65 64 0a 2a 2a 20 3c 2f 74 61 62 6c 65 3e 0a  ded.** </table>.
28640 2a 2a 20 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e  ** </blockquote>
28650 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 61 62  )^.**.** The tab
28660 6c 65 20 61 62 6f 76 65 20 6d 61 6b 65 73 20 72  le above makes r
28670 65 66 65 72 65 6e 63 65 20 74 6f 20 73 74 61 6e  eference to stan
28680 64 61 72 64 20 43 20 6c 69 62 72 61 72 79 20 66  dard C library f
28690 75 6e 63 74 69 6f 6e 73 20 61 74 6f 69 28 29 0a  unctions atoi().
286a0 2a 2a 20 61 6e 64 20 61 74 6f 66 28 29 2e 20 20  ** and atof().  
286b0 53 51 4c 69 74 65 20 64 6f 65 73 20 6e 6f 74 20  SQLite does not 
286c0 72 65 61 6c 6c 79 20 75 73 65 20 74 68 65 73 65  really use these
286d0 20 66 75 6e 63 74 69 6f 6e 73 2e 20 20 49 74 20   functions.  It 
286e0 68 61 73 20 69 74 73 0a 2a 2a 20 6f 77 6e 20 65  has its.** own e
286f0 71 75 69 76 61 6c 65 6e 74 20 69 6e 74 65 72 6e  quivalent intern
28700 61 6c 20 72 6f 75 74 69 6e 65 73 2e 20 20 54 68  al routines.  Th
28710 65 20 61 74 6f 69 28 29 20 61 6e 64 20 61 74 6f  e atoi() and ato
28720 66 28 29 20 6e 61 6d 65 73 20 61 72 65 0a 2a 2a  f() names are.**
28730 20 75 73 65 64 20 69 6e 20 74 68 65 20 74 61 62   used in the tab
28740 6c 65 20 66 6f 72 20 62 72 65 76 69 74 79 20 61  le for brevity a
28750 6e 64 20 62 65 63 61 75 73 65 20 74 68 65 79 20  nd because they 
28760 61 72 65 20 66 61 6d 69 6c 69 61 72 20 74 6f 20  are familiar to 
28770 6d 6f 73 74 0a 2a 2a 20 43 20 70 72 6f 67 72 61  most.** C progra
28780 6d 6d 65 72 73 2e 0a 2a 2a 0a 2a 2a 20 4e 6f 74  mmers..**.** Not
28790 65 20 74 68 61 74 20 77 68 65 6e 20 74 79 70 65  e that when type
287a0 20 63 6f 6e 76 65 72 73 69 6f 6e 73 20 6f 63 63   conversions occ
287b0 75 72 2c 20 70 6f 69 6e 74 65 72 73 20 72 65 74  ur, pointers ret
287c0 75 72 6e 65 64 20 62 79 20 70 72 69 6f 72 0a 2a  urned by prior.*
287d0 2a 20 63 61 6c 6c 73 20 74 6f 20 73 71 6c 69 74  * calls to sqlit
287e0 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f 62 28 29  e3_column_blob()
287f0 2c 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  , sqlite3_column
28800 5f 74 65 78 74 28 29 2c 20 61 6e 64 2f 6f 72 0a  _text(), and/or.
28810 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
28820 6e 5f 74 65 78 74 31 36 28 29 20 6d 61 79 20 62  n_text16() may b
28830 65 20 69 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a  e invalidated..*
28840 2a 20 54 79 70 65 20 63 6f 6e 76 65 72 73 69 6f  * Type conversio
28850 6e 73 20 61 6e 64 20 70 6f 69 6e 74 65 72 20 69  ns and pointer i
28860 6e 76 61 6c 69 64 61 74 69 6f 6e 73 20 6d 69 67  nvalidations mig
28870 68 74 20 6f 63 63 75 72 0a 2a 2a 20 69 6e 20 74  ht occur.** in t
28880 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20 63 61 73  he following cas
28890 65 73 3a 0a 2a 2a 0a 2a 2a 20 3c 75 6c 3e 0a 2a  es:.**.** <ul>.*
288a0 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
288b0 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 61 20  al content is a 
288c0 42 4c 4f 42 20 61 6e 64 20 73 71 6c 69 74 65 33  BLOB and sqlite3
288d0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 20 6f  _column_text() o
288e0 72 0a 2a 2a 20 20 20 20 20 20 73 71 6c 69 74 65  r.**      sqlite
288f0 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28  3_column_text16(
28900 29 20 69 73 20 63 61 6c 6c 65 64 2e 20 20 41 20  ) is called.  A 
28910 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74 6f 72 20  zero-terminator 
28920 6d 69 67 68 74 0a 2a 2a 20 20 20 20 20 20 6e 65  might.**      ne
28930 65 64 20 74 6f 20 62 65 20 61 64 64 65 64 20 74  ed to be added t
28940 6f 20 74 68 65 20 73 74 72 69 6e 67 2e 3c 2f 6c  o the string.</l
28950 69 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65 20 69  i>.** <li> The i
28960 6e 69 74 69 61 6c 20 63 6f 6e 74 65 6e 74 20 69  nitial content i
28970 73 20 55 54 46 2d 38 20 74 65 78 74 20 61 6e 64  s UTF-8 text and
28980 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f   sqlite3_column_
28990 62 79 74 65 73 31 36 28 29 20 6f 72 0a 2a 2a 20  bytes16() or.** 
289a0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 63 6f 6c       sqlite3_col
289b0 75 6d 6e 5f 74 65 78 74 31 36 28 29 20 69 73 20  umn_text16() is 
289c0 63 61 6c 6c 65 64 2e 20 20 54 68 65 20 63 6f 6e  called.  The con
289d0 74 65 6e 74 20 6d 75 73 74 20 62 65 20 63 6f 6e  tent must be con
289e0 76 65 72 74 65 64 0a 2a 2a 20 20 20 20 20 20 74  verted.**      t
289f0 6f 20 55 54 46 2d 31 36 2e 3c 2f 6c 69 3e 0a 2a  o UTF-16.</li>.*
28a00 2a 20 3c 6c 69 3e 20 54 68 65 20 69 6e 69 74 69  * <li> The initi
28a10 61 6c 20 63 6f 6e 74 65 6e 74 20 69 73 20 55 54  al content is UT
28a20 46 2d 31 36 20 74 65 78 74 20 61 6e 64 20 73 71  F-16 text and sq
28a30 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28a40 65 73 28 29 20 6f 72 0a 2a 2a 20 20 20 20 20 20  es() or.**      
28a50 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74  sqlite3_column_t
28a60 65 78 74 28 29 20 69 73 20 63 61 6c 6c 65 64 2e  ext() is called.
28a70 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 20 6d 75    The content mu
28a80 73 74 20 62 65 20 63 6f 6e 76 65 72 74 65 64 0a  st be converted.
28a90 2a 2a 20 20 20 20 20 20 74 6f 20 55 54 46 2d 38  **      to UTF-8
28aa0 2e 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75 6c 3e 0a  .</li>.** </ul>.
28ab0 2a 2a 0a 2a 2a 20 5e 43 6f 6e 76 65 72 73 69 6f  **.** ^Conversio
28ac0 6e 73 20 62 65 74 77 65 65 6e 20 55 54 46 2d 31  ns between UTF-1
28ad0 36 62 65 20 61 6e 64 20 55 54 46 2d 31 36 6c 65  6be and UTF-16le
28ae0 20 61 72 65 20 61 6c 77 61 79 73 20 64 6f 6e 65   are always done
28af0 20 69 6e 20 70 6c 61 63 65 20 61 6e 64 20 64 6f   in place and do
28b00 0a 2a 2a 20 6e 6f 74 20 69 6e 76 61 6c 69 64 61  .** not invalida
28b10 74 65 20 61 20 70 72 69 6f 72 20 70 6f 69 6e 74  te a prior point
28b20 65 72 2c 20 74 68 6f 75 67 68 20 6f 66 20 63 6f  er, though of co
28b30 75 72 73 65 20 74 68 65 20 63 6f 6e 74 65 6e 74  urse the content
28b40 20 6f 66 20 74 68 65 20 62 75 66 66 65 72 0a 2a   of the buffer.*
28b50 2a 20 74 68 61 74 20 74 68 65 20 70 72 69 6f 72  * that the prior
28b60 20 70 6f 69 6e 74 65 72 20 72 65 66 65 72 65 6e   pointer referen
28b70 63 65 73 20 77 69 6c 6c 20 68 61 76 65 20 62 65  ces will have be
28b80 65 6e 20 6d 6f 64 69 66 69 65 64 2e 20 20 4f 74  en modified.  Ot
28b90 68 65 72 20 6b 69 6e 64 73 0a 2a 2a 20 6f 66 20  her kinds.** of 
28ba0 63 6f 6e 76 65 72 73 69 6f 6e 20 61 72 65 20 64  conversion are d
28bb0 6f 6e 65 20 69 6e 20 70 6c 61 63 65 20 77 68 65  one in place whe
28bc0 6e 20 69 74 20 69 73 20 70 6f 73 73 69 62 6c 65  n it is possible
28bd0 2c 20 62 75 74 20 73 6f 6d 65 74 69 6d 65 73 20  , but sometimes 
28be0 74 68 65 79 0a 2a 2a 20 61 72 65 20 6e 6f 74 20  they.** are not 
28bf0 70 6f 73 73 69 62 6c 65 20 61 6e 64 20 69 6e 20  possible and in 
28c00 74 68 6f 73 65 20 63 61 73 65 73 20 70 72 69 6f  those cases prio
28c10 72 20 70 6f 69 6e 74 65 72 73 20 61 72 65 20 69  r pointers are i
28c20 6e 76 61 6c 69 64 61 74 65 64 2e 0a 2a 2a 0a 2a  nvalidated..**.*
28c30 2a 20 54 68 65 20 73 61 66 65 73 74 20 61 6e 64  * The safest and
28c40 20 65 61 73 69 65 73 74 20 74 6f 20 72 65 6d 65   easiest to reme
28c50 6d 62 65 72 20 70 6f 6c 69 63 79 20 69 73 20 74  mber policy is t
28c60 6f 20 69 6e 76 6f 6b 65 20 74 68 65 73 65 20 72  o invoke these r
28c70 6f 75 74 69 6e 65 73 0a 2a 2a 20 69 6e 20 6f 6e  outines.** in on
28c80 65 20 6f 66 20 74 68 65 20 66 6f 6c 6c 6f 77 69  e of the followi
28c90 6e 67 20 77 61 79 73 3a 0a 2a 2a 0a 2a 2a 20 3c  ng ways:.**.** <
28ca0 75 6c 3e 0a 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69  ul>.**  <li>sqli
28cb0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28  te3_column_text(
28cc0 29 20 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71  ) followed by sq
28cd0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74  lite3_column_byt
28ce0 65 73 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 20 3c 6c  es()</li>.**  <l
28cf0 69 3e 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e  i>sqlite3_column
28d00 5f 62 6c 6f 62 28 29 20 66 6f 6c 6c 6f 77 65 64  _blob() followed
28d10 20 62 79 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75   by sqlite3_colu
28d20 6d 6e 5f 62 79 74 65 73 28 29 3c 2f 6c 69 3e 0a  mn_bytes()</li>.
28d30 2a 2a 20 20 3c 6c 69 3e 73 71 6c 69 74 65 33 5f  **  <li>sqlite3_
28d40 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 20  column_text16() 
28d50 66 6f 6c 6c 6f 77 65 64 20 62 79 20 73 71 6c 69  followed by sqli
28d60 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 79 74 65 73  te3_column_bytes
28d70 31 36 28 29 3c 2f 6c 69 3e 0a 2a 2a 20 3c 2f 75  16()</li>.** </u
28d80 6c 3e 0a 2a 2a 0a 2a 2a 20 49 6e 20 6f 74 68 65  l>.**.** In othe
28d90 72 20 77 6f 72 64 73 2c 20 79 6f 75 20 73 68 6f  r words, you sho
28da0 75 6c 64 20 63 61 6c 6c 20 73 71 6c 69 74 65 33  uld call sqlite3
28db0 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74 28 29 2c 0a  _column_text(),.
28dc0 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  ** sqlite3_colum
28dd0 6e 5f 62 6c 6f 62 28 29 2c 20 6f 72 20 73 71 6c  n_blob(), or sql
28de0 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78 74  ite3_column_text
28df0 31 36 28 29 20 66 69 72 73 74 20 74 6f 20 66 6f  16() first to fo
28e00 72 63 65 20 74 68 65 20 72 65 73 75 6c 74 0a 2a  rce the result.*
28e10 2a 20 69 6e 74 6f 20 74 68 65 20 64 65 73 69 72  * into the desir
28e20 65 64 20 66 6f 72 6d 61 74 2c 20 74 68 65 6e 20  ed format, then 
28e30 69 6e 76 6f 6b 65 20 73 71 6c 69 74 65 33 5f 63  invoke sqlite3_c
28e40 6f 6c 75 6d 6e 5f 62 79 74 65 73 28 29 20 6f 72  olumn_bytes() or
28e50 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75  .** sqlite3_colu
28e60 6d 6e 5f 62 79 74 65 73 31 36 28 29 20 74 6f 20  mn_bytes16() to 
28e70 66 69 6e 64 20 74 68 65 20 73 69 7a 65 20 6f 66  find the size of
28e80 20 74 68 65 20 72 65 73 75 6c 74 2e 20 20 44 6f   the result.  Do
28e90 20 6e 6f 74 20 6d 69 78 20 63 61 6c 6c 73 0a 2a   not mix calls.*
28ea0 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 6f 6c  * to sqlite3_col
28eb0 75 6d 6e 5f 74 65 78 74 28 29 20 6f 72 20 73 71  umn_text() or sq
28ec0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
28ed0 62 28 29 20 77 69 74 68 20 63 61 6c 6c 73 20 74  b() with calls t
28ee0 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63 6f 6c  o.** sqlite3_col
28ef0 75 6d 6e 5f 62 79 74 65 73 31 36 28 29 2c 20 61  umn_bytes16(), a
28f00 6e 64 20 64 6f 20 6e 6f 74 20 6d 69 78 20 63 61  nd do not mix ca
28f10 6c 6c 73 20 74 6f 20 73 71 6c 69 74 65 33 5f 63  lls to sqlite3_c
28f20 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 29 0a 2a  olumn_text16().*
28f30 2a 20 77 69 74 68 20 63 61 6c 6c 73 20 74 6f 20  * with calls to 
28f40 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
28f50 79 74 65 73 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ytes()..**.** ^T
28f60 68 65 20 70 6f 69 6e 74 65 72 73 20 72 65 74 75  he pointers retu
28f70 72 6e 65 64 20 61 72 65 20 76 61 6c 69 64 20 75  rned are valid u
28f80 6e 74 69 6c 20 61 20 74 79 70 65 20 63 6f 6e 76  ntil a type conv
28f90 65 72 73 69 6f 6e 20 6f 63 63 75 72 73 20 61 73  ersion occurs as
28fa0 0a 2a 2a 20 64 65 73 63 72 69 62 65 64 20 61 62  .** described ab
28fb0 6f 76 65 2c 20 6f 72 20 75 6e 74 69 6c 20 5b 73  ove, or until [s
28fc0 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d 20 6f  qlite3_step()] o
28fd0 72 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  r [sqlite3_reset
28fe0 28 29 5d 20 6f 72 0a 2a 2a 20 5b 73 71 6c 69 74  ()] or.** [sqlit
28ff0 65 33 5f 66 69 6e 61 6c 69 7a 65 28 29 5d 20 69  e3_finalize()] i
29000 73 20 63 61 6c 6c 65 64 2e 20 20 5e 54 68 65 20  s called.  ^The 
29010 6d 65 6d 6f 72 79 20 73 70 61 63 65 20 75 73 65  memory space use
29020 64 20 74 6f 20 68 6f 6c 64 20 73 74 72 69 6e 67  d to hold string
29030 73 0a 2a 2a 20 61 6e 64 20 42 4c 4f 42 73 20 69  s.** and BLOBs i
29040 73 20 66 72 65 65 64 20 61 75 74 6f 6d 61 74 69  s freed automati
29050 63 61 6c 6c 79 2e 20 20 44 6f 20 3c 62 3e 6e 6f  cally.  Do <b>no
29060 74 3c 2f 62 3e 20 70 61 73 73 20 74 68 65 20 70  t</b> pass the p
29070 6f 69 6e 74 65 72 73 20 72 65 74 75 72 6e 65 64  ointers returned
29080 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6c  .** [sqlite3_col
29090 75 6d 6e 5f 62 6c 6f 62 28 29 5d 2c 20 5b 73 71  umn_blob()], [sq
290a0 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
290b0 74 28 29 5d 2c 20 65 74 63 2e 20 69 6e 74 6f 0a  t()], etc. into.
290c0 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 66 72 65 65  ** [sqlite3_free
290d0 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  ()]..**.** ^(If 
290e0 61 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74  a memory allocat
290f0 69 6f 6e 20 65 72 72 6f 72 20 6f 63 63 75 72 73  ion error occurs
29100 20 64 75 72 69 6e 67 20 74 68 65 20 65 76 61 6c   during the eval
29110 75 61 74 69 6f 6e 20 6f 66 20 61 6e 79 0a 2a 2a  uation of any.**
29120 20 6f 66 20 74 68 65 73 65 20 72 6f 75 74 69 6e   of these routin
29130 65 73 2c 20 61 20 64 65 66 61 75 6c 74 20 76 61  es, a default va
29140 6c 75 65 20 69 73 20 72 65 74 75 72 6e 65 64 2e  lue is returned.
29150 20 20 54 68 65 20 64 65 66 61 75 6c 74 20 76 61    The default va
29160 6c 75 65 0a 2a 2a 20 69 73 20 65 69 74 68 65 72  lue.** is either
29170 20 74 68 65 20 69 6e 74 65 67 65 72 20 30 2c 20   the integer 0, 
29180 74 68 65 20 66 6c 6f 61 74 69 6e 67 20 70 6f 69  the floating poi
29190 6e 74 20 6e 75 6d 62 65 72 20 30 2e 30 2c 20 6f  nt number 0.0, o
291a0 72 20 61 20 4e 55 4c 4c 0a 2a 2a 20 70 6f 69 6e  r a NULL.** poin
291b0 74 65 72 2e 20 20 53 75 62 73 65 71 75 65 6e 74  ter.  Subsequent
291c0 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c 69 74   calls to [sqlit
291d0 65 33 5f 65 72 72 63 6f 64 65 28 29 5d 20 77 69  e3_errcode()] wi
291e0 6c 6c 20 72 65 74 75 72 6e 0a 2a 2a 20 5b 53 51  ll return.** [SQ
291f0 4c 49 54 45 5f 4e 4f 4d 45 4d 5d 2e 29 5e 0a 2a  LITE_NOMEM].)^.*
29200 2f 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71  /.const void *sq
29210 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62 6c 6f  lite3_column_blo
29220 62 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  b(sqlite3_stmt*,
29230 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20   int iCol);.int 
29240 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 62  sqlite3_column_b
29250 79 74 65 73 28 73 71 6c 69 74 65 33 5f 73 74 6d  ytes(sqlite3_stm
29260 74 2a 2c 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 69  t*, int iCol);.i
29270 6e 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 75 6d  nt sqlite3_colum
29280 6e 5f 62 79 74 65 73 31 36 28 73 71 6c 69 74 65  n_bytes16(sqlite
29290 33 5f 73 74 6d 74 2a 2c 20 69 6e 74 20 69 43 6f  3_stmt*, int iCo
292a0 6c 29 3b 0a 64 6f 75 62 6c 65 20 73 71 6c 69 74  l);.double sqlit
292b0 65 33 5f 63 6f 6c 75 6d 6e 5f 64 6f 75 62 6c 65  e3_column_double
292c0 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20  (sqlite3_stmt*, 
292d0 69 6e 74 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73  int iCol);.int s
292e0 71 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 69 6e  qlite3_column_in
292f0 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
29300 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69   int iCol);.sqli
29310 74 65 33 5f 69 6e 74 36 34 20 73 71 6c 69 74 65  te3_int64 sqlite
29320 33 5f 63 6f 6c 75 6d 6e 5f 69 6e 74 36 34 28 73  3_column_int64(s
29330 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e  qlite3_stmt*, in
29340 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73 74 20 75  t iCol);.const u
29350 6e 73 69 67 6e 65 64 20 63 68 61 72 20 2a 73 71  nsigned char *sq
29360 6c 69 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 65 78  lite3_column_tex
29370 74 28 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c  t(sqlite3_stmt*,
29380 20 69 6e 74 20 69 43 6f 6c 29 3b 0a 63 6f 6e 73   int iCol);.cons
29390 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f  t void *sqlite3_
293a0 63 6f 6c 75 6d 6e 5f 74 65 78 74 31 36 28 73 71  column_text16(sq
293b0 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
293c0 20 69 43 6f 6c 29 3b 0a 69 6e 74 20 73 71 6c 69   iCol);.int sqli
293d0 74 65 33 5f 63 6f 6c 75 6d 6e 5f 74 79 70 65 28  te3_column_type(
293e0 73 71 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69  sqlite3_stmt*, i
293f0 6e 74 20 69 43 6f 6c 29 3b 0a 73 71 6c 69 74 65  nt iCol);.sqlite
29400 33 5f 76 61 6c 75 65 20 2a 73 71 6c 69 74 65 33  3_value *sqlite3
29410 5f 63 6f 6c 75 6d 6e 5f 76 61 6c 75 65 28 73 71  _column_value(sq
29420 6c 69 74 65 33 5f 73 74 6d 74 2a 2c 20 69 6e 74  lite3_stmt*, int
29430 20 69 43 6f 6c 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43   iCol);../*.** C
29440 41 50 49 33 52 45 46 3a 20 44 65 73 74 72 6f 79  API3REF: Destroy
29450 20 41 20 50 72 65 70 61 72 65 64 20 53 74 61 74   A Prepared Stat
29460 65 6d 65 6e 74 20 4f 62 6a 65 63 74 0a 2a 2a 0a  ement Object.**.
29470 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
29480 66 69 6e 61 6c 69 7a 65 28 29 20 66 75 6e 63 74  finalize() funct
29490 69 6f 6e 20 69 73 20 63 61 6c 6c 65 64 20 74 6f  ion is called to
294a0 20 64 65 6c 65 74 65 20 61 20 5b 70 72 65 70 61   delete a [prepa
294b0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 2e 0a  red statement]..
294c0 2a 2a 20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20  ** ^If the most 
294d0 72 65 63 65 6e 74 20 65 76 61 6c 75 61 74 69 6f  recent evaluatio
294e0 6e 20 6f 66 20 74 68 65 20 73 74 61 74 65 6d 65  n of the stateme
294f0 6e 74 20 65 6e 63 6f 75 6e 74 65 72 65 64 20 6e  nt encountered n
29500 6f 20 65 72 72 6f 72 73 20 6f 72 0a 2a 2a 20 6f  o errors or.** o
29510 72 20 69 66 20 74 68 65 20 73 74 61 74 65 6d 65  r if the stateme
29520 6e 74 20 69 73 20 6e 65 76 65 72 20 62 65 65 6e  nt is never been
29530 20 65 76 61 6c 75 61 74 65 64 2c 20 74 68 65 6e   evaluated, then
29540 20 73 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a   sqlite3_finaliz
29550 65 28 29 20 72 65 74 75 72 6e 73 0a 2a 2a 20 53  e() returns.** S
29560 51 4c 49 54 45 5f 4f 4b 2e 20 20 5e 49 66 20 74  QLITE_OK.  ^If t
29570 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20 65  he most recent e
29580 76 61 6c 75 61 74 69 6f 6e 20 6f 66 20 73 74 61  valuation of sta
29590 74 65 6d 65 6e 74 20 53 20 66 61 69 6c 65 64 2c  tement S failed,
295a0 20 74 68 65 6e 0a 2a 2a 20 73 71 6c 69 74 65 33   then.** sqlite3
295b0 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 65 74  _finalize(S) ret
295c0 75 72 6e 73 20 74 68 65 20 61 70 70 72 6f 70 72  urns the appropr
295d0 69 61 74 65 20 5b 65 72 72 6f 72 20 63 6f 64 65  iate [error code
295e0 5d 20 6f 72 0a 2a 2a 20 5b 65 78 74 65 6e 64 65  ] or.** [extende
295f0 64 20 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a 2a  d error code]..*
29600 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
29610 33 5f 66 69 6e 61 6c 69 7a 65 28 53 29 20 72 6f  3_finalize(S) ro
29620 75 74 69 6e 65 20 63 61 6e 20 62 65 20 63 61 6c  utine can be cal
29630 6c 65 64 20 61 74 20 61 6e 79 20 70 6f 69 6e 74  led at any point
29640 20 64 75 72 69 6e 67 0a 2a 2a 20 74 68 65 20 6c   during.** the l
29650 69 66 65 20 63 79 63 6c 65 20 6f 66 20 5b 70 72  ife cycle of [pr
29660 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74  epared statement
29670 5d 20 53 3a 0a 2a 2a 20 62 65 66 6f 72 65 20 73  ] S:.** before s
29680 74 61 74 65 6d 65 6e 74 20 53 20 69 73 20 65 76  tatement S is ev
29690 65 72 20 65 76 61 6c 75 61 74 65 64 2c 20 61 66  er evaluated, af
296a0 74 65 72 0a 2a 2a 20 6f 6e 65 20 6f 72 20 6d 6f  ter.** one or mo
296b0 72 65 20 63 61 6c 6c 73 20 74 6f 20 5b 73 71 6c  re calls to [sql
296c0 69 74 65 33 5f 72 65 73 65 74 28 29 5d 2c 20 6f  ite3_reset()], o
296d0 72 20 61 66 74 65 72 20 61 6e 79 20 63 61 6c 6c  r after any call
296e0 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74 65 33 5f  .** to [sqlite3_
296f0 73 74 65 70 28 29 5d 20 72 65 67 61 72 64 6c 65  step()] regardle
29700 73 73 20 6f 66 20 77 68 65 74 68 65 72 20 6f 72  ss of whether or
29710 20 6e 6f 74 20 74 68 65 20 73 74 61 74 65 6d 65   not the stateme
29720 6e 74 20 68 61 73 0a 2a 2a 20 63 6f 6d 70 6c 65  nt has.** comple
29730 74 65 64 20 65 78 65 63 75 74 69 6f 6e 2e 0a 2a  ted execution..*
29740 2a 0a 2a 2a 20 5e 49 6e 76 6f 6b 69 6e 67 20 73  *.** ^Invoking s
29750 71 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28  qlite3_finalize(
29760 29 20 6f 6e 20 61 20 4e 55 4c 4c 20 70 6f 69 6e  ) on a NULL poin
29770 74 65 72 20 69 73 20 61 20 68 61 72 6d 6c 65 73  ter is a harmles
29780 73 20 6e 6f 2d 6f 70 2e 0a 2a 2a 0a 2a 2a 20 54  s no-op..**.** T
29790 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 6d  he application m
297a0 75 73 74 20 66 69 6e 61 6c 69 7a 65 20 65 76 65  ust finalize eve
297b0 72 79 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  ry [prepared sta
297c0 74 65 6d 65 6e 74 5d 20 69 6e 20 6f 72 64 65 72  tement] in order
297d0 20 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 72 65 73   to avoid.** res
297e0 6f 75 72 63 65 20 6c 65 61 6b 73 2e 20 20 49 74  ource leaks.  It
297f0 20 69 73 20 61 20 67 72 69 65 76 6f 75 73 20 65   is a grievous e
29800 72 72 6f 72 20 66 6f 72 20 74 68 65 20 61 70 70  rror for the app
29810 6c 69 63 61 74 69 6f 6e 20 74 6f 20 74 72 79 20  lication to try 
29820 74 6f 20 75 73 65 0a 2a 2a 20 61 20 70 72 65 70  to use.** a prep
29830 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 20 61  ared statement a
29840 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65 6e  fter it has been
29850 20 66 69 6e 61 6c 69 7a 65 64 2e 20 20 41 6e 79   finalized.  Any
29860 20 75 73 65 20 6f 66 20 61 20 70 72 65 70 61 72   use of a prepar
29870 65 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20  ed.** statement 
29880 61 66 74 65 72 20 69 74 20 68 61 73 20 62 65 65  after it has bee
29890 6e 20 66 69 6e 61 6c 69 7a 65 64 20 63 61 6e 20  n finalized can 
298a0 72 65 73 75 6c 74 20 69 6e 20 75 6e 64 65 66 69  result in undefi
298b0 6e 65 64 20 61 6e 64 0a 2a 2a 20 75 6e 64 65 73  ned and.** undes
298c0 69 72 61 62 6c 65 20 62 65 68 61 76 69 6f 72 20  irable behavior 
298d0 73 75 63 68 20 61 73 20 73 65 67 66 61 75 6c 74  such as segfault
298e0 73 20 61 6e 64 20 68 65 61 70 20 63 6f 72 72 75  s and heap corru
298f0 70 74 69 6f 6e 2e 0a 2a 2f 0a 69 6e 74 20 73 71  ption..*/.int sq
29900 6c 69 74 65 33 5f 66 69 6e 61 6c 69 7a 65 28 73  lite3_finalize(s
29910 71 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74  qlite3_stmt *pSt
29920 6d 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49  mt);../*.** CAPI
29930 33 52 45 46 3a 20 52 65 73 65 74 20 41 20 50 72  3REF: Reset A Pr
29940 65 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74  epared Statement
29950 20 4f 62 6a 65 63 74 0a 2a 2a 0a 2a 2a 20 54 68   Object.**.** Th
29960 65 20 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28  e sqlite3_reset(
29970 29 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 63 61  ) function is ca
29980 6c 6c 65 64 20 74 6f 20 72 65 73 65 74 20 61 20  lled to reset a 
29990 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65 6d  [prepared statem
299a0 65 6e 74 5d 0a 2a 2a 20 6f 62 6a 65 63 74 20 62  ent].** object b
299b0 61 63 6b 20 74 6f 20 69 74 73 20 69 6e 69 74 69  ack to its initi
299c0 61 6c 20 73 74 61 74 65 2c 20 72 65 61 64 79 20  al state, ready 
299d0 74 6f 20 62 65 20 72 65 2d 65 78 65 63 75 74 65  to be re-execute
299e0 64 2e 0a 2a 2a 20 5e 41 6e 79 20 53 51 4c 20 73  d..** ^Any SQL s
299f0 74 61 74 65 6d 65 6e 74 20 76 61 72 69 61 62 6c  tatement variabl
29a00 65 73 20 74 68 61 74 20 68 61 64 20 76 61 6c 75  es that had valu
29a10 65 73 20 62 6f 75 6e 64 20 74 6f 20 74 68 65 6d  es bound to them
29a20 20 75 73 69 6e 67 0a 2a 2a 20 74 68 65 20 5b 73   using.** the [s
29a30 71 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62  qlite3_bind_blob
29a40 20 7c 20 73 71 6c 69 74 65 33 5f 62 69 6e 64 5f   | sqlite3_bind_
29a50 2a 28 29 20 41 50 49 5d 20 72 65 74 61 69 6e 20  *() API] retain 
29a60 74 68 65 69 72 20 76 61 6c 75 65 73 2e 0a 2a 2a  their values..**
29a70 20 55 73 65 20 5b 73 71 6c 69 74 65 33 5f 63 6c   Use [sqlite3_cl
29a80 65 61 72 5f 62 69 6e 64 69 6e 67 73 28 29 5d 20  ear_bindings()] 
29a90 74 6f 20 72 65 73 65 74 20 74 68 65 20 62 69 6e  to reset the bin
29aa0 64 69 6e 67 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  dings..**.** ^Th
29ab0 65 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  e [sqlite3_reset
29ac0 28 53 29 5d 20 69 6e 74 65 72 66 61 63 65 20 72  (S)] interface r
29ad0 65 73 65 74 73 20 74 68 65 20 5b 70 72 65 70 61  esets the [prepa
29ae0 72 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53  red statement] S
29af0 0a 2a 2a 20 62 61 63 6b 20 74 6f 20 74 68 65 20  .** back to the 
29b00 62 65 67 69 6e 6e 69 6e 67 20 6f 66 20 69 74 73  beginning of its
29b10 20 70 72 6f 67 72 61 6d 2e 0a 2a 2a 0a 2a 2a 20   program..**.** 
29b20 5e 49 66 20 74 68 65 20 6d 6f 73 74 20 72 65 63  ^If the most rec
29b30 65 6e 74 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c  ent call to [sql
29b40 69 74 65 33 5f 73 74 65 70 28 53 29 5d 20 66 6f  ite3_step(S)] fo
29b50 72 20 74 68 65 0a 2a 2a 20 5b 70 72 65 70 61 72  r the.** [prepar
29b60 65 64 20 73 74 61 74 65 6d 65 6e 74 5d 20 53 20  ed statement] S 
29b70 72 65 74 75 72 6e 65 64 20 5b 53 51 4c 49 54 45  returned [SQLITE
29b80 5f 52 4f 57 5d 20 6f 72 20 5b 53 51 4c 49 54 45  _ROW] or [SQLITE
29b90 5f 44 4f 4e 45 5d 2c 0a 2a 2a 20 6f 72 20 69 66  _DONE],.** or if
29ba0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 53   [sqlite3_step(S
29bb0 29 5d 20 68 61 73 20 6e 65 76 65 72 20 62 65 66  )] has never bef
29bc0 6f 72 65 20 62 65 65 6e 20 63 61 6c 6c 65 64 20  ore been called 
29bd0 6f 6e 20 53 2c 0a 2a 2a 20 74 68 65 6e 20 5b 73  on S,.** then [s
29be0 71 6c 69 74 65 33 5f 72 65 73 65 74 28 53 29 5d  qlite3_reset(S)]
29bf0 20 72 65 74 75 72 6e 73 20 5b 53 51 4c 49 54 45   returns [SQLITE
29c00 5f 4f 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20  _OK]..**.** ^If 
29c10 74 68 65 20 6d 6f 73 74 20 72 65 63 65 6e 74 20  the most recent 
29c20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69 74 65 33  call to [sqlite3
29c30 5f 73 74 65 70 28 53 29 5d 20 66 6f 72 20 74 68  _step(S)] for th
29c40 65 0a 2a 2a 20 5b 70 72 65 70 61 72 65 64 20 73  e.** [prepared s
29c50 74 61 74 65 6d 65 6e 74 5d 20 53 20 69 6e 64 69  tatement] S indi
29c60 63 61 74 65 64 20 61 6e 20 65 72 72 6f 72 2c 20  cated an error, 
29c70 74 68 65 6e 0a 2a 2a 20 5b 73 71 6c 69 74 65 33  then.** [sqlite3
29c80 5f 72 65 73 65 74 28 53 29 5d 20 72 65 74 75 72  _reset(S)] retur
29c90 6e 73 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74  ns an appropriat
29ca0 65 20 5b 65 72 72 6f 72 20 63 6f 64 65 5d 2e 0a  e [error code]..
29cb0 2a 2a 0a 2a 2a 20 5e 54 68 65 20 5b 73 71 6c 69  **.** ^The [sqli
29cc0 74 65 33 5f 72 65 73 65 74 28 53 29 5d 20 69 6e  te3_reset(S)] in
29cd0 74 65 72 66 61 63 65 20 64 6f 65 73 20 6e 6f 74  terface does not
29ce0 20 63 68 61 6e 67 65 20 74 68 65 20 76 61 6c 75   change the valu
29cf0 65 73 0a 2a 2a 20 6f 66 20 61 6e 79 20 5b 73 71  es.** of any [sq
29d00 6c 69 74 65 33 5f 62 69 6e 64 5f 62 6c 6f 62 7c  lite3_bind_blob|
29d10 62 69 6e 64 69 6e 67 73 5d 20 6f 6e 20 74 68 65  bindings] on the
29d20 20 5b 70 72 65 70 61 72 65 64 20 73 74 61 74 65   [prepared state
29d30 6d 65 6e 74 5d 20 53 2e 0a 2a 2f 0a 69 6e 74 20  ment] S..*/.int 
29d40 73 71 6c 69 74 65 33 5f 72 65 73 65 74 28 73 71  sqlite3_reset(sq
29d50 6c 69 74 65 33 5f 73 74 6d 74 20 2a 70 53 74 6d  lite3_stmt *pStm
29d60 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  t);../*.** CAPI3
29d70 52 45 46 3a 20 43 72 65 61 74 65 20 4f 72 20 52  REF: Create Or R
29d80 65 64 65 66 69 6e 65 20 53 51 4c 20 46 75 6e 63  edefine SQL Func
29d90 74 69 6f 6e 73 0a 2a 2a 20 4b 45 59 57 4f 52 44  tions.** KEYWORD
29da0 53 3a 20 7b 66 75 6e 63 74 69 6f 6e 20 63 72 65  S: {function cre
29db0 61 74 69 6f 6e 20 72 6f 75 74 69 6e 65 73 7d 0a  ation routines}.
29dc0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
29dd0 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29de0 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 7d 0a  d SQL function}.
29df0 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 70  ** KEYWORDS: {ap
29e00 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65  plication-define
29e10 64 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 7d  d SQL functions}
29e20 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 66 75  .**.** ^These fu
29e30 6e 63 74 69 6f 6e 73 20 28 63 6f 6c 6c 65 63 74  nctions (collect
29e40 69 76 65 6c 79 20 6b 6e 6f 77 6e 20 61 73 20 22  ively known as "
29e50 66 75 6e 63 74 69 6f 6e 20 63 72 65 61 74 69 6f  function creatio
29e60 6e 20 72 6f 75 74 69 6e 65 73 22 29 0a 2a 2a 20  n routines").** 
29e70 61 72 65 20 75 73 65 64 20 74 6f 20 61 64 64 20  are used to add 
29e80 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6f 72  SQL functions or
29e90 20 61 67 67 72 65 67 61 74 65 73 20 6f 72 20 74   aggregates or t
29ea0 6f 20 72 65 64 65 66 69 6e 65 20 74 68 65 20 62  o redefine the b
29eb0 65 68 61 76 69 6f 72 0a 2a 2a 20 6f 66 20 65 78  ehavior.** of ex
29ec0 69 73 74 69 6e 67 20 53 51 4c 20 66 75 6e 63 74  isting SQL funct
29ed0 69 6f 6e 73 20 6f 72 20 61 67 67 72 65 67 61 74  ions or aggregat
29ee0 65 73 2e 20 20 54 68 65 20 6f 6e 6c 79 20 64 69  es.  The only di
29ef0 66 66 65 72 65 6e 63 65 73 20 62 65 74 77 65 65  fferences betwee
29f00 6e 0a 2a 2a 20 74 68 65 73 65 20 72 6f 75 74 69  n.** these routi
29f10 6e 65 73 20 61 72 65 20 74 68 65 20 74 65 78 74  nes are the text
29f20 20 65 6e 63 6f 64 69 6e 67 20 65 78 70 65 63 74   encoding expect
29f30 65 64 20 66 6f 72 0a 2a 2a 20 74 68 65 20 73 65  ed for.** the se
29f40 63 6f 6e 64 20 70 61 72 61 6d 65 74 65 72 20 28  cond parameter (
29f50 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 20  the name of the 
29f60 66 75 6e 63 74 69 6f 6e 20 62 65 69 6e 67 20 63  function being c
29f70 72 65 61 74 65 64 29 0a 2a 2a 20 61 6e 64 20 74  reated).** and t
29f80 68 65 20 70 72 65 73 65 6e 63 65 20 6f 72 20 61  he presence or a
29f90 62 73 65 6e 63 65 20 6f 66 20 61 20 64 65 73 74  bsence of a dest
29fa0 72 75 63 74 6f 72 20 63 61 6c 6c 62 61 63 6b 20  ructor callback 
29fb0 66 6f 72 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69  for.** the appli
29fc0 63 61 74 69 6f 6e 20 64 61 74 61 20 70 6f 69 6e  cation data poin
29fd0 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ter..**.** ^The 
29fe0 66 69 72 73 74 20 70 61 72 61 6d 65 74 65 72 20  first parameter 
29ff0 69 73 20 74 68 65 20 5b 64 61 74 61 62 61 73 65  is the [database
2a000 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 74 6f 20   connection] to 
2a010 77 68 69 63 68 20 74 68 65 20 53 51 4c 0a 2a 2a  which the SQL.**
2a020 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 74 6f 20   function is to 
2a030 62 65 20 61 64 64 65 64 2e 20 20 5e 49 66 20 61  be added.  ^If a
2a040 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 20 75 73  n application us
2a050 65 73 20 6d 6f 72 65 20 74 68 61 6e 20 6f 6e 65  es more than one
2a060 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63 6f 6e   database.** con
2a070 6e 65 63 74 69 6f 6e 20 74 68 65 6e 20 61 70 70  nection then app
2a080 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2a090 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73 20 6d   SQL functions m
2a0a0 75 73 74 20 62 65 20 61 64 64 65 64 0a 2a 2a 20  ust be added.** 
2a0b0 74 6f 20 65 61 63 68 20 64 61 74 61 62 61 73 65  to each database
2a0c0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 73 65 70 61   connection sepa
2a0d0 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54  rately..**.** ^T
2a0e0 68 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65  he second parame
2a0f0 74 65 72 20 69 73 20 74 68 65 20 6e 61 6d 65 20  ter is the name 
2a100 6f 66 20 74 68 65 20 53 51 4c 20 66 75 6e 63 74  of the SQL funct
2a110 69 6f 6e 20 74 6f 20 62 65 20 63 72 65 61 74 65  ion to be create
2a120 64 20 6f 72 0a 2a 2a 20 72 65 64 65 66 69 6e 65  d or.** redefine
2a130 64 2e 20 20 5e 54 68 65 20 6c 65 6e 67 74 68 20  d.  ^The length 
2a140 6f 66 20 74 68 65 20 6e 61 6d 65 20 69 73 20 6c  of the name is l
2a150 69 6d 69 74 65 64 20 74 6f 20 32 35 35 20 62 79  imited to 255 by
2a160 74 65 73 20 69 6e 20 61 20 55 54 46 2d 38 0a 2a  tes in a UTF-8.*
2a170 2a 20 72 65 70 72 65 73 65 6e 74 61 74 69 6f 6e  * representation
2a180 2c 20 65 78 63 6c 75 73 69 76 65 20 6f 66 20 74  , exclusive of t
2a190 68 65 20 7a 65 72 6f 2d 74 65 72 6d 69 6e 61 74  he zero-terminat
2a1a0 6f 72 2e 20 20 5e 4e 6f 74 65 20 74 68 61 74 20  or.  ^Note that 
2a1b0 74 68 65 20 6e 61 6d 65 0a 2a 2a 20 6c 65 6e 67  the name.** leng
2a1c0 74 68 20 6c 69 6d 69 74 20 69 73 20 69 6e 20 55  th limit is in U
2a1d0 54 46 2d 38 20 62 79 74 65 73 2c 20 6e 6f 74 20  TF-8 bytes, not 
2a1e0 63 68 61 72 61 63 74 65 72 73 20 6e 6f 72 20 55  characters nor U
2a1f0 54 46 2d 31 36 20 62 79 74 65 73 2e 20 20 0a 2a  TF-16 bytes.  .*
2a200 2a 20 5e 41 6e 79 20 61 74 74 65 6d 70 74 20 74  * ^Any attempt t
2a210 6f 20 63 72 65 61 74 65 20 61 20 66 75 6e 63 74  o create a funct
2a220 69 6f 6e 20 77 69 74 68 20 61 20 6c 6f 6e 67 65  ion with a longe
2a230 72 20 6e 61 6d 65 0a 2a 2a 20 77 69 6c 6c 20 72  r name.** will r
2a240 65 73 75 6c 74 20 69 6e 20 5b 53 51 4c 49 54 45  esult in [SQLITE
2a250 5f 4d 49 53 55 53 45 5d 20 62 65 69 6e 67 20 72  _MISUSE] being r
2a260 65 74 75 72 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  eturned..**.** ^
2a270 54 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65  The third parame
2a280 74 65 72 20 28 6e 41 72 67 29 0a 2a 2a 20 69 73  ter (nArg).** is
2a290 20 74 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 61   the number of a
2a2a0 72 67 75 6d 65 6e 74 73 20 74 68 61 74 20 74 68  rguments that th
2a2b0 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f  e SQL function o
2a2c0 72 0a 2a 2a 20 61 67 67 72 65 67 61 74 65 20 74  r.** aggregate t
2a2d0 61 6b 65 73 2e 20 5e 49 66 20 74 68 69 73 20 70  akes. ^If this p
2a2e0 61 72 61 6d 65 74 65 72 20 69 73 20 2d 31 2c 20  arameter is -1, 
2a2f0 74 68 65 6e 20 74 68 65 20 53 51 4c 20 66 75 6e  then the SQL fun
2a300 63 74 69 6f 6e 20 6f 72 0a 2a 2a 20 61 67 67 72  ction or.** aggr
2a310 65 67 61 74 65 20 6d 61 79 20 74 61 6b 65 20 61  egate may take a
2a320 6e 79 20 6e 75 6d 62 65 72 20 6f 66 20 61 72 67  ny number of arg
2a330 75 6d 65 6e 74 73 20 62 65 74 77 65 65 6e 20 30  uments between 0
2a340 20 61 6e 64 20 74 68 65 20 6c 69 6d 69 74 0a 2a   and the limit.*
2a350 2a 20 73 65 74 20 62 79 20 5b 73 71 6c 69 74 65  * set by [sqlite
2a360 33 5f 6c 69 6d 69 74 5d 28 5b 53 51 4c 49 54 45  3_limit]([SQLITE
2a370 5f 4c 49 4d 49 54 5f 46 55 4e 43 54 49 4f 4e 5f  _LIMIT_FUNCTION_
2a380 41 52 47 5d 29 2e 20 20 49 66 20 74 68 65 20 74  ARG]).  If the t
2a390 68 69 72 64 0a 2a 2a 20 70 61 72 61 6d 65 74 65  hird.** paramete
2a3a0 72 20 69 73 20 6c 65 73 73 20 74 68 61 6e 20 2d  r is less than -
2a3b0 31 20 6f 72 20 67 72 65 61 74 65 72 20 74 68 61  1 or greater tha
2a3c0 6e 20 31 32 37 20 74 68 65 6e 20 74 68 65 20 62  n 127 then the b
2a3d0 65 68 61 76 69 6f 72 20 69 73 0a 2a 2a 20 75 6e  ehavior is.** un
2a3e0 64 65 66 69 6e 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  defined..**.** ^
2a3f0 54 68 65 20 66 6f 75 72 74 68 20 70 61 72 61 6d  The fourth param
2a400 65 74 65 72 2c 20 65 54 65 78 74 52 65 70 2c 20  eter, eTextRep, 
2a410 73 70 65 63 69 66 69 65 73 20 77 68 61 74 0a 2a  specifies what.*
2a420 2a 20 5b 53 51 4c 49 54 45 5f 55 54 46 38 20 7c  * [SQLITE_UTF8 |
2a430 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 5d 20   text encoding] 
2a440 74 68 69 73 20 53 51 4c 20 66 75 6e 63 74 69 6f  this SQL functio
2a450 6e 20 70 72 65 66 65 72 73 20 66 6f 72 0a 2a 2a  n prefers for.**
2a460 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 73 2e   its parameters.
2a470 20 20 45 76 65 72 79 20 53 51 4c 20 66 75 6e 63    Every SQL func
2a480 74 69 6f 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74  tion implementat
2a490 69 6f 6e 20 6d 75 73 74 20 62 65 20 61 62 6c 65  ion must be able
2a4a0 20 74 6f 20 77 6f 72 6b 0a 2a 2a 20 77 69 74 68   to work.** with
2a4b0 20 55 54 46 2d 38 2c 20 55 54 46 2d 31 36 6c 65   UTF-8, UTF-16le
2a4c0 2c 20 6f 72 20 55 54 46 2d 31 36 62 65 2e 20 20  , or UTF-16be.  
2a4d0 42 75 74 20 73 6f 6d 65 20 69 6d 70 6c 65 6d 65  But some impleme
2a4e0 6e 74 61 74 69 6f 6e 73 20 6d 61 79 20 62 65 0a  ntations may be.
2a4f0 2a 2a 20 6d 6f 72 65 20 65 66 66 69 63 69 65 6e  ** more efficien
2a500 74 20 77 69 74 68 20 6f 6e 65 20 65 6e 63 6f 64  t with one encod
2a510 69 6e 67 20 74 68 61 6e 20 61 6e 6f 74 68 65 72  ing than another
2a520 2e 20 20 5e 41 6e 20 61 70 70 6c 69 63 61 74 69  .  ^An applicati
2a530 6f 6e 20 6d 61 79 0a 2a 2a 20 69 6e 76 6f 6b 65  on may.** invoke
2a540 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f   sqlite3_create_
2a550 66 75 6e 63 74 69 6f 6e 28 29 20 6f 72 20 73 71  function() or sq
2a560 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e  lite3_create_fun
2a570 63 74 69 6f 6e 31 36 28 29 20 6d 75 6c 74 69 70  ction16() multip
2a580 6c 65 0a 2a 2a 20 74 69 6d 65 73 20 77 69 74 68  le.** times with
2a590 20 74 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69   the same functi
2a5a0 6f 6e 20 62 75 74 20 77 69 74 68 20 64 69 66 66  on but with diff
2a5b0 65 72 65 6e 74 20 76 61 6c 75 65 73 20 6f 66 20  erent values of 
2a5c0 65 54 65 78 74 52 65 70 2e 0a 2a 2a 20 5e 57 68  eTextRep..** ^Wh
2a5d0 65 6e 20 6d 75 6c 74 69 70 6c 65 20 69 6d 70 6c  en multiple impl
2a5e0 65 6d 65 6e 74 61 74 69 6f 6e 73 20 6f 66 20 74  ementations of t
2a5f0 68 65 20 73 61 6d 65 20 66 75 6e 63 74 69 6f 6e  he same function
2a600 20 61 72 65 20 61 76 61 69 6c 61 62 6c 65 2c 20   are available, 
2a610 53 51 4c 69 74 65 0a 2a 2a 20 77 69 6c 6c 20 70  SQLite.** will p
2a620 69 63 6b 20 74 68 65 20 6f 6e 65 20 74 68 61 74  ick the one that
2a630 20 69 6e 76 6f 6c 76 65 73 20 74 68 65 20 6c 65   involves the le
2a640 61 73 74 20 61 6d 6f 75 6e 74 20 6f 66 20 64 61  ast amount of da
2a650 74 61 20 63 6f 6e 76 65 72 73 69 6f 6e 2e 0a 2a  ta conversion..*
2a660 2a 20 49 66 20 74 68 65 72 65 20 69 73 20 6f 6e  * If there is on
2a670 6c 79 20 61 20 73 69 6e 67 6c 65 20 69 6d 70 6c  ly a single impl
2a680 65 6d 65 6e 74 61 74 69 6f 6e 20 77 68 69 63 68  ementation which
2a690 20 64 6f 65 73 20 6e 6f 74 20 63 61 72 65 20 77   does not care w
2a6a0 68 61 74 20 74 65 78 74 0a 2a 2a 20 65 6e 63 6f  hat text.** enco
2a6b0 64 69 6e 67 20 69 73 20 75 73 65 64 2c 20 74 68  ding is used, th
2a6c0 65 6e 20 74 68 65 20 66 6f 75 72 74 68 20 61 72  en the fourth ar
2a6d0 67 75 6d 65 6e 74 20 73 68 6f 75 6c 64 20 62 65  gument should be
2a6e0 20 5b 53 51 4c 49 54 45 5f 41 4e 59 5d 2e 0a 2a   [SQLITE_ANY]..*
2a6f0 2a 0a 2a 2a 20 5e 28 54 68 65 20 66 69 66 74 68  *.** ^(The fifth
2a700 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 61 6e   parameter is an
2a710 20 61 72 62 69 74 72 61 72 79 20 70 6f 69 6e 74   arbitrary point
2a720 65 72 2e 20 20 54 68 65 20 69 6d 70 6c 65 6d 65  er.  The impleme
2a730 6e 74 61 74 69 6f 6e 20 6f 66 20 74 68 65 0a 2a  ntation of the.*
2a740 2a 20 66 75 6e 63 74 69 6f 6e 20 63 61 6e 20 67  * function can g
2a750 61 69 6e 20 61 63 63 65 73 73 20 74 6f 20 74 68  ain access to th
2a760 69 73 20 70 6f 69 6e 74 65 72 20 75 73 69 6e 67  is pointer using
2a770 20 5b 73 71 6c 69 74 65 33 5f 75 73 65 72 5f 64   [sqlite3_user_d
2a780 61 74 61 28 29 5d 2e 29 5e 0a 2a 2a 0a 2a 2a 20  ata()].)^.**.** 
2a790 5e 54 68 65 20 73 69 78 74 68 2c 20 73 65 76 65  ^The sixth, seve
2a7a0 6e 74 68 20 61 6e 64 20 65 69 67 68 74 68 20 70  nth and eighth p
2a7b0 61 72 61 6d 65 74 65 72 73 2c 20 78 46 75 6e 63  arameters, xFunc
2a7c0 2c 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  , xStep and xFin
2a7d0 61 6c 2c 20 61 72 65 0a 2a 2a 20 70 6f 69 6e 74  al, are.** point
2a7e0 65 72 73 20 74 6f 20 43 2d 6c 61 6e 67 75 61 67  ers to C-languag
2a7f0 65 20 66 75 6e 63 74 69 6f 6e 73 20 74 68 61 74  e functions that
2a800 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68 65 20 53   implement the S
2a810 51 4c 20 66 75 6e 63 74 69 6f 6e 20 6f 72 0a 2a  QL function or.*
2a820 2a 20 61 67 67 72 65 67 61 74 65 2e 20 5e 41 20  * aggregate. ^A 
2a830 73 63 61 6c 61 72 20 53 51 4c 20 66 75 6e 63 74  scalar SQL funct
2a840 69 6f 6e 20 72 65 71 75 69 72 65 73 20 61 6e 20  ion requires an 
2a850 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f  implementation o
2a860 66 20 74 68 65 20 78 46 75 6e 63 0a 2a 2a 20 63  f the xFunc.** c
2a870 61 6c 6c 62 61 63 6b 20 6f 6e 6c 79 3b 20 4e 55  allback only; NU
2a880 4c 4c 20 70 6f 69 6e 74 65 72 73 20 6d 75 73 74  LL pointers must
2a890 20 62 65 20 70 61 73 73 65 64 20 61 73 20 74 68   be passed as th
2a8a0 65 20 78 53 74 65 70 20 61 6e 64 20 78 46 69 6e  e xStep and xFin
2a8b0 61 6c 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72 73  al.** parameters
2a8c0 2e 20 5e 41 6e 20 61 67 67 72 65 67 61 74 65 20  . ^An aggregate 
2a8d0 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 72 65 71  SQL function req
2a8e0 75 69 72 65 73 20 61 6e 20 69 6d 70 6c 65 6d 65  uires an impleme
2a8f0 6e 74 61 74 69 6f 6e 20 6f 66 20 78 53 74 65 70  ntation of xStep
2a900 0a 2a 2a 20 61 6e 64 20 78 46 69 6e 61 6c 20 61  .** and xFinal a
2a910 6e 64 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 20  nd NULL pointer 
2a920 6d 75 73 74 20 62 65 20 70 61 73 73 65 64 20 66  must be passed f
2a930 6f 72 20 78 46 75 6e 63 2e 20 5e 54 6f 20 64 65  or xFunc. ^To de
2a940 6c 65 74 65 20 61 6e 20 65 78 69 73 74 69 6e 67  lete an existing
2a950 0a 2a 2a 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  .** SQL function
2a960 20 6f 72 20 61 67 67 72 65 67 61 74 65 2c 20 70   or aggregate, p
2a970 61 73 73 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72  ass NULL pointer
2a980 73 20 66 6f 72 20 61 6c 6c 20 74 68 72 65 65 20  s for all three 
2a990 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 63 61 6c 6c  function.** call
2a9a0 62 61 63 6b 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 49  backs..**.** ^(I
2a9b0 66 20 74 68 65 20 6e 69 6e 74 68 20 70 61 72 61  f the ninth para
2a9c0 6d 65 74 65 72 20 74 6f 20 73 71 6c 69 74 65 33  meter to sqlite3
2a9d0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2a9e0 5f 76 32 28 29 20 69 73 20 6e 6f 74 20 4e 55 4c  _v2() is not NUL
2a9f0 4c 2c 0a 2a 2a 20 74 68 65 6e 20 69 74 20 69 73  L,.** then it is
2aa00 20 64 65 73 74 72 75 63 74 6f 72 20 66 6f 72 20   destructor for 
2aa10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2aa20 64 61 74 61 20 70 6f 69 6e 74 65 72 2e 20 0a 2a  data pointer. .*
2aa30 2a 20 54 68 65 20 64 65 73 74 72 75 63 74 6f 72  * The destructor
2aa40 20 69 73 20 69 6e 76 6f 6b 65 64 20 77 68 65 6e   is invoked when
2aa50 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 69 73   the function is
2aa60 20 64 65 6c 65 74 65 64 2c 20 65 69 74 68 65 72   deleted, either
2aa70 20 62 79 20 62 65 69 6e 67 0a 2a 2a 20 6f 76 65   by being.** ove
2aa80 72 6c 6f 61 64 65 64 20 6f 72 20 77 68 65 6e 20  rloaded or when 
2aa90 74 68 65 20 64 61 74 61 62 61 73 65 20 63 6f 6e  the database con
2aaa0 6e 65 63 74 69 6f 6e 20 63 6c 6f 73 65 73 2e 29  nection closes.)
2aab0 5e 0a 2a 2a 20 5e 54 68 65 20 64 65 73 74 72 75  ^.** ^The destru
2aac0 63 74 6f 72 20 69 73 20 61 6c 73 6f 20 69 6e 76  ctor is also inv
2aad0 6f 6b 65 64 20 69 66 20 74 68 65 20 63 61 6c 6c  oked if the call
2aae0 20 74 6f 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63   to.** sqlite3_c
2aaf0 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76  reate_function_v
2ab00 32 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 57  2() fails..** ^W
2ab10 68 65 6e 20 74 68 65 20 64 65 73 74 72 75 63 74  hen the destruct
2ab20 6f 72 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  or callback of t
2ab30 68 65 20 74 65 6e 74 68 20 70 61 72 61 6d 65 74  he tenth paramet
2ab40 65 72 20 69 73 20 69 6e 76 6f 6b 65 64 2c 20 69  er is invoked, i
2ab50 74 0a 2a 2a 20 69 73 20 70 61 73 73 65 64 20 61  t.** is passed a
2ab60 20 73 69 6e 67 6c 65 20 61 72 67 75 6d 65 6e 74   single argument
2ab70 20 77 68 69 63 68 20 69 73 20 61 20 63 6f 70 79   which is a copy
2ab80 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61 74   of the applicat
2ab90 69 6f 6e 20 64 61 74 61 20 0a 2a 2a 20 70 6f 69  ion data .** poi
2aba0 6e 74 65 72 20 77 68 69 63 68 20 77 61 73 20 74  nter which was t
2abb0 68 65 20 66 69 66 74 68 20 70 61 72 61 6d 65 74  he fifth paramet
2abc0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 63 72  er to sqlite3_cr
2abd0 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f 76 32  eate_function_v2
2abe0 28 29 2e 0a 2a 2a 0a 2a 2a 20 5e 49 74 20 69 73  ()..**.** ^It is
2abf0 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 72 65   permitted to re
2ac00 67 69 73 74 65 72 20 6d 75 6c 74 69 70 6c 65 20  gister multiple 
2ac10 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 20  implementations 
2ac20 6f 66 20 74 68 65 20 73 61 6d 65 0a 2a 2a 20 66  of the same.** f
2ac30 75 6e 63 74 69 6f 6e 73 20 77 69 74 68 20 74 68  unctions with th
2ac40 65 20 73 61 6d 65 20 6e 61 6d 65 20 62 75 74 20  e same name but 
2ac50 77 69 74 68 20 65 69 74 68 65 72 20 64 69 66 66  with either diff
2ac60 65 72 69 6e 67 20 6e 75 6d 62 65 72 73 20 6f 66  ering numbers of
2ac70 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 73 20 6f 72  .** arguments or
2ac80 20 64 69 66 66 65 72 69 6e 67 20 70 72 65 66 65   differing prefe
2ac90 72 72 65 64 20 74 65 78 74 20 65 6e 63 6f 64 69  rred text encodi
2aca0 6e 67 73 2e 20 20 5e 53 51 4c 69 74 65 20 77 69  ngs.  ^SQLite wi
2acb0 6c 6c 20 75 73 65 0a 2a 2a 20 74 68 65 20 69 6d  ll use.** the im
2acc0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 74 68 61  plementation tha
2acd0 74 20 6d 6f 73 74 20 63 6c 6f 73 65 6c 79 20 6d  t most closely m
2ace0 61 74 63 68 65 73 20 74 68 65 20 77 61 79 20 69  atches the way i
2acf0 6e 20 77 68 69 63 68 20 74 68 65 0a 2a 2a 20 53  n which the.** S
2ad00 51 4c 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 75  QL function is u
2ad10 73 65 64 2e 20 20 5e 41 20 66 75 6e 63 74 69 6f  sed.  ^A functio
2ad20 6e 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e  n implementation
2ad30 20 77 69 74 68 20 61 20 6e 6f 6e 2d 6e 65 67 61   with a non-nega
2ad40 74 69 76 65 0a 2a 2a 20 6e 41 72 67 20 70 61 72  tive.** nArg par
2ad50 61 6d 65 74 65 72 20 69 73 20 61 20 62 65 74 74  ameter is a bett
2ad60 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61 20  er match than a 
2ad70 66 75 6e 63 74 69 6f 6e 20 69 6d 70 6c 65 6d 65  function impleme
2ad80 6e 74 61 74 69 6f 6e 20 77 69 74 68 0a 2a 2a 20  ntation with.** 
2ad90 61 20 6e 65 67 61 74 69 76 65 20 6e 41 72 67 2e  a negative nArg.
2ada0 20 20 5e 41 20 66 75 6e 63 74 69 6f 6e 20 77 68    ^A function wh
2adb0 65 72 65 20 74 68 65 20 70 72 65 66 65 72 72 65  ere the preferre
2adc0 64 20 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 0a  d text encoding.
2add0 2a 2a 20 6d 61 74 63 68 65 73 20 74 68 65 20 64  ** matches the d
2ade0 61 74 61 62 61 73 65 20 65 6e 63 6f 64 69 6e 67  atabase encoding
2adf0 20 69 73 20 61 20 62 65 74 74 65 72 0a 2a 2a 20   is a better.** 
2ae00 6d 61 74 63 68 20 74 68 61 6e 20 61 20 66 75 6e  match than a fun
2ae10 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68 65 20  ction where the 
2ae20 65 6e 63 6f 64 69 6e 67 20 69 73 20 64 69 66 66  encoding is diff
2ae30 65 72 65 6e 74 2e 20 20 0a 2a 2a 20 5e 41 20 66  erent.  .** ^A f
2ae40 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20 74 68  unction where th
2ae50 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66 66 65  e encoding diffe
2ae60 72 65 6e 63 65 20 69 73 20 62 65 74 77 65 65 6e  rence is between
2ae70 20 55 54 46 31 36 6c 65 20 61 6e 64 20 55 54 46   UTF16le and UTF
2ae80 31 36 62 65 0a 2a 2a 20 69 73 20 61 20 63 6c 6f  16be.** is a clo
2ae90 73 65 72 20 6d 61 74 63 68 20 74 68 61 6e 20 61  ser match than a
2aea0 20 66 75 6e 63 74 69 6f 6e 20 77 68 65 72 65 20   function where 
2aeb0 74 68 65 20 65 6e 63 6f 64 69 6e 67 20 64 69 66  the encoding dif
2aec0 66 65 72 65 6e 63 65 20 69 73 0a 2a 2a 20 62 65  ference is.** be
2aed0 74 77 65 65 6e 20 55 54 46 38 20 61 6e 64 20 55  tween UTF8 and U
2aee0 54 46 31 36 2e 0a 2a 2a 0a 2a 2a 20 5e 42 75 69  TF16..**.** ^Bui
2aef0 6c 74 2d 69 6e 20 66 75 6e 63 74 69 6f 6e 73 20  lt-in functions 
2af00 6d 61 79 20 62 65 20 6f 76 65 72 6c 6f 61 64 65  may be overloade
2af10 64 20 62 79 20 6e 65 77 20 61 70 70 6c 69 63 61  d by new applica
2af20 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2af30 63 74 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 41  ctions..**.** ^A
2af40 6e 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  n application-de
2af50 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 69  fined function i
2af60 73 20 70 65 72 6d 69 74 74 65 64 20 74 6f 20 63  s permitted to c
2af70 61 6c 6c 20 6f 74 68 65 72 0a 2a 2a 20 53 51 4c  all other.** SQL
2af80 69 74 65 20 69 6e 74 65 72 66 61 63 65 73 2e 20  ite interfaces. 
2af90 20 48 6f 77 65 76 65 72 2c 20 73 75 63 68 20 63   However, such c
2afa0 61 6c 6c 73 20 6d 75 73 74 20 6e 6f 74 0a 2a 2a  alls must not.**
2afb0 20 63 6c 6f 73 65 20 74 68 65 20 64 61 74 61 62   close the datab
2afc0 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6e  ase connection n
2afd0 6f 72 20 66 69 6e 61 6c 69 7a 65 20 6f 72 20 72  or finalize or r
2afe0 65 73 65 74 20 74 68 65 20 70 72 65 70 61 72 65  eset the prepare
2aff0 64 0a 2a 2a 20 73 74 61 74 65 6d 65 6e 74 20 69  d.** statement i
2b000 6e 20 77 68 69 63 68 20 74 68 65 20 66 75 6e 63  n which the func
2b010 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67 2e  tion is running.
2b020 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .*/.int sqlite3_
2b030 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 28  create_function(
2b040 0a 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a  .  sqlite3 *db,.
2b050 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 46    const char *zF
2b060 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a 20 20 69  unctionName,.  i
2b070 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e 74 20 65  nt nArg,.  int e
2b080 54 65 78 74 52 65 70 2c 0a 20 20 76 6f 69 64 20  TextRep,.  void 
2b090 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64 20 28 2a  *pApp,.  void (*
2b0a0 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f 63  xFunc)(sqlite3_c
2b0b0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2b0c0 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2b0d0 76 6f 69 64 20 28 2a 78 53 74 65 70 29 28 73 71  void (*xStep)(sq
2b0e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 69  lite3_context*,i
2b0f0 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  nt,sqlite3_value
2b100 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a 78 46  **),.  void (*xF
2b110 69 6e 61 6c 29 28 73 71 6c 69 74 65 33 5f 63 6f  inal)(sqlite3_co
2b120 6e 74 65 78 74 2a 29 0a 29 3b 0a 69 6e 74 20 73  ntext*).);.int s
2b130 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b140 6e 63 74 69 6f 6e 31 36 28 0a 20 20 73 71 6c 69  nction16(.  sqli
2b150 74 65 33 20 2a 64 62 2c 0a 20 20 63 6f 6e 73 74  te3 *db,.  const
2b160 20 76 6f 69 64 20 2a 7a 46 75 6e 63 74 69 6f 6e   void *zFunction
2b170 4e 61 6d 65 2c 0a 20 20 69 6e 74 20 6e 41 72 67  Name,.  int nArg
2b180 2c 0a 20 20 69 6e 74 20 65 54 65 78 74 52 65 70  ,.  int eTextRep
2b190 2c 0a 20 20 76 6f 69 64 20 2a 70 41 70 70 2c 0a  ,.  void *pApp,.
2b1a0 20 20 76 6f 69 64 20 28 2a 78 46 75 6e 63 29 28    void (*xFunc)(
2b1b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2b1c0 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61 6c  ,int,sqlite3_val
2b1d0 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28 2a  ue**),.  void (*
2b1e0 78 53 74 65 70 29 28 73 71 6c 69 74 65 33 5f 63  xStep)(sqlite3_c
2b1f0 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c 69  ontext*,int,sqli
2b200 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20 20  te3_value**),.  
2b210 76 6f 69 64 20 28 2a 78 46 69 6e 61 6c 29 28 73  void (*xFinal)(s
2b220 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29  qlite3_context*)
2b230 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f  .);.int sqlite3_
2b240 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e 5f  create_function_
2b250 76 32 28 0a 20 20 73 71 6c 69 74 65 33 20 2a 64  v2(.  sqlite3 *d
2b260 62 2c 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  b,.  const char 
2b270 2a 7a 46 75 6e 63 74 69 6f 6e 4e 61 6d 65 2c 0a  *zFunctionName,.
2b280 20 20 69 6e 74 20 6e 41 72 67 2c 0a 20 20 69 6e    int nArg,.  in
2b290 74 20 65 54 65 78 74 52 65 70 2c 0a 20 20 76 6f  t eTextRep,.  vo
2b2a0 69 64 20 2a 70 41 70 70 2c 0a 20 20 76 6f 69 64  id *pApp,.  void
2b2b0 20 28 2a 78 46 75 6e 63 29 28 73 71 6c 69 74 65   (*xFunc)(sqlite
2b2c0 33 5f 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73  3_context*,int,s
2b2d0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c  qlite3_value**),
2b2e0 0a 20 20 76 6f 69 64 20 28 2a 78 53 74 65 70 29  .  void (*xStep)
2b2f0 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2b300 2a 2c 69 6e 74 2c 73 71 6c 69 74 65 33 5f 76 61  *,int,sqlite3_va
2b310 6c 75 65 2a 2a 29 2c 0a 20 20 76 6f 69 64 20 28  lue**),.  void (
2b320 2a 78 46 69 6e 61 6c 29 28 73 71 6c 69 74 65 33  *xFinal)(sqlite3
2b330 5f 63 6f 6e 74 65 78 74 2a 29 2c 0a 20 20 76 6f  _context*),.  vo
2b340 69 64 28 2a 78 44 65 73 74 72 6f 79 29 28 76 6f  id(*xDestroy)(vo
2b350 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  id*).);../*.** C
2b360 41 50 49 33 52 45 46 3a 20 54 65 78 74 20 45 6e  API3REF: Text En
2b370 63 6f 64 69 6e 67 73 0a 2a 2a 0a 2a 2a 20 54 68  codings.**.** Th
2b380 65 73 65 20 63 6f 6e 73 74 61 6e 74 20 64 65 66  ese constant def
2b390 69 6e 65 20 69 6e 74 65 67 65 72 20 63 6f 64 65  ine integer code
2b3a0 73 20 74 68 61 74 20 72 65 70 72 65 73 65 6e 74  s that represent
2b3b0 20 74 68 65 20 76 61 72 69 6f 75 73 0a 2a 2a 20   the various.** 
2b3c0 74 65 78 74 20 65 6e 63 6f 64 69 6e 67 73 20 73  text encodings s
2b3d0 75 70 70 6f 72 74 65 64 20 62 79 20 53 51 4c 69  upported by SQLi
2b3e0 74 65 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  te..*/.#define S
2b3f0 51 4c 49 54 45 5f 55 54 46 38 20 20 20 20 20 20  QLITE_UTF8      
2b400 20 20 20 20 20 31 0a 23 64 65 66 69 6e 65 20 53       1.#define S
2b410 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 20 20 20  QLITE_UTF16LE   
2b420 20 20 20 20 20 32 0a 23 64 65 66 69 6e 65 20 53       2.#define S
2b430 51 4c 49 54 45 5f 55 54 46 31 36 42 45 20 20 20  QLITE_UTF16BE   
2b440 20 20 20 20 20 33 0a 23 64 65 66 69 6e 65 20 53       3.#define S
2b450 51 4c 49 54 45 5f 55 54 46 31 36 20 20 20 20 20  QLITE_UTF16     
2b460 20 20 20 20 20 34 20 20 20 20 2f 2a 20 55 73 65       4    /* Use
2b470 20 6e 61 74 69 76 65 20 62 79 74 65 20 6f 72 64   native byte ord
2b480 65 72 20 2a 2f 0a 23 64 65 66 69 6e 65 20 53 51  er */.#define SQ
2b490 4c 49 54 45 5f 41 4e 59 20 20 20 20 20 20 20 20  LITE_ANY        
2b4a0 20 20 20 20 35 20 20 20 20 2f 2a 20 73 71 6c 69      5    /* sqli
2b4b0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2b4c0 69 6f 6e 20 6f 6e 6c 79 20 2a 2f 0a 23 64 65 66  ion only */.#def
2b4d0 69 6e 65 20 53 51 4c 49 54 45 5f 55 54 46 31 36  ine SQLITE_UTF16
2b4e0 5f 41 4c 49 47 4e 45 44 20 20 38 20 20 20 20 2f  _ALIGNED  8    /
2b4f0 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
2b500 5f 63 6f 6c 6c 61 74 69 6f 6e 20 6f 6e 6c 79 20  _collation only 
2b510 2a 2f 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  */../*.** CAPI3R
2b520 45 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 46  EF: Deprecated F
2b530 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20 44 45 50 52  unctions.** DEPR
2b540 45 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 65  ECATED.**.** The
2b550 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 61 72 65  se functions are
2b560 20 5b 64 65 70 72 65 63 61 74 65 64 5d 2e 20 20   [deprecated].  
2b570 49 6e 20 6f 72 64 65 72 20 74 6f 20 6d 61 69 6e  In order to main
2b580 74 61 69 6e 0a 2a 2a 20 62 61 63 6b 77 61 72 64  tain.** backward
2b590 73 20 63 6f 6d 70 61 74 69 62 69 6c 69 74 79 20  s compatibility 
2b5a0 77 69 74 68 20 6f 6c 64 65 72 20 63 6f 64 65 2c  with older code,
2b5b0 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e 73   these functions
2b5c0 20 63 6f 6e 74 69 6e 75 65 20 0a 2a 2a 20 74 6f   continue .** to
2b5d0 20 62 65 20 73 75 70 70 6f 72 74 65 64 2e 20 20   be supported.  
2b5e0 48 6f 77 65 76 65 72 2c 20 6e 65 77 20 61 70 70  However, new app
2b5f0 6c 69 63 61 74 69 6f 6e 73 20 73 68 6f 75 6c 64  lications should
2b600 20 61 76 6f 69 64 0a 2a 2a 20 74 68 65 20 75 73   avoid.** the us
2b610 65 20 6f 66 20 74 68 65 73 65 20 66 75 6e 63 74  e of these funct
2b620 69 6f 6e 73 2e 20 20 54 6f 20 68 65 6c 70 20 65  ions.  To help e
2b630 6e 63 6f 75 72 61 67 65 20 70 65 6f 70 6c 65 20  ncourage people 
2b640 74 6f 20 61 76 6f 69 64 0a 2a 2a 20 75 73 69 6e  to avoid.** usin
2b650 67 20 74 68 65 73 65 20 66 75 6e 63 74 69 6f 6e  g these function
2b660 73 2c 20 77 65 20 61 72 65 20 6e 6f 74 20 67 6f  s, we are not go
2b670 69 6e 67 20 74 6f 20 74 65 6c 6c 20 79 6f 75 20  ing to tell you 
2b680 77 68 61 74 20 74 68 65 79 20 64 6f 2e 0a 2a 2f  what they do..*/
2b690 0a 23 69 66 6e 64 65 66 20 53 51 4c 49 54 45 5f  .#ifndef SQLITE_
2b6a0 4f 4d 49 54 5f 44 45 50 52 45 43 41 54 45 44 0a  OMIT_DEPRECATED.
2b6b0 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45  SQLITE_DEPRECATE
2b6c0 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 61 67  D int sqlite3_ag
2b6d0 67 72 65 67 61 74 65 5f 63 6f 75 6e 74 28 73 71  gregate_count(sq
2b6e0 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b  lite3_context*);
2b6f0 0a 53 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54  .SQLITE_DEPRECAT
2b700 45 44 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 65  ED int sqlite3_e
2b710 78 70 69 72 65 64 28 73 71 6c 69 74 65 33 5f 73  xpired(sqlite3_s
2b720 74 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45  tmt*);.SQLITE_DE
2b730 50 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c  PRECATED int sql
2b740 69 74 65 33 5f 74 72 61 6e 73 66 65 72 5f 62 69  ite3_transfer_bi
2b750 6e 64 69 6e 67 73 28 73 71 6c 69 74 65 33 5f 73  ndings(sqlite3_s
2b760 74 6d 74 2a 2c 20 73 71 6c 69 74 65 33 5f 73 74  tmt*, sqlite3_st
2b770 6d 74 2a 29 3b 0a 53 51 4c 49 54 45 5f 44 45 50  mt*);.SQLITE_DEP
2b780 52 45 43 41 54 45 44 20 69 6e 74 20 73 71 6c 69  RECATED int sqli
2b790 74 65 33 5f 67 6c 6f 62 61 6c 5f 72 65 63 6f 76  te3_global_recov
2b7a0 65 72 28 76 6f 69 64 29 3b 0a 53 51 4c 49 54 45  er(void);.SQLITE
2b7b0 5f 44 45 50 52 45 43 41 54 45 44 20 76 6f 69 64  _DEPRECATED void
2b7c0 20 73 71 6c 69 74 65 33 5f 74 68 72 65 61 64 5f   sqlite3_thread_
2b7d0 63 6c 65 61 6e 75 70 28 76 6f 69 64 29 3b 0a 53  cleanup(void);.S
2b7e0 51 4c 49 54 45 5f 44 45 50 52 45 43 41 54 45 44  QLITE_DEPRECATED
2b7f0 20 69 6e 74 20 73 71 6c 69 74 65 33 5f 6d 65 6d   int sqlite3_mem
2b800 6f 72 79 5f 61 6c 61 72 6d 28 76 6f 69 64 28 2a  ory_alarm(void(*
2b810 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 5f  )(void*,sqlite3_
2b820 69 6e 74 36 34 2c 69 6e 74 29 2c 76 6f 69 64 2a  int64,int),void*
2b830 2c 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 29 3b  ,sqlite3_int64);
2b840 0a 23 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43  .#endif../*.** C
2b850 41 50 49 33 52 45 46 3a 20 4f 62 74 61 69 6e 69  API3REF: Obtaini
2b860 6e 67 20 53 51 4c 20 46 75 6e 63 74 69 6f 6e 20  ng SQL Function 
2b870 50 61 72 61 6d 65 74 65 72 20 56 61 6c 75 65 73  Parameter Values
2b880 0a 2a 2a 0a 2a 2a 20 54 68 65 20 43 2d 6c 61 6e  .**.** The C-lan
2b890 67 75 61 67 65 20 69 6d 70 6c 65 6d 65 6e 74 61  guage implementa
2b8a0 74 69 6f 6e 20 6f 66 20 53 51 4c 20 66 75 6e 63  tion of SQL func
2b8b0 74 69 6f 6e 73 20 61 6e 64 20 61 67 67 72 65 67  tions and aggreg
2b8c0 61 74 65 73 20 75 73 65 73 0a 2a 2a 20 74 68 69  ates uses.** thi
2b8d0 73 20 73 65 74 20 6f 66 20 69 6e 74 65 72 66 61  s set of interfa
2b8e0 63 65 20 72 6f 75 74 69 6e 65 73 20 74 6f 20 61  ce routines to a
2b8f0 63 63 65 73 73 20 74 68 65 20 70 61 72 61 6d 65  ccess the parame
2b900 74 65 72 20 76 61 6c 75 65 73 20 6f 6e 0a 2a 2a  ter values on.**
2b910 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20 6f 72   the function or
2b920 20 61 67 67 72 65 67 61 74 65 2e 0a 2a 2a 0a 2a   aggregate..**.*
2b930 2a 20 54 68 65 20 78 46 75 6e 63 20 28 66 6f 72  * The xFunc (for
2b940 20 73 63 61 6c 61 72 20 66 75 6e 63 74 69 6f 6e   scalar function
2b950 73 29 20 6f 72 20 78 53 74 65 70 20 28 66 6f 72  s) or xStep (for
2b960 20 61 67 67 72 65 67 61 74 65 73 29 20 70 61 72   aggregates) par
2b970 61 6d 65 74 65 72 73 0a 2a 2a 20 74 6f 20 5b 73  ameters.** to [s
2b980 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b990 6e 63 74 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73  nction()] and [s
2b9a0 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 66 75  qlite3_create_fu
2b9b0 6e 63 74 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 64  nction16()].** d
2b9c0 65 66 69 6e 65 20 63 61 6c 6c 62 61 63 6b 73 20  efine callbacks 
2b9d0 74 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 20 74  that implement t
2b9e0 68 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 73  he SQL functions
2b9f0 20 61 6e 64 20 61 67 67 72 65 67 61 74 65 73 2e   and aggregates.
2ba00 0a 2a 2a 20 54 68 65 20 33 72 64 20 70 61 72 61  .** The 3rd para
2ba10 6d 65 74 65 72 20 74 6f 20 74 68 65 73 65 20 63  meter to these c
2ba20 61 6c 6c 62 61 63 6b 73 20 69 73 20 61 6e 20 61  allbacks is an a
2ba30 72 72 61 79 20 6f 66 20 70 6f 69 6e 74 65 72 73  rray of pointers
2ba40 20 74 6f 0a 2a 2a 20 5b 70 72 6f 74 65 63 74 65   to.** [protecte
2ba50 64 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d  d sqlite3_value]
2ba60 20 6f 62 6a 65 63 74 73 2e 20 20 54 68 65 72 65   objects.  There
2ba70 20 69 73 20 6f 6e 65 20 5b 73 71 6c 69 74 65 33   is one [sqlite3
2ba80 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 66  _value] object f
2ba90 6f 72 0a 2a 2a 20 65 61 63 68 20 70 61 72 61 6d  or.** each param
2baa0 65 74 65 72 20 74 6f 20 74 68 65 20 53 51 4c 20  eter to the SQL 
2bab0 66 75 6e 63 74 69 6f 6e 2e 20 20 54 68 65 73 65  function.  These
2bac0 20 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73   routines are us
2bad0 65 64 20 74 6f 0a 2a 2a 20 65 78 74 72 61 63 74  ed to.** extract
2bae0 20 76 61 6c 75 65 73 20 66 72 6f 6d 20 74 68 65   values from the
2baf0 20 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d   [sqlite3_value]
2bb00 20 6f 62 6a 65 63 74 73 2e 0a 2a 2a 0a 2a 2a 20   objects..**.** 
2bb10 54 68 65 73 65 20 72 6f 75 74 69 6e 65 73 20 77  These routines w
2bb20 6f 72 6b 20 6f 6e 6c 79 20 77 69 74 68 20 5b 70  ork only with [p
2bb30 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bb40 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 73 2e  _value] objects.
2bb50 0a 2a 2a 20 41 6e 79 20 61 74 74 65 6d 70 74 20  .** Any attempt 
2bb60 74 6f 20 75 73 65 20 74 68 65 73 65 20 72 6f 75  to use these rou
2bb70 74 69 6e 65 73 20 6f 6e 20 61 6e 20 5b 75 6e 70  tines on an [unp
2bb80 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65 33  rotected sqlite3
2bb90 5f 76 61 6c 75 65 5d 0a 2a 2a 20 6f 62 6a 65 63  _value].** objec
2bba0 74 20 72 65 73 75 6c 74 73 20 69 6e 20 75 6e 64  t results in und
2bbb0 65 66 69 6e 65 64 20 62 65 68 61 76 69 6f 72 2e  efined behavior.
2bbc0 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20 72 6f  .**.** ^These ro
2bbd0 75 74 69 6e 65 73 20 77 6f 72 6b 20 6a 75 73 74  utines work just
2bbe0 20 6c 69 6b 65 20 74 68 65 20 63 6f 72 72 65 73   like the corres
2bbf0 70 6f 6e 64 69 6e 67 20 5b 63 6f 6c 75 6d 6e 20  ponding [column 
2bc00 61 63 63 65 73 73 20 66 75 6e 63 74 69 6f 6e 73  access functions
2bc10 5d 0a 2a 2a 20 65 78 63 65 70 74 20 74 68 61 74  ].** except that
2bc20 20 20 74 68 65 73 65 20 72 6f 75 74 69 6e 65 73    these routines
2bc30 20 74 61 6b 65 20 61 20 73 69 6e 67 6c 65 20 5b   take a single [
2bc40 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74 65  protected sqlite
2bc50 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 0a  3_value] object.
2bc60 2a 2a 20 70 6f 69 6e 74 65 72 20 69 6e 73 74 65  ** pointer inste
2bc70 61 64 20 6f 66 20 61 20 5b 73 71 6c 69 74 65 33  ad of a [sqlite3
2bc80 5f 73 74 6d 74 2a 5d 20 70 6f 69 6e 74 65 72 20  _stmt*] pointer 
2bc90 61 6e 64 20 61 6e 20 69 6e 74 65 67 65 72 20 63  and an integer c
2bca0 6f 6c 75 6d 6e 20 6e 75 6d 62 65 72 2e 0a 2a 2a  olumn number..**
2bcb0 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33  .** ^The sqlite3
2bcc0 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 29 20  _value_text16() 
2bcd0 69 6e 74 65 72 66 61 63 65 20 65 78 74 72 61 63  interface extrac
2bce0 74 73 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  ts a UTF-16 stri
2bcf0 6e 67 0a 2a 2a 20 69 6e 20 74 68 65 20 6e 61 74  ng.** in the nat
2bd00 69 76 65 20 62 79 74 65 2d 6f 72 64 65 72 20 6f  ive byte-order o
2bd10 66 20 74 68 65 20 68 6f 73 74 20 6d 61 63 68 69  f the host machi
2bd20 6e 65 2e 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c  ne.  ^The.** sql
2bd30 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31  ite3_value_text1
2bd40 36 62 65 28 29 20 61 6e 64 20 73 71 6c 69 74 65  6be() and sqlite
2bd50 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 6c 65  3_value_text16le
2bd60 28 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  () interfaces.**
2bd70 20 65 78 74 72 61 63 74 20 55 54 46 2d 31 36 20   extract UTF-16 
2bd80 73 74 72 69 6e 67 73 20 61 73 20 62 69 67 2d 65  strings as big-e
2bd90 6e 64 69 61 6e 20 61 6e 64 20 6c 69 74 74 6c 65  ndian and little
2bda0 2d 65 6e 64 69 61 6e 20 72 65 73 70 65 63 74 69  -endian respecti
2bdb0 76 65 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  vely..**.** ^(Th
2bdc0 65 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f  e sqlite3_value_
2bdd0 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 29 20 69  numeric_type() i
2bde0 6e 74 65 72 66 61 63 65 20 61 74 74 65 6d 70 74  nterface attempt
2bdf0 73 20 74 6f 20 61 70 70 6c 79 0a 2a 2a 20 6e 75  s to apply.** nu
2be00 6d 65 72 69 63 20 61 66 66 69 6e 69 74 79 20 74  meric affinity t
2be10 6f 20 74 68 65 20 76 61 6c 75 65 2e 20 20 54 68  o the value.  Th
2be20 69 73 20 6d 65 61 6e 73 20 74 68 61 74 20 61 6e  is means that an
2be30 20 61 74 74 65 6d 70 74 20 69 73 0a 2a 2a 20 6d   attempt is.** m
2be40 61 64 65 20 74 6f 20 63 6f 6e 76 65 72 74 20 74  ade to convert t
2be50 68 65 20 76 61 6c 75 65 20 74 6f 20 61 6e 20 69  he value to an i
2be60 6e 74 65 67 65 72 20 6f 72 20 66 6c 6f 61 74 69  nteger or floati
2be70 6e 67 20 70 6f 69 6e 74 2e 20 20 49 66 0a 2a 2a  ng point.  If.**
2be80 20 73 75 63 68 20 61 20 63 6f 6e 76 65 72 73 69   such a conversi
2be90 6f 6e 20 69 73 20 70 6f 73 73 69 62 6c 65 20 77  on is possible w
2bea0 69 74 68 6f 75 74 20 6c 6f 73 73 20 6f 66 20 69  ithout loss of i
2beb0 6e 66 6f 72 6d 61 74 69 6f 6e 20 28 69 6e 20 6f  nformation (in o
2bec0 74 68 65 72 0a 2a 2a 20 77 6f 72 64 73 2c 20 69  ther.** words, i
2bed0 66 20 74 68 65 20 76 61 6c 75 65 20 69 73 20 61  f the value is a
2bee0 20 73 74 72 69 6e 67 20 74 68 61 74 20 6c 6f 6f   string that loo
2bef0 6b 73 20 6c 69 6b 65 20 61 20 6e 75 6d 62 65 72  ks like a number
2bf00 29 0a 2a 2a 20 74 68 65 6e 20 74 68 65 20 63 6f  ).** then the co
2bf10 6e 76 65 72 73 69 6f 6e 20 69 73 20 70 65 72 66  nversion is perf
2bf20 6f 72 6d 65 64 2e 20 20 4f 74 68 65 72 77 69 73  ormed.  Otherwis
2bf30 65 20 6e 6f 20 63 6f 6e 76 65 72 73 69 6f 6e 20  e no conversion 
2bf40 6f 63 63 75 72 73 2e 0a 2a 2a 20 54 68 65 20 5b  occurs..** The [
2bf50 53 51 4c 49 54 45 5f 49 4e 54 45 47 45 52 20 7c  SQLITE_INTEGER |
2bf60 20 64 61 74 61 74 79 70 65 5d 20 61 66 74 65 72   datatype] after
2bf70 20 63 6f 6e 76 65 72 73 69 6f 6e 20 69 73 20 72   conversion is r
2bf80 65 74 75 72 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a  eturned.)^.**.**
2bf90 20 50 6c 65 61 73 65 20 70 61 79 20 70 61 72 74   Please pay part
2bfa0 69 63 75 6c 61 72 20 61 74 74 65 6e 74 69 6f 6e  icular attention
2bfb0 20 74 6f 20 74 68 65 20 66 61 63 74 20 74 68 61   to the fact tha
2bfc0 74 20 74 68 65 20 70 6f 69 6e 74 65 72 20 72 65  t the pointer re
2bfd0 74 75 72 6e 65 64 0a 2a 2a 20 66 72 6f 6d 20 5b  turned.** from [
2bfe0 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 6c  sqlite3_value_bl
2bff0 6f 62 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f  ob()], [sqlite3_
2c000 76 61 6c 75 65 5f 74 65 78 74 28 29 5d 2c 20 6f  value_text()], o
2c010 72 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 76 61  r.** [sqlite3_va
2c020 6c 75 65 5f 74 65 78 74 31 36 28 29 5d 20 63 61  lue_text16()] ca
2c030 6e 20 62 65 20 69 6e 76 61 6c 69 64 61 74 65 64  n be invalidated
2c040 20 62 79 20 61 20 73 75 62 73 65 71 75 65 6e 74   by a subsequent
2c050 20 63 61 6c 6c 20 74 6f 0a 2a 2a 20 5b 73 71 6c   call to.** [sql
2c060 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65 73  ite3_value_bytes
2c070 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 76 61  ()], [sqlite3_va
2c080 6c 75 65 5f 62 79 74 65 73 31 36 28 29 5d 2c 20  lue_bytes16()], 
2c090 5b 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74  [sqlite3_value_t
2c0a0 65 78 74 28 29 5d 2c 0a 2a 2a 20 6f 72 20 5b 73  ext()],.** or [s
2c0b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65 78  qlite3_value_tex
2c0c0 74 31 36 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20 54 68  t16()]..**.** Th
2c0d0 65 73 65 20 72 6f 75 74 69 6e 65 73 20 6d 75 73  ese routines mus
2c0e0 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2c0f0 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2c100 20 61 73 0a 2a 2a 20 74 68 65 20 53 51 4c 20 66   as.** the SQL f
2c110 75 6e 63 74 69 6f 6e 20 74 68 61 74 20 73 75 70  unction that sup
2c120 70 6c 69 65 64 20 74 68 65 20 5b 73 71 6c 69 74  plied the [sqlit
2c130 65 33 5f 76 61 6c 75 65 2a 5d 20 70 61 72 61 6d  e3_value*] param
2c140 65 74 65 72 73 2e 0a 2a 2f 0a 63 6f 6e 73 74 20  eters..*/.const 
2c150 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 76 61  void *sqlite3_va
2c160 6c 75 65 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33  lue_blob(sqlite3
2c170 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71  _value*);.int sq
2c180 6c 69 74 65 33 5f 76 61 6c 75 65 5f 62 79 74 65  lite3_value_byte
2c190 73 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a  s(sqlite3_value*
2c1a0 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 76  );.int sqlite3_v
2c1b0 61 6c 75 65 5f 62 79 74 65 73 31 36 28 73 71 6c  alue_bytes16(sql
2c1c0 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 64 6f  ite3_value*);.do
2c1d0 75 62 6c 65 20 73 71 6c 69 74 65 33 5f 76 61 6c  uble sqlite3_val
2c1e0 75 65 5f 64 6f 75 62 6c 65 28 73 71 6c 69 74 65  ue_double(sqlite
2c1f0 33 5f 76 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73  3_value*);.int s
2c200 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e 74  qlite3_value_int
2c210 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29  (sqlite3_value*)
2c220 3b 0a 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20  ;.sqlite3_int64 
2c230 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 69 6e  sqlite3_value_in
2c240 74 36 34 28 73 71 6c 69 74 65 33 5f 76 61 6c 75  t64(sqlite3_valu
2c250 65 2a 29 3b 0a 63 6f 6e 73 74 20 75 6e 73 69 67  e*);.const unsig
2c260 6e 65 64 20 63 68 61 72 20 2a 73 71 6c 69 74 65  ned char *sqlite
2c270 33 5f 76 61 6c 75 65 5f 74 65 78 74 28 73 71 6c  3_value_text(sql
2c280 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a 63 6f  ite3_value*);.co
2c290 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69 74 65  nst void *sqlite
2c2a0 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36 28 73  3_value_text16(s
2c2b0 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2c2c0 63 6f 6e 73 74 20 76 6f 69 64 20 2a 73 71 6c 69  const void *sqli
2c2d0 74 65 33 5f 76 61 6c 75 65 5f 74 65 78 74 31 36  te3_value_text16
2c2e0 6c 65 28 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  le(sqlite3_value
2c2f0 2a 29 3b 0a 63 6f 6e 73 74 20 76 6f 69 64 20 2a  *);.const void *
2c300 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5f 74 65  sqlite3_value_te
2c310 78 74 31 36 62 65 28 73 71 6c 69 74 65 33 5f 76  xt16be(sqlite3_v
2c320 61 6c 75 65 2a 29 3b 0a 69 6e 74 20 73 71 6c 69  alue*);.int sqli
2c330 74 65 33 5f 76 61 6c 75 65 5f 74 79 70 65 28 73  te3_value_type(s
2c340 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2c350 69 6e 74 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  int sqlite3_valu
2c360 65 5f 6e 75 6d 65 72 69 63 5f 74 79 70 65 28 73  e_numeric_type(s
2c370 71 6c 69 74 65 33 5f 76 61 6c 75 65 2a 29 3b 0a  qlite3_value*);.
2c380 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2c390 20 4f 62 74 61 69 6e 20 41 67 67 72 65 67 61 74   Obtain Aggregat
2c3a0 65 20 46 75 6e 63 74 69 6f 6e 20 43 6f 6e 74 65  e Function Conte
2c3b0 78 74 0a 2a 2a 0a 2a 2a 20 49 6d 70 6c 65 6d 65  xt.**.** Impleme
2c3c0 6e 74 61 74 69 6f 6e 73 20 6f 66 20 61 67 67 72  ntations of aggr
2c3d0 65 67 61 74 65 20 53 51 4c 20 66 75 6e 63 74 69  egate SQL functi
2c3e0 6f 6e 73 20 75 73 65 20 74 68 69 73 0a 2a 2a 20  ons use this.** 
2c3f0 72 6f 75 74 69 6e 65 20 74 6f 20 61 6c 6c 6f 63  routine to alloc
2c400 61 74 65 20 6d 65 6d 6f 72 79 20 66 6f 72 20 73  ate memory for s
2c410 74 6f 72 69 6e 67 20 74 68 65 69 72 20 73 74 61  toring their sta
2c420 74 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66  te..**.** ^The f
2c430 69 72 73 74 20 74 69 6d 65 20 74 68 65 20 73 71  irst time the sq
2c440 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f  lite3_aggregate_
2c450 63 6f 6e 74 65 78 74 28 43 2c 4e 29 20 72 6f 75  context(C,N) rou
2c460 74 69 6e 65 20 69 73 20 63 61 6c 6c 65 64 20 0a  tine is called .
2c470 2a 2a 20 66 6f 72 20 61 20 70 61 72 74 69 63 75  ** for a particu
2c480 6c 61 72 20 61 67 67 72 65 67 61 74 65 20 66 75  lar aggregate fu
2c490 6e 63 74 69 6f 6e 2c 20 53 51 4c 69 74 65 0a 2a  nction, SQLite.*
2c4a0 2a 20 61 6c 6c 6f 63 61 74 65 73 20 4e 20 6f 66  * allocates N of
2c4b0 20 6d 65 6d 6f 72 79 2c 20 7a 65 72 6f 65 73 20   memory, zeroes 
2c4c0 6f 75 74 20 74 68 61 74 20 6d 65 6d 6f 72 79 2c  out that memory,
2c4d0 20 61 6e 64 20 72 65 74 75 72 6e 73 20 61 20 70   and returns a p
2c4e0 6f 69 6e 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65  ointer.** to the
2c4f0 20 6e 65 77 20 6d 65 6d 6f 72 79 2e 20 5e 4f 6e   new memory. ^On
2c500 20 73 65 63 6f 6e 64 20 61 6e 64 20 73 75 62 73   second and subs
2c510 65 71 75 65 6e 74 20 63 61 6c 6c 73 20 74 6f 0a  equent calls to.
2c520 2a 2a 20 73 71 6c 69 74 65 33 5f 61 67 67 72 65  ** sqlite3_aggre
2c530 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 29 20 66  gate_context() f
2c540 6f 72 20 74 68 65 20 73 61 6d 65 20 61 67 67 72  or the same aggr
2c550 65 67 61 74 65 20 66 75 6e 63 74 69 6f 6e 20 69  egate function i
2c560 6e 73 74 61 6e 63 65 2c 0a 2a 2a 20 74 68 65 20  nstance,.** the 
2c570 73 61 6d 65 20 62 75 66 66 65 72 20 69 73 20 72  same buffer is r
2c580 65 74 75 72 6e 65 64 2e 20 20 53 71 6c 69 74 65  eturned.  Sqlite
2c590 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74  3_aggregate_cont
2c5a0 65 78 74 28 29 20 69 73 20 6e 6f 72 6d 61 6c 6c  ext() is normall
2c5b0 79 0a 2a 2a 20 63 61 6c 6c 65 64 20 6f 6e 63 65  y.** called once
2c5c0 20 66 6f 72 20 65 61 63 68 20 69 6e 76 6f 63 61   for each invoca
2c5d0 74 69 6f 6e 20 6f 66 20 74 68 65 20 78 53 74 65  tion of the xSte
2c5e0 70 20 63 61 6c 6c 62 61 63 6b 20 61 6e 64 20 74  p callback and t
2c5f0 68 65 6e 20 6f 6e 65 0a 2a 2a 20 6c 61 73 74 20  hen one.** last 
2c600 74 69 6d 65 20 77 68 65 6e 20 74 68 65 20 78 46  time when the xF
2c610 69 6e 61 6c 20 63 61 6c 6c 62 61 63 6b 20 69 73  inal callback is
2c620 20 69 6e 76 6f 6b 65 64 2e 20 20 5e 28 57 68 65   invoked.  ^(Whe
2c630 6e 20 6e 6f 20 72 6f 77 73 20 6d 61 74 63 68 0a  n no rows match.
2c640 2a 2a 20 61 6e 20 61 67 67 72 65 67 61 74 65 20  ** an aggregate 
2c650 71 75 65 72 79 2c 20 74 68 65 20 78 53 74 65 70  query, the xStep
2c660 28 29 20 63 61 6c 6c 62 61 63 6b 20 6f 66 20 74  () callback of t
2c670 68 65 20 61 67 67 72 65 67 61 74 65 20 66 75 6e  he aggregate fun
2c680 63 74 69 6f 6e 0a 2a 2a 20 69 6d 70 6c 65 6d 65  ction.** impleme
2c690 6e 74 61 74 69 6f 6e 20 69 73 20 6e 65 76 65 72  ntation is never
2c6a0 20 63 61 6c 6c 65 64 20 61 6e 64 20 78 46 69 6e   called and xFin
2c6b0 61 6c 28 29 20 69 73 20 63 61 6c 6c 65 64 20 65  al() is called e
2c6c0 78 61 63 74 6c 79 20 6f 6e 63 65 2e 0a 2a 2a 20  xactly once..** 
2c6d0 49 6e 20 74 68 6f 73 65 20 63 61 73 65 73 2c 20  In those cases, 
2c6e0 73 71 6c 69 74 65 33 5f 61 67 67 72 65 67 61 74  sqlite3_aggregat
2c6f0 65 5f 63 6f 6e 74 65 78 74 28 29 20 6d 69 67 68  e_context() migh
2c700 74 20 62 65 20 63 61 6c 6c 65 64 20 66 6f 72 20  t be called for 
2c710 74 68 65 0a 2a 2a 20 66 69 72 73 74 20 74 69 6d  the.** first tim
2c720 65 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 78 46  e from within xF
2c730 69 6e 61 6c 28 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20  inal().)^.**.** 
2c740 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 61 67 67  ^The sqlite3_agg
2c750 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74 28 43  regate_context(C
2c760 2c 4e 29 20 72 6f 75 74 69 6e 65 20 72 65 74 75  ,N) routine retu
2c770 72 6e 73 20 61 20 4e 55 4c 4c 20 70 6f 69 6e 74  rns a NULL point
2c780 65 72 20 69 66 20 4e 20 69 73 0a 2a 2a 20 6c 65  er if N is.** le
2c790 73 73 20 74 68 61 6e 20 6f 72 20 65 71 75 61 6c  ss than or equal
2c7a0 20 74 6f 20 7a 65 72 6f 20 6f 72 20 69 66 20 61   to zero or if a
2c7b0 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 65   memory allocate
2c7c0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 2e 0a 2a   error occurs..*
2c7d0 2a 0a 2a 2a 20 5e 28 54 68 65 20 61 6d 6f 75 6e  *.** ^(The amoun
2c7e0 74 20 6f 66 20 73 70 61 63 65 20 61 6c 6c 6f 63  t of space alloc
2c7f0 61 74 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f  ated by sqlite3_
2c800 61 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78  aggregate_contex
2c810 74 28 43 2c 4e 29 20 69 73 0a 2a 2a 20 64 65 74  t(C,N) is.** det
2c820 65 72 6d 69 6e 65 64 20 62 79 20 74 68 65 20 4e  ermined by the N
2c830 20 70 61 72 61 6d 65 74 65 72 20 6f 6e 20 66 69   parameter on fi
2c840 72 73 74 20 73 75 63 63 65 73 73 66 75 6c 20 63  rst successful c
2c850 61 6c 6c 2e 20 20 43 68 61 6e 67 69 6e 67 20 74  all.  Changing t
2c860 68 65 0a 2a 2a 20 76 61 6c 75 65 20 6f 66 20 4e  he.** value of N
2c870 20 69 6e 20 73 75 62 73 65 71 75 65 6e 74 20 63   in subsequent c
2c880 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f 61  all to sqlite3_a
2c890 67 67 72 65 67 61 74 65 5f 63 6f 6e 74 65 78 74  ggregate_context
2c8a0 28 29 20 77 69 74 68 69 6e 0a 2a 2a 20 74 68 65  () within.** the
2c8b0 20 73 61 6d 65 20 61 67 67 72 65 67 61 74 65 20   same aggregate 
2c8c0 66 75 6e 63 74 69 6f 6e 20 69 6e 73 74 61 6e 63  function instanc
2c8d0 65 20 77 69 6c 6c 20 6e 6f 74 20 72 65 73 69 7a  e will not resiz
2c8e0 65 20 74 68 65 20 6d 65 6d 6f 72 79 0a 2a 2a 20  e the memory.** 
2c8f0 61 6c 6c 6f 63 61 74 69 6f 6e 2e 29 5e 0a 2a 2a  allocation.)^.**
2c900 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 61 75 74 6f  .** ^SQLite auto
2c910 6d 61 74 69 63 61 6c 6c 79 20 66 72 65 65 73 20  matically frees 
2c920 74 68 65 20 6d 65 6d 6f 72 79 20 61 6c 6c 6f 63  the memory alloc
2c930 61 74 65 64 20 62 79 20 0a 2a 2a 20 73 71 6c 69  ated by .** sqli
2c940 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63 6f  te3_aggregate_co
2c950 6e 74 65 78 74 28 29 20 77 68 65 6e 20 74 68 65  ntext() when the
2c960 20 61 67 67 72 65 67 61 74 65 20 71 75 65 72 79   aggregate query
2c970 20 63 6f 6e 63 6c 75 64 65 73 2e 0a 2a 2a 0a 2a   concludes..**.*
2c980 2a 20 54 68 65 20 66 69 72 73 74 20 70 61 72 61  * The first para
2c990 6d 65 74 65 72 20 6d 75 73 74 20 62 65 20 61 20  meter must be a 
2c9a0 63 6f 70 79 20 6f 66 20 74 68 65 0a 2a 2a 20 5b  copy of the.** [
2c9b0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 20  sqlite3_context 
2c9c0 7c 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e 20 63  | SQL function c
2c9d0 6f 6e 74 65 78 74 5d 20 74 68 61 74 20 69 73 20  ontext] that is 
2c9e0 74 68 65 20 66 69 72 73 74 20 70 61 72 61 6d 65  the first parame
2c9f0 74 65 72 0a 2a 2a 20 74 6f 20 74 68 65 20 78 53  ter.** to the xS
2ca00 74 65 70 20 6f 72 20 78 46 69 6e 61 6c 20 63 61  tep or xFinal ca
2ca10 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e 65 20 74  llback routine t
2ca20 68 61 74 20 69 6d 70 6c 65 6d 65 6e 74 73 20 74  hat implements t
2ca30 68 65 20 61 67 67 72 65 67 61 74 65 0a 2a 2a 20  he aggregate.** 
2ca40 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  function..**.** 
2ca50 54 68 69 73 20 72 6f 75 74 69 6e 65 20 6d 75 73  This routine mus
2ca60 74 20 62 65 20 63 61 6c 6c 65 64 20 66 72 6f 6d  t be called from
2ca70 20 74 68 65 20 73 61 6d 65 20 74 68 72 65 61 64   the same thread
2ca80 20 69 6e 20 77 68 69 63 68 0a 2a 2a 20 74 68 65   in which.** the
2ca90 20 61 67 67 72 65 67 61 74 65 20 53 51 4c 20 66   aggregate SQL f
2caa0 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69  unction is runni
2cab0 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c  ng..*/.void *sql
2cac0 69 74 65 33 5f 61 67 67 72 65 67 61 74 65 5f 63  ite3_aggregate_c
2cad0 6f 6e 74 65 78 74 28 73 71 6c 69 74 65 33 5f 63  ontext(sqlite3_c
2cae0 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 20 6e 42 79  ontext*, int nBy
2caf0 74 65 73 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  tes);../*.** CAP
2cb00 49 33 52 45 46 3a 20 55 73 65 72 20 44 61 74 61  I3REF: User Data
2cb10 20 46 6f 72 20 46 75 6e 63 74 69 6f 6e 73 0a 2a   For Functions.*
2cb20 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65  *.** ^The sqlite
2cb30 33 5f 75 73 65 72 5f 64 61 74 61 28 29 20 69 6e  3_user_data() in
2cb40 74 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20  terface returns 
2cb50 61 20 63 6f 70 79 20 6f 66 0a 2a 2a 20 74 68 65  a copy of.** the
2cb60 20 70 6f 69 6e 74 65 72 20 74 68 61 74 20 77 61   pointer that wa
2cb70 73 20 74 68 65 20 70 55 73 65 72 44 61 74 61 20  s the pUserData 
2cb80 70 61 72 61 6d 65 74 65 72 20 28 74 68 65 20 35  parameter (the 5
2cb90 74 68 20 70 61 72 61 6d 65 74 65 72 29 0a 2a 2a  th parameter).**
2cba0 20 6f 66 20 74 68 65 20 5b 73 71 6c 69 74 65 33   of the [sqlite3
2cbb0 5f 63 72 65 61 74 65 5f 66 75 6e 63 74 69 6f 6e  _create_function
2cbc0 28 29 5d 0a 2a 2a 20 61 6e 64 20 5b 73 71 6c 69  ()].** and [sqli
2cbd0 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2cbe0 69 6f 6e 31 36 28 29 5d 20 72 6f 75 74 69 6e 65  ion16()] routine
2cbf0 73 20 74 68 61 74 20 6f 72 69 67 69 6e 61 6c 6c  s that originall
2cc00 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65 64 20  y.** registered 
2cc10 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 20  the application 
2cc20 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e  defined function
2cc30 2e 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20 72 6f 75  ..**.** This rou
2cc40 74 69 6e 65 20 6d 75 73 74 20 62 65 20 63 61 6c  tine must be cal
2cc50 6c 65 64 20 66 72 6f 6d 20 74 68 65 20 73 61 6d  led from the sam
2cc60 65 20 74 68 72 65 61 64 20 69 6e 20 77 68 69 63  e thread in whic
2cc70 68 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  h.** the applica
2cc80 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2cc90 63 74 69 6f 6e 20 69 73 20 72 75 6e 6e 69 6e 67  ction is running
2cca0 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74  ..*/.void *sqlit
2ccb0 65 33 5f 75 73 65 72 5f 64 61 74 61 28 73 71 6c  e3_user_data(sql
2ccc0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 29 3b 0a  ite3_context*);.
2ccd0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
2cce0 20 44 61 74 61 62 61 73 65 20 43 6f 6e 6e 65 63   Database Connec
2ccf0 74 69 6f 6e 20 46 6f 72 20 46 75 6e 63 74 69 6f  tion For Functio
2cd00 6e 73 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  ns.**.** ^The sq
2cd10 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 5f 64 62  lite3_context_db
2cd20 5f 68 61 6e 64 6c 65 28 29 20 69 6e 74 65 72 66  _handle() interf
2cd30 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 63 6f  ace returns a co
2cd40 70 79 20 6f 66 0a 2a 2a 20 74 68 65 20 70 6f 69  py of.** the poi
2cd50 6e 74 65 72 20 74 6f 20 74 68 65 20 5b 64 61 74  nter to the [dat
2cd60 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
2cd70 5d 20 28 74 68 65 20 31 73 74 20 70 61 72 61 6d  ] (the 1st param
2cd80 65 74 65 72 29 0a 2a 2a 20 6f 66 20 74 68 65 20  eter).** of the 
2cd90 5b 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f  [sqlite3_create_
2cda0 66 75 6e 63 74 69 6f 6e 28 29 5d 0a 2a 2a 20 61  function()].** a
2cdb0 6e 64 20 5b 73 71 6c 69 74 65 33 5f 63 72 65 61  nd [sqlite3_crea
2cdc0 74 65 5f 66 75 6e 63 74 69 6f 6e 31 36 28 29 5d  te_function16()]
2cdd0 20 72 6f 75 74 69 6e 65 73 20 74 68 61 74 20 6f   routines that o
2cde0 72 69 67 69 6e 61 6c 6c 79 0a 2a 2a 20 72 65 67  riginally.** reg
2cdf0 69 73 74 65 72 65 64 20 74 68 65 20 61 70 70 6c  istered the appl
2ce00 69 63 61 74 69 6f 6e 20 64 65 66 69 6e 65 64 20  ication defined 
2ce10 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 71 6c  function..*/.sql
2ce20 69 74 65 33 20 2a 73 71 6c 69 74 65 33 5f 63 6f  ite3 *sqlite3_co
2ce30 6e 74 65 78 74 5f 64 62 5f 68 61 6e 64 6c 65 28  ntext_db_handle(
2ce40 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2ce50 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
2ce60 45 46 3a 20 46 75 6e 63 74 69 6f 6e 20 41 75 78  EF: Function Aux
2ce70 69 6c 69 61 72 79 20 44 61 74 61 0a 2a 2a 0a 2a  iliary Data.**.*
2ce80 2a 20 54 68 65 20 66 6f 6c 6c 6f 77 69 6e 67 20  * The following 
2ce90 74 77 6f 20 66 75 6e 63 74 69 6f 6e 73 20 6d 61  two functions ma
2cea0 79 20 62 65 20 75 73 65 64 20 62 79 20 73 63 61  y be used by sca
2ceb0 6c 61 72 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  lar SQL function
2cec0 73 20 74 6f 0a 2a 2a 20 61 73 73 6f 63 69 61 74  s to.** associat
2ced0 65 20 6d 65 74 61 64 61 74 61 20 77 69 74 68 20  e metadata with 
2cee0 61 72 67 75 6d 65 6e 74 20 76 61 6c 75 65 73 2e  argument values.
2cef0 20 49 66 20 74 68 65 20 73 61 6d 65 20 76 61 6c   If the same val
2cf00 75 65 20 69 73 20 70 61 73 73 65 64 20 74 6f 0a  ue is passed to.
2cf10 2a 2a 20 6d 75 6c 74 69 70 6c 65 20 69 6e 76 6f  ** multiple invo
2cf20 63 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73  cations of the s
2cf30 61 6d 65 20 53 51 4c 20 66 75 6e 63 74 69 6f 6e  ame SQL function
2cf40 20 64 75 72 69 6e 67 20 71 75 65 72 79 20 65 78   during query ex
2cf50 65 63 75 74 69 6f 6e 2c 20 75 6e 64 65 72 0a 2a  ecution, under.*
2cf60 2a 20 73 6f 6d 65 20 63 69 72 63 75 6d 73 74 61  * some circumsta
2cf70 6e 63 65 73 20 74 68 65 20 61 73 73 6f 63 69 61  nces the associa
2cf80 74 65 64 20 6d 65 74 61 64 61 74 61 20 6d 61 79  ted metadata may
2cf90 20 62 65 20 70 72 65 73 65 72 76 65 64 2e 20 54   be preserved. T
2cfa0 68 69 73 20 6d 61 79 0a 2a 2a 20 62 65 20 75 73  his may.** be us
2cfb0 65 64 2c 20 66 6f 72 20 65 78 61 6d 70 6c 65 2c  ed, for example,
2cfc0 20 74 6f 20 61 64 64 20 61 20 72 65 67 75 6c 61   to add a regula
2cfd0 72 2d 65 78 70 72 65 73 73 69 6f 6e 20 6d 61 74  r-expression mat
2cfe0 63 68 69 6e 67 20 73 63 61 6c 61 72 0a 2a 2a 20  ching scalar.** 
2cff0 66 75 6e 63 74 69 6f 6e 2e 20 54 68 65 20 63 6f  function. The co
2d000 6d 70 69 6c 65 64 20 76 65 72 73 69 6f 6e 20 6f  mpiled version o
2d010 66 20 74 68 65 20 72 65 67 75 6c 61 72 20 65 78  f the regular ex
2d020 70 72 65 73 73 69 6f 6e 20 69 73 20 73 74 6f 72  pression is stor
2d030 65 64 20 61 73 0a 2a 2a 20 6d 65 74 61 64 61 74  ed as.** metadat
2d040 61 20 61 73 73 6f 63 69 61 74 65 64 20 77 69 74  a associated wit
2d050 68 20 74 68 65 20 53 51 4c 20 76 61 6c 75 65 20  h the SQL value 
2d060 70 61 73 73 65 64 20 61 73 20 74 68 65 20 72 65  passed as the re
2d070 67 75 6c 61 72 20 65 78 70 72 65 73 73 69 6f 6e  gular expression
2d080 0a 2a 2a 20 70 61 74 74 65 72 6e 2e 20 20 54 68  .** pattern.  Th
2d090 65 20 63 6f 6d 70 69 6c 65 64 20 72 65 67 75 6c  e compiled regul
2d0a0 61 72 20 65 78 70 72 65 73 73 69 6f 6e 20 63 61  ar expression ca
2d0b0 6e 20 62 65 20 72 65 75 73 65 64 20 6f 6e 20 6d  n be reused on m
2d0c0 75 6c 74 69 70 6c 65 0a 2a 2a 20 69 6e 76 6f 63  ultiple.** invoc
2d0d0 61 74 69 6f 6e 73 20 6f 66 20 74 68 65 20 73 61  ations of the sa
2d0e0 6d 65 20 66 75 6e 63 74 69 6f 6e 20 73 6f 20 74  me function so t
2d0f0 68 61 74 20 74 68 65 20 6f 72 69 67 69 6e 61 6c  hat the original
2d100 20 70 61 74 74 65 72 6e 20 73 74 72 69 6e 67 0a   pattern string.
2d110 2a 2a 20 64 6f 65 73 20 6e 6f 74 20 6e 65 65 64  ** does not need
2d120 20 74 6f 20 62 65 20 72 65 63 6f 6d 70 69 6c 65   to be recompile
2d130 64 20 6f 6e 20 65 61 63 68 20 69 6e 76 6f 63 61  d on each invoca
2d140 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65  tion..**.** ^The
2d150 20 73 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78   sqlite3_get_aux
2d160 64 61 74 61 28 29 20 69 6e 74 65 72 66 61 63 65  data() interface
2d170 20 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74   returns a point
2d180 65 72 20 74 6f 20 74 68 65 20 6d 65 74 61 64 61  er to the metada
2d190 74 61 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64  ta.** associated
2d1a0 20 62 79 20 74 68 65 20 73 71 6c 69 74 65 33 5f   by the sqlite3_
2d1b0 73 65 74 5f 61 75 78 64 61 74 61 28 29 20 66 75  set_auxdata() fu
2d1c0 6e 63 74 69 6f 6e 20 77 69 74 68 20 74 68 65 20  nction with the 
2d1d0 4e 74 68 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  Nth argument.** 
2d1e0 76 61 6c 75 65 20 74 6f 20 74 68 65 20 61 70 70  value to the app
2d1f0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2d200 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 49 66 20 6e   function. ^If n
2d210 6f 20 6d 65 74 61 64 61 74 61 20 68 61 73 20 62  o metadata has b
2d220 65 65 6e 20 65 76 65 72 0a 2a 2a 20 62 65 65 6e  een ever.** been
2d230 20 73 65 74 20 66 6f 72 20 74 68 65 20 4e 74 68   set for the Nth
2d240 20 61 72 67 75 6d 65 6e 74 20 6f 66 20 74 68 65   argument of the
2d250 20 66 75 6e 63 74 69 6f 6e 2c 20 6f 72 20 69 66   function, or if
2d260 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69   the correspondi
2d270 6e 67 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 70  ng.** function p
2d280 61 72 61 6d 65 74 65 72 20 68 61 73 20 63 68 61  arameter has cha
2d290 6e 67 65 64 20 73 69 6e 63 65 20 74 68 65 20 6d  nged since the m
2d2a0 65 74 61 2d 64 61 74 61 20 77 61 73 20 73 65 74  eta-data was set
2d2b0 2c 0a 2a 2a 20 74 68 65 6e 20 73 71 6c 69 74 65  ,.** then sqlite
2d2c0 33 5f 67 65 74 5f 61 75 78 64 61 74 61 28 29 20  3_get_auxdata() 
2d2d0 72 65 74 75 72 6e 73 20 61 20 4e 55 4c 4c 20 70  returns a NULL p
2d2e0 6f 69 6e 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  ointer..**.** ^T
2d2f0 68 65 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61  he sqlite3_set_a
2d300 75 78 64 61 74 61 28 29 20 69 6e 74 65 72 66 61  uxdata() interfa
2d310 63 65 20 73 61 76 65 73 20 74 68 65 20 6d 65 74  ce saves the met
2d320 61 64 61 74 61 0a 2a 2a 20 70 6f 69 6e 74 65 64  adata.** pointed
2d330 20 74 6f 20 62 79 20 69 74 73 20 33 72 64 20 70   to by its 3rd p
2d340 61 72 61 6d 65 74 65 72 20 61 73 20 74 68 65 20  arameter as the 
2d350 6d 65 74 61 64 61 74 61 20 66 6f 72 20 74 68 65  metadata for the
2d360 20 4e 2d 74 68 0a 2a 2a 20 61 72 67 75 6d 65 6e   N-th.** argumen
2d370 74 20 6f 66 20 74 68 65 20 61 70 70 6c 69 63 61  t of the applica
2d380 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2d390 63 74 69 6f 6e 2e 20 20 53 75 62 73 65 71 75 65  ction.  Subseque
2d3a0 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f 20 73  nt.** calls to s
2d3b0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2d3c0 74 61 28 29 20 6d 69 67 68 74 20 72 65 74 75 72  ta() might retur
2d3d0 6e 20 74 68 69 73 20 64 61 74 61 2c 20 69 66 20  n this data, if 
2d3e0 69 74 20 68 61 73 0a 2a 2a 20 6e 6f 74 20 62 65  it has.** not be
2d3f0 65 6e 20 64 65 73 74 72 6f 79 65 64 2e 0a 2a 2a  en destroyed..**
2d400 20 5e 49 66 20 69 74 20 69 73 20 6e 6f 74 20 4e   ^If it is not N
2d410 55 4c 4c 2c 20 53 51 4c 69 74 65 20 77 69 6c 6c  ULL, SQLite will
2d420 20 69 6e 76 6f 6b 65 20 74 68 65 20 64 65 73 74   invoke the dest
2d430 72 75 63 74 6f 72 0a 2a 2a 20 66 75 6e 63 74 69  ructor.** functi
2d440 6f 6e 20 67 69 76 65 6e 20 62 79 20 74 68 65 20  on given by the 
2d450 34 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f  4th parameter to
2d460 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75 78   sqlite3_set_aux
2d470 64 61 74 61 28 29 20 6f 6e 0a 2a 2a 20 74 68 65  data() on.** the
2d480 20 6d 65 74 61 64 61 74 61 20 77 68 65 6e 20 74   metadata when t
2d490 68 65 20 63 6f 72 72 65 73 70 6f 6e 64 69 6e 67  he corresponding
2d4a0 20 66 75 6e 63 74 69 6f 6e 20 70 61 72 61 6d 65   function parame
2d4b0 74 65 72 20 63 68 61 6e 67 65 73 0a 2a 2a 20 6f  ter changes.** o
2d4c0 72 20 77 68 65 6e 20 74 68 65 20 53 51 4c 20 73  r when the SQL s
2d4d0 74 61 74 65 6d 65 6e 74 20 63 6f 6d 70 6c 65 74  tatement complet
2d4e0 65 73 2c 20 77 68 69 63 68 65 76 65 72 20 63 6f  es, whichever co
2d4f0 6d 65 73 20 66 69 72 73 74 2e 0a 2a 2a 0a 2a 2a  mes first..**.**
2d500 20 53 51 4c 69 74 65 20 69 73 20 66 72 65 65 20   SQLite is free 
2d510 74 6f 20 63 61 6c 6c 20 74 68 65 20 64 65 73 74  to call the dest
2d520 72 75 63 74 6f 72 20 61 6e 64 20 64 72 6f 70 20  ructor and drop 
2d530 6d 65 74 61 64 61 74 61 20 6f 6e 20 61 6e 79 0a  metadata on any.
2d540 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 6f 66 20  ** parameter of 
2d550 61 6e 79 20 66 75 6e 63 74 69 6f 6e 20 61 74 20  any function at 
2d560 61 6e 79 20 74 69 6d 65 2e 20 20 5e 54 68 65 20  any time.  ^The 
2d570 6f 6e 6c 79 20 67 75 61 72 61 6e 74 65 65 20 69  only guarantee i
2d580 73 20 74 68 61 74 0a 2a 2a 20 74 68 65 20 64 65  s that.** the de
2d590 73 74 72 75 63 74 6f 72 20 77 69 6c 6c 20 62 65  structor will be
2d5a0 20 63 61 6c 6c 65 64 20 62 65 66 6f 72 65 20 74   called before t
2d5b0 68 65 20 6d 65 74 61 64 61 74 61 20 69 73 20 64  he metadata is d
2d5c0 72 6f 70 70 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28  ropped..**.** ^(
2d5d0 49 6e 20 70 72 61 63 74 69 63 65 2c 20 6d 65 74  In practice, met
2d5e0 61 64 61 74 61 20 69 73 20 70 72 65 73 65 72 76  adata is preserv
2d5f0 65 64 20 62 65 74 77 65 65 6e 20 66 75 6e 63 74  ed between funct
2d600 69 6f 6e 20 63 61 6c 6c 73 20 66 6f 72 0a 2a 2a  ion calls for.**
2d610 20 65 78 70 72 65 73 73 69 6f 6e 73 20 74 68 61   expressions tha
2d620 74 20 61 72 65 20 63 6f 6e 73 74 61 6e 74 20 61  t are constant a
2d630 74 20 63 6f 6d 70 69 6c 65 20 74 69 6d 65 2e 20  t compile time. 
2d640 54 68 69 73 20 69 6e 63 6c 75 64 65 73 20 6c 69  This includes li
2d650 74 65 72 61 6c 0a 2a 2a 20 76 61 6c 75 65 73 20  teral.** values 
2d660 61 6e 64 20 5b 70 61 72 61 6d 65 74 65 72 73 5d  and [parameters]
2d670 2e 29 5e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  .)^.**.** These 
2d680 72 6f 75 74 69 6e 65 73 20 6d 75 73 74 20 62 65  routines must be
2d690 20 63 61 6c 6c 65 64 20 66 72 6f 6d 20 74 68 65   called from the
2d6a0 20 73 61 6d 65 20 74 68 72 65 61 64 20 69 6e 20   same thread in 
2d6b0 77 68 69 63 68 0a 2a 2a 20 74 68 65 20 53 51 4c  which.** the SQL
2d6c0 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 72 75 6e   function is run
2d6d0 6e 69 6e 67 2e 0a 2a 2f 0a 76 6f 69 64 20 2a 73  ning..*/.void *s
2d6e0 71 6c 69 74 65 33 5f 67 65 74 5f 61 75 78 64 61  qlite3_get_auxda
2d6f0 74 61 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  ta(sqlite3_conte
2d700 78 74 2a 2c 20 69 6e 74 20 4e 29 3b 0a 76 6f 69  xt*, int N);.voi
2d710 64 20 73 71 6c 69 74 65 33 5f 73 65 74 5f 61 75  d sqlite3_set_au
2d720 78 64 61 74 61 28 73 71 6c 69 74 65 33 5f 63 6f  xdata(sqlite3_co
2d730 6e 74 65 78 74 2a 2c 20 69 6e 74 20 4e 2c 20 76  ntext*, int N, v
2d740 6f 69 64 2a 2c 20 76 6f 69 64 20 28 2a 29 28 76  oid*, void (*)(v
2d750 6f 69 64 2a 29 29 3b 0a 0a 0a 2f 2a 0a 2a 2a 20  oid*));.../*.** 
2d760 43 41 50 49 33 52 45 46 3a 20 43 6f 6e 73 74 61  CAPI3REF: Consta
2d770 6e 74 73 20 44 65 66 69 6e 69 6e 67 20 53 70 65  nts Defining Spe
2d780 63 69 61 6c 20 44 65 73 74 72 75 63 74 6f 72 20  cial Destructor 
2d790 42 65 68 61 76 69 6f 72 0a 2a 2a 0a 2a 2a 20 54  Behavior.**.** T
2d7a0 68 65 73 65 20 61 72 65 20 73 70 65 63 69 61 6c  hese are special
2d7b0 20 76 61 6c 75 65 73 20 66 6f 72 20 74 68 65 20   values for the 
2d7c0 64 65 73 74 72 75 63 74 6f 72 20 74 68 61 74 20  destructor that 
2d7d0 69 73 20 70 61 73 73 65 64 20 69 6e 20 61 73 20  is passed in as 
2d7e0 74 68 65 0a 2a 2a 20 66 69 6e 61 6c 20 61 72 67  the.** final arg
2d7f0 75 6d 65 6e 74 20 74 6f 20 72 6f 75 74 69 6e 65  ument to routine
2d800 73 20 6c 69 6b 65 20 5b 73 71 6c 69 74 65 33 5f  s like [sqlite3_
2d810 72 65 73 75 6c 74 5f 62 6c 6f 62 28 29 5d 2e 20  result_blob()]. 
2d820 20 5e 49 66 20 74 68 65 20 64 65 73 74 72 75 63   ^If the destruc
2d830 74 6f 72 0a 2a 2a 20 61 72 67 75 6d 65 6e 74 20  tor.** argument 
2d840 69 73 20 53 51 4c 49 54 45 5f 53 54 41 54 49 43  is SQLITE_STATIC
2d850 2c 20 69 74 20 6d 65 61 6e 73 20 74 68 61 74 20  , it means that 
2d860 74 68 65 20 63 6f 6e 74 65 6e 74 20 70 6f 69 6e  the content poin
2d870 74 65 72 20 69 73 20 63 6f 6e 73 74 61 6e 74 0a  ter is constant.
2d880 2a 2a 20 61 6e 64 20 77 69 6c 6c 20 6e 65 76 65  ** and will neve
2d890 72 20 63 68 61 6e 67 65 2e 20 20 49 74 20 64 6f  r change.  It do
2d8a0 65 73 20 6e 6f 74 20 6e 65 65 64 20 74 6f 20 62  es not need to b
2d8b0 65 20 64 65 73 74 72 6f 79 65 64 2e 20 20 5e 54  e destroyed.  ^T
2d8c0 68 65 0a 2a 2a 20 53 51 4c 49 54 45 5f 54 52 41  he.** SQLITE_TRA
2d8d0 4e 53 49 45 4e 54 20 76 61 6c 75 65 20 6d 65 61  NSIENT value mea
2d8e0 6e 73 20 74 68 61 74 20 74 68 65 20 63 6f 6e 74  ns that the cont
2d8f0 65 6e 74 20 77 69 6c 6c 20 6c 69 6b 65 6c 79 20  ent will likely 
2d900 63 68 61 6e 67 65 20 69 6e 0a 2a 2a 20 74 68 65  change in.** the
2d910 20 6e 65 61 72 20 66 75 74 75 72 65 20 61 6e 64   near future and
2d920 20 74 68 61 74 20 53 51 4c 69 74 65 20 73 68 6f   that SQLite sho
2d930 75 6c 64 20 6d 61 6b 65 20 69 74 73 20 6f 77 6e  uld make its own
2d940 20 70 72 69 76 61 74 65 20 63 6f 70 79 20 6f 66   private copy of
2d950 0a 2a 2a 20 74 68 65 20 63 6f 6e 74 65 6e 74 20  .** the content 
2d960 62 65 66 6f 72 65 20 72 65 74 75 72 6e 69 6e 67  before returning
2d970 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 74 79 70 65  ..**.** The type
2d980 64 65 66 20 69 73 20 6e 65 63 65 73 73 61 72 79  def is necessary
2d990 20 74 6f 20 77 6f 72 6b 20 61 72 6f 75 6e 64 20   to work around 
2d9a0 70 72 6f 62 6c 65 6d 73 20 69 6e 20 63 65 72 74  problems in cert
2d9b0 61 69 6e 0a 2a 2a 20 43 2b 2b 20 63 6f 6d 70 69  ain.** C++ compi
2d9c0 6c 65 72 73 2e 20 20 53 65 65 20 74 69 63 6b 65  lers.  See ticke
2d9d0 74 20 23 32 31 39 31 2e 0a 2a 2f 0a 74 79 70 65  t #2191..*/.type
2d9e0 64 65 66 20 76 6f 69 64 20 28 2a 73 71 6c 69 74  def void (*sqlit
2d9f0 65 33 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79  e3_destructor_ty
2da00 70 65 29 28 76 6f 69 64 2a 29 3b 0a 23 64 65 66  pe)(void*);.#def
2da10 69 6e 65 20 53 51 4c 49 54 45 5f 53 54 41 54 49  ine SQLITE_STATI
2da20 43 20 20 20 20 20 20 28 28 73 71 6c 69 74 65 33  C      ((sqlite3
2da30 5f 64 65 73 74 72 75 63 74 6f 72 5f 74 79 70 65  _destructor_type
2da40 29 30 29 0a 23 64 65 66 69 6e 65 20 53 51 4c 49  )0).#define SQLI
2da50 54 45 5f 54 52 41 4e 53 49 45 4e 54 20 20 20 28  TE_TRANSIENT   (
2da60 28 73 71 6c 69 74 65 33 5f 64 65 73 74 72 75 63  (sqlite3_destruc
2da70 74 6f 72 5f 74 79 70 65 29 2d 31 29 0a 0a 2f 2a  tor_type)-1)../*
2da80 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 53 65  .** CAPI3REF: Se
2da90 74 74 69 6e 67 20 54 68 65 20 52 65 73 75 6c 74  tting The Result
2daa0 20 4f 66 20 41 6e 20 53 51 4c 20 46 75 6e 63 74   Of An SQL Funct
2dab0 69 6f 6e 0a 2a 2a 0a 2a 2a 20 54 68 65 73 65 20  ion.**.** These 
2dac0 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
2dad0 64 20 62 79 20 74 68 65 20 78 46 75 6e 63 20 6f  d by the xFunc o
2dae0 72 20 78 46 69 6e 61 6c 20 63 61 6c 6c 62 61 63  r xFinal callbac
2daf0 6b 73 20 74 68 61 74 0a 2a 2a 20 69 6d 70 6c 65  ks that.** imple
2db00 6d 65 6e 74 20 53 51 4c 20 66 75 6e 63 74 69 6f  ment SQL functio
2db10 6e 73 20 61 6e 64 20 61 67 67 72 65 67 61 74 65  ns and aggregate
2db20 73 2e 20 20 53 65 65 0a 2a 2a 20 5b 73 71 6c 69  s.  See.** [sqli
2db30 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2db40 69 6f 6e 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69  ion()] and [sqli
2db50 74 65 33 5f 63 72 65 61 74 65 5f 66 75 6e 63 74  te3_create_funct
2db60 69 6f 6e 31 36 28 29 5d 0a 2a 2a 20 66 6f 72 20  ion16()].** for 
2db70 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66 6f 72  additional infor
2db80 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20 54 68  mation..**.** Th
2db90 65 73 65 20 66 75 6e 63 74 69 6f 6e 73 20 77 6f  ese functions wo
2dba0 72 6b 20 76 65 72 79 20 6d 75 63 68 20 6c 69 6b  rk very much lik
2dbb0 65 20 74 68 65 20 5b 70 61 72 61 6d 65 74 65 72  e the [parameter
2dbc0 20 62 69 6e 64 69 6e 67 5d 20 66 61 6d 69 6c 79   binding] family
2dbd0 20 6f 66 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 73   of.** functions
2dbe0 20 75 73 65 64 20 74 6f 20 62 69 6e 64 20 76 61   used to bind va
2dbf0 6c 75 65 73 20 74 6f 20 68 6f 73 74 20 70 61 72  lues to host par
2dc00 61 6d 65 74 65 72 73 20 69 6e 20 70 72 65 70 61  ameters in prepa
2dc10 72 65 64 20 73 74 61 74 65 6d 65 6e 74 73 2e 0a  red statements..
2dc20 2a 2a 20 52 65 66 65 72 20 74 6f 20 74 68 65 20  ** Refer to the 
2dc30 5b 53 51 4c 20 70 61 72 61 6d 65 74 65 72 5d 20  [SQL parameter] 
2dc40 64 6f 63 75 6d 65 6e 74 61 74 69 6f 6e 20 66 6f  documentation fo
2dc50 72 20 61 64 64 69 74 69 6f 6e 61 6c 20 69 6e 66  r additional inf
2dc60 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a 20  ormation..**.** 
2dc70 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2dc80 75 6c 74 5f 62 6c 6f 62 28 29 20 69 6e 74 65 72  ult_blob() inter
2dc90 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72 65  face sets the re
2dca0 73 75 6c 74 20 66 72 6f 6d 0a 2a 2a 20 61 6e 20  sult from.** an 
2dcb0 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2dcc0 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20  ned function to 
2dcd0 62 65 20 74 68 65 20 42 4c 4f 42 20 77 68 6f 73  be the BLOB whos
2dce0 65 20 63 6f 6e 74 65 6e 74 20 69 73 20 70 6f 69  e content is poi
2dcf0 6e 74 65 64 0a 2a 2a 20 74 6f 20 62 79 20 74 68  nted.** to by th
2dd00 65 20 73 65 63 6f 6e 64 20 70 61 72 61 6d 65 74  e second paramet
2dd10 65 72 20 61 6e 64 20 77 68 69 63 68 20 69 73 20  er and which is 
2dd20 4e 20 62 79 74 65 73 20 6c 6f 6e 67 20 77 68 65  N bytes long whe
2dd30 72 65 20 4e 20 69 73 20 74 68 65 0a 2a 2a 20 74  re N is the.** t
2dd40 68 69 72 64 20 70 61 72 61 6d 65 74 65 72 2e 0a  hird parameter..
2dd50 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2dd60 65 33 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c  e3_result_zerobl
2dd70 6f 62 28 29 20 69 6e 74 65 72 66 61 63 65 73 20  ob() interfaces 
2dd80 73 65 74 20 74 68 65 20 72 65 73 75 6c 74 20 6f  set the result o
2dd90 66 0a 2a 2a 20 74 68 65 20 61 70 70 6c 69 63 61  f.** the applica
2dda0 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e  tion-defined fun
2ddb0 63 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 42 4c  ction to be a BL
2ddc0 4f 42 20 63 6f 6e 74 61 69 6e 69 6e 67 20 61 6c  OB containing al
2ddd0 6c 20 7a 65 72 6f 0a 2a 2a 20 62 79 74 65 73 20  l zero.** bytes 
2dde0 61 6e 64 20 4e 20 62 79 74 65 73 20 69 6e 20 73  and N bytes in s
2ddf0 69 7a 65 2c 20 77 68 65 72 65 20 4e 20 69 73 20  ize, where N is 
2de00 74 68 65 20 76 61 6c 75 65 20 6f 66 20 74 68 65  the value of the
2de10 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e 0a   2nd parameter..
2de20 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
2de30 65 33 5f 72 65 73 75 6c 74 5f 64 6f 75 62 6c 65  e3_result_double
2de40 28 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74  () interface set
2de50 73 20 74 68 65 20 72 65 73 75 6c 74 20 66 72 6f  s the result fro
2de60 6d 0a 2a 2a 20 61 6e 20 61 70 70 6c 69 63 61 74  m.** an applicat
2de70 69 6f 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63  ion-defined func
2de80 74 69 6f 6e 20 74 6f 20 62 65 20 61 20 66 6c 6f  tion to be a flo
2de90 61 74 69 6e 67 20 70 6f 69 6e 74 20 76 61 6c 75  ating point valu
2dea0 65 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20 62  e specified.** b
2deb0 79 20 69 74 73 20 32 6e 64 20 61 72 67 75 6d 65  y its 2nd argume
2dec0 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73  nt..**.** ^The s
2ded0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2dee0 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2def0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2df00 28 29 20 66 75 6e 63 74 69 6f 6e 73 0a 2a 2a 20  () functions.** 
2df10 63 61 75 73 65 20 74 68 65 20 69 6d 70 6c 65 6d  cause the implem
2df20 65 6e 74 65 64 20 53 51 4c 20 66 75 6e 63 74 69  ented SQL functi
2df30 6f 6e 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65  on to throw an e
2df40 78 63 65 70 74 69 6f 6e 2e 0a 2a 2a 20 5e 53 51  xception..** ^SQ
2df50 4c 69 74 65 20 75 73 65 73 20 74 68 65 20 73 74  Lite uses the st
2df60 72 69 6e 67 20 70 6f 69 6e 74 65 64 20 74 6f 20  ring pointed to 
2df70 62 79 20 74 68 65 0a 2a 2a 20 32 6e 64 20 70 61  by the.** 2nd pa
2df80 72 61 6d 65 74 65 72 20 6f 66 20 73 71 6c 69 74  rameter of sqlit
2df90 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 28  e3_result_error(
2dfa0 29 20 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73  ) or sqlite3_res
2dfb0 75 6c 74 5f 65 72 72 6f 72 31 36 28 29 0a 2a 2a  ult_error16().**
2dfc0 20 61 73 20 74 68 65 20 74 65 78 74 20 6f 66 20   as the text of 
2dfd0 61 6e 20 65 72 72 6f 72 20 6d 65 73 73 61 67 65  an error message
2dfe0 2e 20 20 5e 53 51 4c 69 74 65 20 69 6e 74 65 72  .  ^SQLite inter
2dff0 70 72 65 74 73 20 74 68 65 20 65 72 72 6f 72 0a  prets the error.
2e000 2a 2a 20 6d 65 73 73 61 67 65 20 73 74 72 69 6e  ** message strin
2e010 67 20 66 72 6f 6d 20 73 71 6c 69 74 65 33 5f 72  g from sqlite3_r
2e020 65 73 75 6c 74 5f 65 72 72 6f 72 28 29 20 61 73  esult_error() as
2e030 20 55 54 46 2d 38 2e 20 5e 53 51 4c 69 74 65 0a   UTF-8. ^SQLite.
2e040 2a 2a 20 69 6e 74 65 72 70 72 65 74 73 20 74 68  ** interprets th
2e050 65 20 73 74 72 69 6e 67 20 66 72 6f 6d 20 73 71  e string from sq
2e060 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e070 6f 72 31 36 28 29 20 61 73 20 55 54 46 2d 31 36  or16() as UTF-16
2e080 20 69 6e 20 6e 61 74 69 76 65 0a 2a 2a 20 62 79   in native.** by
2e090 74 65 20 6f 72 64 65 72 2e 20 20 5e 49 66 20 74  te order.  ^If t
2e0a0 68 65 20 74 68 69 72 64 20 70 61 72 61 6d 65 74  he third paramet
2e0b0 65 72 20 74 6f 20 73 71 6c 69 74 65 33 5f 72 65  er to sqlite3_re
2e0c0 73 75 6c 74 5f 65 72 72 6f 72 28 29 0a 2a 2a 20  sult_error().** 
2e0d0 6f 72 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  or sqlite3_resul
2e0e0 74 5f 65 72 72 6f 72 31 36 28 29 20 69 73 20 6e  t_error16() is n
2e0f0 65 67 61 74 69 76 65 20 74 68 65 6e 20 53 51 4c  egative then SQL
2e100 69 74 65 20 74 61 6b 65 73 20 61 73 20 74 68 65  ite takes as the
2e110 20 65 72 72 6f 72 0a 2a 2a 20 6d 65 73 73 61 67   error.** messag
2e120 65 20 61 6c 6c 20 74 65 78 74 20 75 70 20 74 68  e all text up th
2e130 72 6f 75 67 68 20 74 68 65 20 66 69 72 73 74 20  rough the first 
2e140 7a 65 72 6f 20 63 68 61 72 61 63 74 65 72 2e 0a  zero character..
2e150 2a 2a 20 5e 49 66 20 74 68 65 20 74 68 69 72 64  ** ^If the third
2e160 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 73 71   parameter to sq
2e170 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e180 6f 72 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74  or() or.** sqlit
2e190 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31  e3_result_error1
2e1a0 36 28 29 20 69 73 20 6e 6f 6e 2d 6e 65 67 61 74  6() is non-negat
2e1b0 69 76 65 20 74 68 65 6e 20 53 51 4c 69 74 65 20  ive then SQLite 
2e1c0 74 61 6b 65 73 20 74 68 61 74 20 6d 61 6e 79 0a  takes that many.
2e1d0 2a 2a 20 62 79 74 65 73 20 28 6e 6f 74 20 63 68  ** bytes (not ch
2e1e0 61 72 61 63 74 65 72 73 29 20 66 72 6f 6d 20 74  aracters) from t
2e1f0 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72  he 2nd parameter
2e200 20 61 73 20 74 68 65 20 65 72 72 6f 72 20 6d 65   as the error me
2e210 73 73 61 67 65 2e 0a 2a 2a 20 5e 54 68 65 20 73  ssage..** ^The s
2e220 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2e230 72 6f 72 28 29 20 61 6e 64 20 73 71 6c 69 74 65  ror() and sqlite
2e240 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 31 36  3_result_error16
2e250 28 29 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20 6d  ().** routines m
2e260 61 6b 65 20 61 20 70 72 69 76 61 74 65 20 63 6f  ake a private co
2e270 70 79 20 6f 66 20 74 68 65 20 65 72 72 6f 72 20  py of the error 
2e280 6d 65 73 73 61 67 65 20 74 65 78 74 20 62 65 66  message text bef
2e290 6f 72 65 0a 2a 2a 20 74 68 65 79 20 72 65 74 75  ore.** they retu
2e2a0 72 6e 2e 20 20 48 65 6e 63 65 2c 20 74 68 65 20  rn.  Hence, the 
2e2b0 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74 69 6f 6e  calling function
2e2c0 20 63 61 6e 20 64 65 61 6c 6c 6f 63 61 74 65 20   can deallocate 
2e2d0 6f 72 0a 2a 2a 20 6d 6f 64 69 66 79 20 74 68 65  or.** modify the
2e2e0 20 74 65 78 74 20 61 66 74 65 72 20 74 68 65 79   text after they
2e2f0 20 72 65 74 75 72 6e 20 77 69 74 68 6f 75 74 20   return without 
2e300 68 61 72 6d 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  harm..** ^The sq
2e310 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72  lite3_result_err
2e320 6f 72 5f 63 6f 64 65 28 29 20 66 75 6e 63 74 69  or_code() functi
2e330 6f 6e 20 63 68 61 6e 67 65 73 20 74 68 65 20 65  on changes the e
2e340 72 72 6f 72 20 63 6f 64 65 0a 2a 2a 20 72 65 74  rror code.** ret
2e350 75 72 6e 65 64 20 62 79 20 53 51 4c 69 74 65 20  urned by SQLite 
2e360 61 73 20 61 20 72 65 73 75 6c 74 20 6f 66 20 61  as a result of a
2e370 6e 20 65 72 72 6f 72 20 69 6e 20 61 20 66 75 6e  n error in a fun
2e380 63 74 69 6f 6e 2e 20 20 5e 42 79 20 64 65 66 61  ction.  ^By defa
2e390 75 6c 74 2c 0a 2a 2a 20 74 68 65 20 65 72 72 6f  ult,.** the erro
2e3a0 72 20 63 6f 64 65 20 69 73 20 53 51 4c 49 54 45  r code is SQLITE
2e3b0 5f 45 52 52 4f 52 2e 20 20 5e 41 20 73 75 62 73  _ERROR.  ^A subs
2e3c0 65 71 75 65 6e 74 20 63 61 6c 6c 20 74 6f 20 73  equent call to s
2e3d0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72  qlite3_result_er
2e3e0 72 6f 72 28 29 0a 2a 2a 20 6f 72 20 73 71 6c 69  ror().** or sqli
2e3f0 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72  te3_result_error
2e400 31 36 28 29 20 72 65 73 65 74 73 20 74 68 65 20  16() resets the 
2e410 65 72 72 6f 72 20 63 6f 64 65 20 74 6f 20 53 51  error code to SQ
2e420 4c 49 54 45 5f 45 52 52 4f 52 2e 0a 2a 2a 0a 2a  LITE_ERROR..**.*
2e430 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72  * ^The sqlite3_r
2e440 65 73 75 6c 74 5f 74 6f 6f 62 69 67 28 29 20 69  esult_toobig() i
2e450 6e 74 65 72 66 61 63 65 20 63 61 75 73 65 73 20  nterface causes 
2e460 53 51 4c 69 74 65 20 74 6f 20 74 68 72 6f 77 20  SQLite to throw 
2e470 61 6e 20 65 72 72 6f 72 0a 2a 2a 20 69 6e 64 69  an error.** indi
2e480 63 61 74 69 6e 67 20 74 68 61 74 20 61 20 73 74  cating that a st
2e490 72 69 6e 67 20 6f 72 20 42 4c 4f 42 20 69 73 20  ring or BLOB is 
2e4a0 74 6f 6f 20 6c 6f 6e 67 20 74 6f 20 72 65 70 72  too long to repr
2e4b0 65 73 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  esent..**.** ^Th
2e4c0 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e4d0 5f 6e 6f 6d 65 6d 28 29 20 69 6e 74 65 72 66 61  _nomem() interfa
2e4e0 63 65 20 63 61 75 73 65 73 20 53 51 4c 69 74 65  ce causes SQLite
2e4f0 20 74 6f 20 74 68 72 6f 77 20 61 6e 20 65 72 72   to throw an err
2e500 6f 72 0a 2a 2a 20 69 6e 64 69 63 61 74 69 6e 67  or.** indicating
2e510 20 74 68 61 74 20 61 20 6d 65 6d 6f 72 79 20 61   that a memory a
2e520 6c 6c 6f 63 61 74 69 6f 6e 20 66 61 69 6c 65 64  llocation failed
2e530 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2e540 69 74 65 33 5f 72 65 73 75 6c 74 5f 69 6e 74 28  ite3_result_int(
2e550 29 20 69 6e 74 65 72 66 61 63 65 20 73 65 74 73  ) interface sets
2e560 20 74 68 65 20 72 65 74 75 72 6e 20 76 61 6c 75   the return valu
2e570 65 0a 2a 2a 20 6f 66 20 74 68 65 20 61 70 70 6c  e.** of the appl
2e580 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e590 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 74  function to be t
2e5a0 68 65 20 33 32 2d 62 69 74 20 73 69 67 6e 65 64  he 32-bit signed
2e5b0 20 69 6e 74 65 67 65 72 0a 2a 2a 20 76 61 6c 75   integer.** valu
2e5c0 65 20 67 69 76 65 6e 20 69 6e 20 74 68 65 20 32  e given in the 2
2e5d0 6e 64 20 61 72 67 75 6d 65 6e 74 2e 0a 2a 2a 20  nd argument..** 
2e5e0 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73  ^The sqlite3_res
2e5f0 75 6c 74 5f 69 6e 74 36 34 28 29 20 69 6e 74 65  ult_int64() inte
2e600 72 66 61 63 65 20 73 65 74 73 20 74 68 65 20 72  rface sets the r
2e610 65 74 75 72 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f  eturn value.** o
2e620 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
2e630 6e 2d 64 65 66 69 6e 65 64 20 66 75 6e 63 74 69  n-defined functi
2e640 6f 6e 20 74 6f 20 62 65 20 74 68 65 20 36 34 2d  on to be the 64-
2e650 62 69 74 20 73 69 67 6e 65 64 20 69 6e 74 65 67  bit signed integ
2e660 65 72 0a 2a 2a 20 76 61 6c 75 65 20 67 69 76 65  er.** value give
2e670 6e 20 69 6e 20 74 68 65 20 32 6e 64 20 61 72 67  n in the 2nd arg
2e680 75 6d 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  ument..**.** ^Th
2e690 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2e6a0 5f 6e 75 6c 6c 28 29 20 69 6e 74 65 72 66 61 63  _null() interfac
2e6b0 65 20 73 65 74 73 20 74 68 65 20 72 65 74 75 72  e sets the retur
2e6c0 6e 20 76 61 6c 75 65 0a 2a 2a 20 6f 66 20 74 68  n value.** of th
2e6d0 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2e6e0 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2e6f0 6f 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  o be NULL..**.**
2e700 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65   ^The sqlite3_re
2e710 73 75 6c 74 5f 74 65 78 74 28 29 2c 20 73 71 6c  sult_text(), sql
2e720 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2e730 31 36 28 29 2c 0a 2a 2a 20 73 71 6c 69 74 65 33  16(),.** sqlite3
2e740 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c 65  _result_text16le
2e750 28 29 2c 20 61 6e 64 20 73 71 6c 69 74 65 33 5f  (), and sqlite3_
2e760 72 65 73 75 6c 74 5f 74 65 78 74 31 36 62 65 28  result_text16be(
2e770 29 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a 20  ) interfaces.** 
2e780 73 65 74 20 74 68 65 20 72 65 74 75 72 6e 20 76  set the return v
2e790 61 6c 75 65 20 6f 66 20 74 68 65 20 61 70 70 6c  alue of the appl
2e7a0 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64 20  ication-defined 
2e7b0 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 0a 2a  function to be.*
2e7c0 2a 20 61 20 74 65 78 74 20 73 74 72 69 6e 67 20  * a text string 
2e7d0 77 68 69 63 68 20 69 73 20 72 65 70 72 65 73 65  which is represe
2e7e0 6e 74 65 64 20 61 73 20 55 54 46 2d 38 2c 20 55  nted as UTF-8, U
2e7f0 54 46 2d 31 36 20 6e 61 74 69 76 65 20 62 79 74  TF-16 native byt
2e800 65 20 6f 72 64 65 72 2c 0a 2a 2a 20 55 54 46 2d  e order,.** UTF-
2e810 31 36 20 6c 69 74 74 6c 65 20 65 6e 64 69 61 6e  16 little endian
2e820 2c 20 6f 72 20 55 54 46 2d 31 36 20 62 69 67 20  , or UTF-16 big 
2e830 65 6e 64 69 61 6e 2c 20 72 65 73 70 65 63 74 69  endian, respecti
2e840 76 65 6c 79 2e 0a 2a 2a 20 5e 53 51 4c 69 74 65  vely..** ^SQLite
2e850 20 74 61 6b 65 73 20 74 68 65 20 74 65 78 74 20   takes the text 
2e860 72 65 73 75 6c 74 20 66 72 6f 6d 20 74 68 65 20  result from the 
2e870 61 70 70 6c 69 63 61 74 69 6f 6e 20 66 72 6f 6d  application from
2e880 0a 2a 2a 20 74 68 65 20 32 6e 64 20 70 61 72 61  .** the 2nd para
2e890 6d 65 74 65 72 20 6f 66 20 74 68 65 20 73 71 6c  meter of the sql
2e8a0 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74  ite3_result_text
2e8b0 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2a  * interfaces..**
2e8c0 20 5e 49 66 20 74 68 65 20 33 72 64 20 70 61 72   ^If the 3rd par
2e8d0 61 6d 65 74 65 72 20 74 6f 20 74 68 65 20 73 71  ameter to the sq
2e8e0 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78  lite3_result_tex
2e8f0 74 2a 20 69 6e 74 65 72 66 61 63 65 73 0a 2a 2a  t* interfaces.**
2e900 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 74 68   is negative, th
2e910 65 6e 20 53 51 4c 69 74 65 20 74 61 6b 65 73 20  en SQLite takes 
2e920 72 65 73 75 6c 74 20 74 65 78 74 20 66 72 6f 6d  result text from
2e930 20 74 68 65 20 32 6e 64 20 70 61 72 61 6d 65 74   the 2nd paramet
2e940 65 72 0a 2a 2a 20 74 68 72 6f 75 67 68 20 74 68  er.** through th
2e950 65 20 66 69 72 73 74 20 7a 65 72 6f 20 63 68 61  e first zero cha
2e960 72 61 63 74 65 72 2e 0a 2a 2a 20 5e 49 66 20 74  racter..** ^If t
2e970 68 65 20 33 72 64 20 70 61 72 61 6d 65 74 65 72  he 3rd parameter
2e980 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2e990 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2e9a0 65 72 66 61 63 65 73 0a 2a 2a 20 69 73 20 6e 6f  erfaces.** is no
2e9b0 6e 2d 6e 65 67 61 74 69 76 65 2c 20 74 68 65 6e  n-negative, then
2e9c0 20 61 73 20 6d 61 6e 79 20 62 79 74 65 73 20 28   as many bytes (
2e9d0 6e 6f 74 20 63 68 61 72 61 63 74 65 72 73 29 20  not characters) 
2e9e0 6f 66 20 74 68 65 20 74 65 78 74 0a 2a 2a 20 70  of the text.** p
2e9f0 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68 65  ointed to by the
2ea00 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 20 61   2nd parameter a
2ea10 72 65 20 74 61 6b 65 6e 20 61 73 20 74 68 65 20  re taken as the 
2ea20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69  application-defi
2ea30 6e 65 64 0a 2a 2a 20 66 75 6e 63 74 69 6f 6e 20  ned.** function 
2ea40 72 65 73 75 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74  result..** ^If t
2ea50 68 65 20 34 74 68 20 70 61 72 61 6d 65 74 65 72  he 4th parameter
2ea60 20 74 6f 20 74 68 65 20 73 71 6c 69 74 65 33 5f   to the sqlite3_
2ea70 72 65 73 75 6c 74 5f 74 65 78 74 2a 20 69 6e 74  result_text* int
2ea80 65 72 66 61 63 65 73 0a 2a 2a 20 6f 72 20 73 71  erfaces.** or sq
2ea90 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f  lite3_result_blo
2eaa0 62 20 69 73 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  b is a non-NULL 
2eab0 70 6f 69 6e 74 65 72 2c 20 74 68 65 6e 20 53 51  pointer, then SQ
2eac0 4c 69 74 65 20 63 61 6c 6c 73 20 74 68 61 74 0a  Lite calls that.
2ead0 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 61 73 20 74  ** function as t
2eae0 68 65 20 64 65 73 74 72 75 63 74 6f 72 20 6f 6e  he destructor on
2eaf0 20 74 68 65 20 74 65 78 74 20 6f 72 20 42 4c 4f   the text or BLO
2eb00 42 20 72 65 73 75 6c 74 20 77 68 65 6e 20 69 74  B result when it
2eb10 20 68 61 73 0a 2a 2a 20 66 69 6e 69 73 68 65 64   has.** finished
2eb20 20 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75   using that resu
2eb30 6c 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34  lt..** ^If the 4
2eb40 74 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20  th parameter to 
2eb50 74 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75  the sqlite3_resu
2eb60 6c 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61  lt_text* interfa
2eb70 63 65 73 20 6f 72 20 74 6f 0a 2a 2a 20 73 71 6c  ces or to.** sql
2eb80 69 74 65 33 5f 72 65 73 75 6c 74 5f 62 6c 6f 62  ite3_result_blob
2eb90 20 69 73 20 74 68 65 20 73 70 65 63 69 61 6c 20   is the special 
2eba0 63 6f 6e 73 74 61 6e 74 20 53 51 4c 49 54 45 5f  constant SQLITE_
2ebb0 53 54 41 54 49 43 2c 20 74 68 65 6e 20 53 51 4c  STATIC, then SQL
2ebc0 69 74 65 0a 2a 2a 20 61 73 73 75 6d 65 73 20 74  ite.** assumes t
2ebd0 68 61 74 20 74 68 65 20 74 65 78 74 20 6f 72 20  hat the text or 
2ebe0 42 4c 4f 42 20 72 65 73 75 6c 74 20 69 73 20 69  BLOB result is i
2ebf0 6e 20 63 6f 6e 73 74 61 6e 74 20 73 70 61 63 65  n constant space
2ec00 20 61 6e 64 20 64 6f 65 73 20 6e 6f 74 0a 2a 2a   and does not.**
2ec10 20 63 6f 70 79 20 74 68 65 20 63 6f 6e 74 65 6e   copy the conten
2ec20 74 20 6f 66 20 74 68 65 20 70 61 72 61 6d 65 74  t of the paramet
2ec30 65 72 20 6e 6f 72 20 63 61 6c 6c 20 61 20 64 65  er nor call a de
2ec40 73 74 72 75 63 74 6f 72 20 6f 6e 20 74 68 65 20  structor on the 
2ec50 63 6f 6e 74 65 6e 74 0a 2a 2a 20 77 68 65 6e 20  content.** when 
2ec60 69 74 20 68 61 73 20 66 69 6e 69 73 68 65 64 20  it has finished 
2ec70 75 73 69 6e 67 20 74 68 61 74 20 72 65 73 75 6c  using that resul
2ec80 74 2e 0a 2a 2a 20 5e 49 66 20 74 68 65 20 34 74  t..** ^If the 4t
2ec90 68 20 70 61 72 61 6d 65 74 65 72 20 74 6f 20 74  h parameter to t
2eca0 68 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c  he sqlite3_resul
2ecb0 74 5f 74 65 78 74 2a 20 69 6e 74 65 72 66 61 63  t_text* interfac
2ecc0 65 73 0a 2a 2a 20 6f 72 20 73 71 6c 69 74 65 33  es.** or sqlite3
2ecd0 5f 72 65 73 75 6c 74 5f 62 6c 6f 62 20 69 73 20  _result_blob is 
2ece0 74 68 65 20 73 70 65 63 69 61 6c 20 63 6f 6e 73  the special cons
2ecf0 74 61 6e 74 20 53 51 4c 49 54 45 5f 54 52 41 4e  tant SQLITE_TRAN
2ed00 53 49 45 4e 54 0a 2a 2a 20 74 68 65 6e 20 53 51  SIENT.** then SQ
2ed10 4c 69 74 65 20 6d 61 6b 65 73 20 61 20 63 6f 70  Lite makes a cop
2ed20 79 20 6f 66 20 74 68 65 20 72 65 73 75 6c 74 20  y of the result 
2ed30 69 6e 74 6f 20 73 70 61 63 65 20 6f 62 74 61 69  into space obtai
2ed40 6e 65 64 20 66 72 6f 6d 0a 2a 2a 20 66 72 6f 6d  ned from.** from
2ed50 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63   [sqlite3_malloc
2ed60 28 29 5d 20 62 65 66 6f 72 65 20 69 74 20 72 65  ()] before it re
2ed70 74 75 72 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  turns..**.** ^Th
2ed80 65 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  e sqlite3_result
2ed90 5f 76 61 6c 75 65 28 29 20 69 6e 74 65 72 66 61  _value() interfa
2eda0 63 65 20 73 65 74 73 20 74 68 65 20 72 65 73 75  ce sets the resu
2edb0 6c 74 20 6f 66 0a 2a 2a 20 74 68 65 20 61 70 70  lt of.** the app
2edc0 6c 69 63 61 74 69 6f 6e 2d 64 65 66 69 6e 65 64  lication-defined
2edd0 20 66 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20   function to be 
2ede0 61 20 63 6f 70 79 20 74 68 65 0a 2a 2a 20 5b 75  a copy the.** [u
2edf0 6e 70 72 6f 74 65 63 74 65 64 20 73 71 6c 69 74  nprotected sqlit
2ee00 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74  e3_value] object
2ee10 20 73 70 65 63 69 66 69 65 64 20 62 79 20 74 68   specified by th
2ee20 65 20 32 6e 64 20 70 61 72 61 6d 65 74 65 72 2e  e 2nd parameter.
2ee30 20 20 5e 54 68 65 0a 2a 2a 20 73 71 6c 69 74 65    ^The.** sqlite
2ee40 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65 28 29  3_result_value()
2ee50 20 69 6e 74 65 72 66 61 63 65 20 6d 61 6b 65 73   interface makes
2ee60 20 61 20 63 6f 70 79 20 6f 66 20 74 68 65 20 5b   a copy of the [
2ee70 73 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 0a 2a  sqlite3_value].*
2ee80 2a 20 73 6f 20 74 68 61 74 20 74 68 65 20 5b 73  * so that the [s
2ee90 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 73 70  qlite3_value] sp
2eea0 65 63 69 66 69 65 64 20 69 6e 20 74 68 65 20 70  ecified in the p
2eeb0 61 72 61 6d 65 74 65 72 20 6d 61 79 20 63 68 61  arameter may cha
2eec0 6e 67 65 20 6f 72 0a 2a 2a 20 62 65 20 64 65 61  nge or.** be dea
2eed0 6c 6c 6f 63 61 74 65 64 20 61 66 74 65 72 20 73  llocated after s
2eee0 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 76 61  qlite3_result_va
2eef0 6c 75 65 28 29 20 72 65 74 75 72 6e 73 20 77 69  lue() returns wi
2ef00 74 68 6f 75 74 20 68 61 72 6d 2e 0a 2a 2a 20 5e  thout harm..** ^
2ef10 41 20 5b 70 72 6f 74 65 63 74 65 64 20 73 71 6c  A [protected sql
2ef20 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62 6a 65  ite3_value] obje
2ef30 63 74 20 6d 61 79 20 61 6c 77 61 79 73 20 62 65  ct may always be
2ef40 20 75 73 65 64 20 77 68 65 72 65 20 61 6e 0a 2a   used where an.*
2ef50 2a 20 5b 75 6e 70 72 6f 74 65 63 74 65 64 20 73  * [unprotected s
2ef60 71 6c 69 74 65 33 5f 76 61 6c 75 65 5d 20 6f 62  qlite3_value] ob
2ef70 6a 65 63 74 20 69 73 20 72 65 71 75 69 72 65 64  ject is required
2ef80 2c 20 73 6f 20 65 69 74 68 65 72 0a 2a 2a 20 6b  , so either.** k
2ef90 69 6e 64 20 6f 66 20 5b 73 71 6c 69 74 65 33 5f  ind of [sqlite3_
2efa0 76 61 6c 75 65 5d 20 6f 62 6a 65 63 74 20 63 61  value] object ca
2efb0 6e 20 62 65 20 75 73 65 64 20 77 69 74 68 20 74  n be used with t
2efc0 68 69 73 20 69 6e 74 65 72 66 61 63 65 2e 0a 2a  his interface..*
2efd0 2a 0a 2a 2a 20 49 66 20 74 68 65 73 65 20 72 6f  *.** If these ro
2efe0 75 74 69 6e 65 73 20 61 72 65 20 63 61 6c 6c 65  utines are calle
2eff0 64 20 66 72 6f 6d 20 77 69 74 68 69 6e 20 74 68  d from within th
2f000 65 20 64 69 66 66 65 72 65 6e 74 20 74 68 72 65  e different thre
2f010 61 64 0a 2a 2a 20 74 68 61 6e 20 74 68 65 20 6f  ad.** than the o
2f020 6e 65 20 63 6f 6e 74 61 69 6e 69 6e 67 20 74 68  ne containing th
2f030 65 20 61 70 70 6c 69 63 61 74 69 6f 6e 2d 64 65  e application-de
2f040 66 69 6e 65 64 20 66 75 6e 63 74 69 6f 6e 20 74  fined function t
2f050 68 61 74 20 72 65 63 65 69 76 65 64 0a 2a 2a 20  hat received.** 
2f060 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e  the [sqlite3_con
2f070 74 65 78 74 5d 20 70 6f 69 6e 74 65 72 2c 20 74  text] pointer, t
2f080 68 65 20 72 65 73 75 6c 74 73 20 61 72 65 20 75  he results are u
2f090 6e 64 65 66 69 6e 65 64 2e 0a 2a 2f 0a 76 6f 69  ndefined..*/.voi
2f0a0 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74  d sqlite3_result
2f0b0 5f 62 6c 6f 62 28 73 71 6c 69 74 65 33 5f 63 6f  _blob(sqlite3_co
2f0c0 6e 74 65 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f  ntext*, const vo
2f0d0 69 64 2a 2c 20 69 6e 74 2c 20 76 6f 69 64 28 2a  id*, int, void(*
2f0e0 29 28 76 6f 69 64 2a 29 29 3b 0a 76 6f 69 64 20  )(void*));.void 
2f0f0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 64  sqlite3_result_d
2f100 6f 75 62 6c 65 28 73 71 6c 69 74 65 33 5f 63 6f  ouble(sqlite3_co
2f110 6e 74 65 78 74 2a 2c 20 64 6f 75 62 6c 65 29 3b  ntext*, double);
2f120 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2f130 73 75 6c 74 5f 65 72 72 6f 72 28 73 71 6c 69 74  sult_error(sqlit
2f140 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f 6e  e3_context*, con
2f150 73 74 20 63 68 61 72 2a 2c 20 69 6e 74 29 3b 0a  st char*, int);.
2f160 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73  void sqlite3_res
2f170 75 6c 74 5f 65 72 72 6f 72 31 36 28 73 71 6c 69  ult_error16(sqli
2f180 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 63 6f  te3_context*, co
2f190 6e 73 74 20 76 6f 69 64 2a 2c 20 69 6e 74 29 3b  nst void*, int);
2f1a0 0a 76 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65  .void sqlite3_re
2f1b0 73 75 6c 74 5f 65 72 72 6f 72 5f 74 6f 6f 62 69  sult_error_toobi
2f1c0 67 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  g(sqlite3_contex
2f1d0 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  t*);.void sqlite
2f1e0 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f 72 5f 6e  3_result_error_n
2f1f0 6f 6d 65 6d 28 73 71 6c 69 74 65 33 5f 63 6f 6e  omem(sqlite3_con
2f200 74 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c  text*);.void sql
2f210 69 74 65 33 5f 72 65 73 75 6c 74 5f 65 72 72 6f  ite3_result_erro
2f220 72 5f 63 6f 64 65 28 73 71 6c 69 74 65 33 5f 63  r_code(sqlite3_c
2f230 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
2f240 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2f250 6c 74 5f 69 6e 74 28 73 71 6c 69 74 65 33 5f 63  lt_int(sqlite3_c
2f260 6f 6e 74 65 78 74 2a 2c 20 69 6e 74 29 3b 0a 76  ontext*, int);.v
2f270 6f 69 64 20 73 71 6c 69 74 65 33 5f 72 65 73 75  oid sqlite3_resu
2f280 6c 74 5f 69 6e 74 36 34 28 73 71 6c 69 74 65 33  lt_int64(sqlite3
2f290 5f 63 6f 6e 74 65 78 74 2a 2c 20 73 71 6c 69 74  _context*, sqlit
2f2a0 65 33 5f 69 6e 74 36 34 29 3b 0a 76 6f 69 64 20  e3_int64);.void 
2f2b0 73 71 6c 69 74 65 33 5f 72 65 73 75 6c 74 5f 6e  sqlite3_result_n
2f2c0 75 6c 6c 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74  ull(sqlite3_cont
2f2d0 65 78 74 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69  ext*);.void sqli
2f2e0 74 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 28  te3_result_text(
2f2f0 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f300 2c 20 63 6f 6e 73 74 20 63 68 61 72 2a 2c 20 69  , const char*, i
2f310 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2f320 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2f330 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 28  3_result_text16(
2f340 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a  sqlite3_context*
2f350 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c 20 69  , const void*, i
2f360 6e 74 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  nt, void(*)(void
2f370 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65  *));.void sqlite
2f380 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36 6c  3_result_text16l
2f390 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78  e(sqlite3_contex
2f3a0 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  t*, const void*,
2f3b0 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f 69   int,void(*)(voi
2f3c0 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74  d*));.void sqlit
2f3d0 65 33 5f 72 65 73 75 6c 74 5f 74 65 78 74 31 36  e3_result_text16
2f3e0 62 65 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65  be(sqlite3_conte
2f3f0 78 74 2a 2c 20 63 6f 6e 73 74 20 76 6f 69 64 2a  xt*, const void*
2f400 2c 20 69 6e 74 2c 76 6f 69 64 28 2a 29 28 76 6f  , int,void(*)(vo
2f410 69 64 2a 29 29 3b 0a 76 6f 69 64 20 73 71 6c 69  id*));.void sqli
2f420 74 65 33 5f 72 65 73 75 6c 74 5f 76 61 6c 75 65  te3_result_value
2f430 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f440 2a 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75 65  *, sqlite3_value
2f450 2a 29 3b 0a 76 6f 69 64 20 73 71 6c 69 74 65 33  *);.void sqlite3
2f460 5f 72 65 73 75 6c 74 5f 7a 65 72 6f 62 6c 6f 62  _result_zeroblob
2f470 28 73 71 6c 69 74 65 33 5f 63 6f 6e 74 65 78 74  (sqlite3_context
2f480 2a 2c 20 69 6e 74 20 6e 29 3b 0a 0a 2f 2a 0a 2a  *, int n);../*.*
2f490 2a 20 43 41 50 49 33 52 45 46 3a 20 44 65 66 69  * CAPI3REF: Defi
2f4a0 6e 65 20 4e 65 77 20 43 6f 6c 6c 61 74 69 6e 67  ne New Collating
2f4b0 20 53 65 71 75 65 6e 63 65 73 0a 2a 2a 0a 2a 2a   Sequences.**.**
2f4c0 20 5e 54 68 65 73 65 20 66 75 6e 63 74 69 6f 6e   ^These function
2f4d0 73 20 61 64 64 2c 20 72 65 6d 6f 76 65 2c 20 6f  s add, remove, o
2f4e0 72 20 6d 6f 64 69 66 79 20 61 20 5b 63 6f 6c 6c  r modify a [coll
2f4f0 61 74 69 6f 6e 5d 20 61 73 73 6f 63 69 61 74 65  ation] associate
2f500 64 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 5b 64  d.** with the [d
2f510 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69  atabase connecti
2f520 6f 6e 5d 20 73 70 65 63 69 66 69 65 64 20 61 73  on] specified as
2f530 20 74 68 65 20 66 69 72 73 74 20 61 72 67 75 6d   the first argum
2f540 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20  ent..**.** ^The 
2f550 6e 61 6d 65 20 6f 66 20 74 68 65 20 63 6f 6c 6c  name of the coll
2f560 61 74 69 6f 6e 20 69 73 20 61 20 55 54 46 2d 38  ation is a UTF-8
2f570 20 73 74 72 69 6e 67 0a 2a 2a 20 66 6f 72 20 73   string.** for s
2f580 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
2f590 6c 6c 61 74 69 6f 6e 28 29 20 61 6e 64 20 73 71  llation() and sq
2f5a0 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c  lite3_create_col
2f5b0 6c 61 74 69 6f 6e 5f 76 32 28 29 0a 2a 2a 20 61  lation_v2().** a
2f5c0 6e 64 20 61 20 55 54 46 2d 31 36 20 73 74 72 69  nd a UTF-16 stri
2f5d0 6e 67 20 69 6e 20 6e 61 74 69 76 65 20 62 79 74  ng in native byt
2f5e0 65 20 6f 72 64 65 72 20 66 6f 72 20 73 71 6c 69  e order for sqli
2f5f0 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
2f600 74 69 6f 6e 31 36 28 29 2e 0a 2a 2a 20 5e 43 6f  tion16()..** ^Co
2f610 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 73 20 74 68  llation names th
2f620 61 74 20 63 6f 6d 70 61 72 65 20 65 71 75 61 6c  at compare equal
2f630 20 61 63 63 6f 72 64 69 6e 67 20 74 6f 20 5b 73   according to [s
2f640 71 6c 69 74 65 33 5f 73 74 72 6e 69 63 6d 70 28  qlite3_strnicmp(
2f650 29 5d 20 61 72 65 0a 2a 2a 20 63 6f 6e 73 69 64  )] are.** consid
2f660 65 72 65 64 20 74 6f 20 62 65 20 74 68 65 20 73  ered to be the s
2f670 61 6d 65 20 6e 61 6d 65 2e 0a 2a 2a 0a 2a 2a 20  ame name..**.** 
2f680 5e 28 54 68 65 20 74 68 69 72 64 20 61 72 67 75  ^(The third argu
2f690 6d 65 6e 74 20 28 65 54 65 78 74 52 65 70 29 20  ment (eTextRep) 
2f6a0 6d 75 73 74 20 62 65 20 6f 6e 65 20 6f 66 20 74  must be one of t
2f6b0 68 65 20 63 6f 6e 73 74 61 6e 74 73 3a 0a 2a 2a  he constants:.**
2f6c0 20 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 5b 53   <ul>.** <li> [S
2f6d0 51 4c 49 54 45 5f 55 54 46 38 5d 2c 0a 2a 2a 20  QLITE_UTF8],.** 
2f6e0 3c 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46  <li> [SQLITE_UTF
2f6f0 31 36 4c 45 5d 2c 0a 2a 2a 20 3c 6c 69 3e 20 5b  16LE],.** <li> [
2f700 53 51 4c 49 54 45 5f 55 54 46 31 36 42 45 5d 2c  SQLITE_UTF16BE],
2f710 0a 2a 2a 20 3c 6c 69 3e 20 5b 53 51 4c 49 54 45  .** <li> [SQLITE
2f720 5f 55 54 46 31 36 5d 2c 20 6f 72 0a 2a 2a 20 3c  _UTF16], or.** <
2f730 6c 69 3e 20 5b 53 51 4c 49 54 45 5f 55 54 46 31  li> [SQLITE_UTF1
2f740 36 5f 41 4c 49 47 4e 45 44 5d 2e 0a 2a 2a 20 3c  6_ALIGNED]..** <
2f750 2f 75 6c 3e 29 5e 0a 2a 2a 20 5e 54 68 65 20 65  /ul>)^.** ^The e
2f760 54 65 78 74 52 65 70 20 61 72 67 75 6d 65 6e 74  TextRep argument
2f770 20 64 65 74 65 72 6d 69 6e 65 73 20 74 68 65 20   determines the 
2f780 65 6e 63 6f 64 69 6e 67 20 6f 66 20 73 74 72 69  encoding of stri
2f790 6e 67 73 20 70 61 73 73 65 64 0a 2a 2a 20 74 6f  ngs passed.** to
2f7a0 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66   the collating f
2f7b0 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b  unction callback
2f7c0 2c 20 78 43 61 6c 6c 62 61 63 6b 2e 0a 2a 2a 20  , xCallback..** 
2f7d0 5e 54 68 65 20 5b 53 51 4c 49 54 45 5f 55 54 46  ^The [SQLITE_UTF
2f7e0 31 36 5d 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f  16] and [SQLITE_
2f7f0 55 54 46 31 36 5f 41 4c 49 47 4e 45 44 5d 20 76  UTF16_ALIGNED] v
2f800 61 6c 75 65 73 20 66 6f 72 20 65 54 65 78 74 52  alues for eTextR
2f810 65 70 0a 2a 2a 20 66 6f 72 63 65 20 73 74 72 69  ep.** force stri
2f820 6e 67 73 20 74 6f 20 62 65 20 55 54 46 31 36 20  ngs to be UTF16 
2f830 77 69 74 68 20 6e 61 74 69 76 65 20 62 79 74 65  with native byte
2f840 20 6f 72 64 65 72 2e 0a 2a 2a 20 5e 54 68 65 20   order..** ^The 
2f850 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 5f 41 4c  [SQLITE_UTF16_AL
2f860 49 47 4e 45 44 5d 20 76 61 6c 75 65 20 66 6f 72  IGNED] value for
2f870 20 65 54 65 78 74 52 65 70 20 66 6f 72 63 65 73   eTextRep forces
2f880 20 73 74 72 69 6e 67 73 20 74 6f 20 62 65 67 69   strings to begi
2f890 6e 0a 2a 2a 20 6f 6e 20 61 6e 20 65 76 65 6e 20  n.** on an even 
2f8a0 62 79 74 65 20 61 64 64 72 65 73 73 2e 0a 2a 2a  byte address..**
2f8b0 0a 2a 2a 20 5e 54 68 65 20 66 6f 75 72 74 68 20  .** ^The fourth 
2f8c0 61 72 67 75 6d 65 6e 74 2c 20 70 41 72 67 2c 20  argument, pArg, 
2f8d0 69 73 20 61 6e 20 61 70 70 6c 69 63 61 74 69 6f  is an applicatio
2f8e0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 74  n data pointer t
2f8f0 68 61 74 20 69 73 20 70 61 73 73 65 64 0a 2a 2a  hat is passed.**
2f900 20 74 68 72 6f 75 67 68 20 61 73 20 74 68 65 20   through as the 
2f910 66 69 72 73 74 20 61 72 67 75 6d 65 6e 74 20 74  first argument t
2f920 6f 20 74 68 65 20 63 6f 6c 6c 61 74 69 6e 67 20  o the collating 
2f930 66 75 6e 63 74 69 6f 6e 20 63 61 6c 6c 62 61 63  function callbac
2f940 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 66 69  k..**.** ^The fi
2f950 66 74 68 20 61 72 67 75 6d 65 6e 74 2c 20 78 43  fth argument, xC
2f960 61 6c 6c 62 61 63 6b 2c 20 69 73 20 61 20 70 6f  allback, is a po
2f970 69 6e 74 65 72 20 74 6f 20 74 68 65 20 63 6f 6c  inter to the col
2f980 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 2e  lating function.
2f990 0a 2a 2a 20 5e 4d 75 6c 74 69 70 6c 65 20 63 6f  .** ^Multiple co
2f9a0 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e  llating function
2f9b0 73 20 63 61 6e 20 62 65 20 72 65 67 69 73 74 65  s can be registe
2f9c0 72 65 64 20 75 73 69 6e 67 20 74 68 65 20 73 61  red using the sa
2f9d0 6d 65 20 6e 61 6d 65 20 62 75 74 0a 2a 2a 20 77  me name but.** w
2f9e0 69 74 68 20 64 69 66 66 65 72 65 6e 74 20 65 54  ith different eT
2f9f0 65 78 74 52 65 70 20 70 61 72 61 6d 65 74 65 72  extRep parameter
2fa00 73 20 61 6e 64 20 53 51 4c 69 74 65 20 77 69 6c  s and SQLite wil
2fa10 6c 20 75 73 65 20 77 68 69 63 68 65 76 65 72 0a  l use whichever.
2fa20 2a 2a 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75  ** function requ
2fa30 69 72 65 73 20 74 68 65 20 6c 65 61 73 74 20 61  ires the least a
2fa40 6d 6f 75 6e 74 20 6f 66 20 64 61 74 61 20 74 72  mount of data tr
2fa50 61 6e 73 66 6f 72 6d 61 74 69 6f 6e 2e 0a 2a 2a  ansformation..**
2fa60 20 5e 49 66 20 74 68 65 20 78 43 61 6c 6c 62 61   ^If the xCallba
2fa70 63 6b 20 61 72 67 75 6d 65 6e 74 20 69 73 20 4e  ck argument is N
2fa80 55 4c 4c 20 74 68 65 6e 20 74 68 65 20 63 6f 6c  ULL then the col
2fa90 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20  lating function 
2faa0 69 73 0a 2a 2a 20 64 65 6c 65 74 65 64 2e 20 20  is.** deleted.  
2fab0 5e 57 68 65 6e 20 61 6c 6c 20 63 6f 6c 6c 61 74  ^When all collat
2fac0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 73 20 68 61  ing functions ha
2fad0 76 69 6e 67 20 74 68 65 20 73 61 6d 65 20 6e 61  ving the same na
2fae0 6d 65 20 61 72 65 20 64 65 6c 65 74 65 64 2c 0a  me are deleted,.
2faf0 2a 2a 20 74 68 61 74 20 63 6f 6c 6c 61 74 69 6f  ** that collatio
2fb00 6e 20 69 73 20 6e 6f 20 6c 6f 6e 67 65 72 20 75  n is no longer u
2fb10 73 61 62 6c 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  sable..**.** ^Th
2fb20 65 20 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63  e collating func
2fb30 74 69 6f 6e 20 63 61 6c 6c 62 61 63 6b 20 69 73  tion callback is
2fb40 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 61 20   invoked with a 
2fb50 63 6f 70 79 20 6f 66 20 74 68 65 20 70 41 72 67  copy of the pArg
2fb60 20 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e   .** application
2fb70 20 64 61 74 61 20 70 6f 69 6e 74 65 72 20 61 6e   data pointer an
2fb80 64 20 77 69 74 68 20 74 77 6f 20 73 74 72 69 6e  d with two strin
2fb90 67 73 20 69 6e 20 74 68 65 20 65 6e 63 6f 64 69  gs in the encodi
2fba0 6e 67 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  ng specified.** 
2fbb0 62 79 20 74 68 65 20 65 54 65 78 74 52 65 70 20  by the eTextRep 
2fbc0 61 72 67 75 6d 65 6e 74 2e 20 20 54 68 65 20 63  argument.  The c
2fbd0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2fbe0 6e 20 6d 75 73 74 20 72 65 74 75 72 6e 20 61 6e  n must return an
2fbf0 0a 2a 2a 20 69 6e 74 65 67 65 72 20 74 68 61 74  .** integer that
2fc00 20 69 73 20 6e 65 67 61 74 69 76 65 2c 20 7a 65   is negative, ze
2fc10 72 6f 2c 20 6f 72 20 70 6f 73 69 74 69 76 65 0a  ro, or positive.
2fc20 2a 2a 20 69 66 20 74 68 65 20 66 69 72 73 74 20  ** if the first 
2fc30 73 74 72 69 6e 67 20 69 73 20 6c 65 73 73 20 74  string is less t
2fc40 68 61 6e 2c 20 65 71 75 61 6c 20 74 6f 2c 20 6f  han, equal to, o
2fc50 72 20 67 72 65 61 74 65 72 20 74 68 61 6e 20 74  r greater than t
2fc60 68 65 20 73 65 63 6f 6e 64 2c 0a 2a 2a 20 72 65  he second,.** re
2fc70 73 70 65 63 74 69 76 65 6c 79 2e 20 20 41 20 63  spectively.  A c
2fc80 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2fc90 6e 20 6d 75 73 74 20 61 6c 77 61 79 73 20 72 65  n must always re
2fca0 74 75 72 6e 20 74 68 65 20 73 61 6d 65 20 61 6e  turn the same an
2fcb0 73 77 65 72 0a 2a 2a 20 67 69 76 65 6e 20 74 68  swer.** given th
2fcc0 65 20 73 61 6d 65 20 69 6e 70 75 74 73 2e 20 20  e same inputs.  
2fcd0 49 66 20 74 77 6f 20 6f 72 20 6d 6f 72 65 20 63  If two or more c
2fce0 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69 6f  ollating functio
2fcf0 6e 73 20 61 72 65 20 72 65 67 69 73 74 65 72 65  ns are registere
2fd00 64 0a 2a 2a 20 74 6f 20 74 68 65 20 73 61 6d 65  d.** to the same
2fd10 20 63 6f 6c 6c 61 74 69 6f 6e 20 6e 61 6d 65 20   collation name 
2fd20 28 75 73 69 6e 67 20 64 69 66 66 65 72 65 6e 74  (using different
2fd30 20 65 54 65 78 74 52 65 70 20 76 61 6c 75 65 73   eTextRep values
2fd40 29 20 74 68 65 6e 20 61 6c 6c 0a 2a 2a 20 6d 75  ) then all.** mu
2fd50 73 74 20 67 69 76 65 20 61 6e 20 65 71 75 69 76  st give an equiv
2fd60 61 6c 65 6e 74 20 61 6e 73 77 65 72 20 77 68 65  alent answer whe
2fd70 6e 20 69 6e 76 6f 6b 65 64 20 77 69 74 68 20 65  n invoked with e
2fd80 71 75 69 76 61 6c 65 6e 74 20 73 74 72 69 6e 67  quivalent string
2fd90 73 2e 0a 2a 2a 20 54 68 65 20 63 6f 6c 6c 61 74  s..** The collat
2fda0 69 6e 67 20 66 75 6e 63 74 69 6f 6e 20 6d 75 73  ing function mus
2fdb0 74 20 6f 62 65 79 20 74 68 65 20 66 6f 6c 6c 6f  t obey the follo
2fdc0 77 69 6e 67 20 70 72 6f 70 65 72 74 69 65 73 20  wing properties 
2fdd0 66 6f 72 20 61 6c 6c 0a 2a 2a 20 73 74 72 69 6e  for all.** strin
2fde0 67 73 20 41 2c 20 42 2c 20 61 6e 64 20 43 3a 0a  gs A, B, and C:.
2fdf0 2a 2a 0a 2a 2a 20 3c 6f 6c 3e 0a 2a 2a 20 3c 6c  **.** <ol>.** <l
2fe00 69 3e 20 49 66 20 41 3d 3d 42 20 74 68 65 6e 20  i> If A==B then 
2fe10 42 3d 3d 41 2e 0a 2a 2a 20 3c 6c 69 3e 20 49 66  B==A..** <li> If
2fe20 20 41 3d 3d 42 20 61 6e 64 20 42 3d 3d 43 20 74   A==B and B==C t
2fe30 68 65 6e 20 41 3d 3d 43 2e 0a 2a 2a 20 3c 6c 69  hen A==C..** <li
2fe40 3e 20 49 66 20 41 26 6c 74 3b 42 20 54 48 45 4e  > If A&lt;B THEN
2fe50 20 42 26 67 74 3b 41 2e 0a 2a 2a 20 3c 6c 69 3e   B&gt;A..** <li>
2fe60 20 49 66 20 41 26 6c 74 3b 42 20 61 6e 64 20 42   If A&lt;B and B
2fe70 26 6c 74 3b 43 20 74 68 65 6e 20 41 26 6c 74 3b  &lt;C then A&lt;
2fe80 43 2e 0a 2a 2a 20 3c 2f 6f 6c 3e 0a 2a 2a 0a 2a  C..** </ol>.**.*
2fe90 2a 20 49 66 20 61 20 63 6f 6c 6c 61 74 69 6e 67  * If a collating
2fea0 20 66 75 6e 63 74 69 6f 6e 20 66 61 69 6c 73 20   function fails 
2feb0 61 6e 79 20 6f 66 20 74 68 65 20 61 62 6f 76 65  any of the above
2fec0 20 63 6f 6e 73 74 72 61 69 6e 74 73 20 61 6e 64   constraints and
2fed0 20 74 68 61 74 0a 2a 2a 20 63 6f 6c 6c 61 74 69   that.** collati
2fee0 6e 67 20 66 75 6e 63 74 69 6f 6e 20 69 73 20 20  ng function is  
2fef0 72 65 67 69 73 74 65 72 65 64 20 61 6e 64 20 75  registered and u
2ff00 73 65 64 2c 20 74 68 65 6e 20 74 68 65 20 62 65  sed, then the be
2ff10 68 61 76 69 6f 72 20 6f 66 20 53 51 4c 69 74 65  havior of SQLite
2ff20 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69 6e 65 64  .** is undefined
2ff30 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c  ..**.** ^The sql
2ff40 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c  ite3_create_coll
2ff50 61 74 69 6f 6e 5f 76 32 28 29 20 77 6f 72 6b 73  ation_v2() works
2ff60 20 6c 69 6b 65 20 73 71 6c 69 74 65 33 5f 63 72   like sqlite3_cr
2ff70 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 28 29  eate_collation()
2ff80 0a 2a 2a 20 77 69 74 68 20 74 68 65 20 61 64 64  .** with the add
2ff90 69 74 69 6f 6e 20 74 68 61 74 20 74 68 65 20 78  ition that the x
2ffa0 44 65 73 74 72 6f 79 20 63 61 6c 6c 62 61 63 6b  Destroy callback
2ffb0 20 69 73 20 69 6e 76 6f 6b 65 64 20 6f 6e 20 70   is invoked on p
2ffc0 41 72 67 20 77 68 65 6e 0a 2a 2a 20 74 68 65 20  Arg when.** the 
2ffd0 63 6f 6c 6c 61 74 69 6e 67 20 66 75 6e 63 74 69  collating functi
2ffe0 6f 6e 20 69 73 20 64 65 6c 65 74 65 64 2e 0a 2a  on is deleted..*
2fff0 2a 20 5e 43 6f 6c 6c 61 74 69 6e 67 20 66 75 6e  * ^Collating fun
30000 63 74 69 6f 6e 73 20 61 72 65 20 64 65 6c 65 74  ctions are delet
30010 65 64 20 77 68 65 6e 20 74 68 65 79 20 61 72 65  ed when they are
30020 20 6f 76 65 72 72 69 64 64 65 6e 20 62 79 20 6c   overridden by l
30030 61 74 65 72 0a 2a 2a 20 63 61 6c 6c 73 20 74 6f  ater.** calls to
30040 20 74 68 65 20 63 6f 6c 6c 61 74 69 6f 6e 20 63   the collation c
30050 72 65 61 74 69 6f 6e 20 66 75 6e 63 74 69 6f 6e  reation function
30060 73 20 6f 72 20 77 68 65 6e 20 74 68 65 0a 2a 2a  s or when the.**
30070 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65   [database conne
30080 63 74 69 6f 6e 5d 20 69 73 20 63 6c 6f 73 65 64  ction] is closed
30090 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33 5f   using [sqlite3_
300a0 63 6c 6f 73 65 28 29 5d 2e 0a 2a 2a 0a 2a 2a 20  close()]..**.** 
300b0 5e 54 68 65 20 78 44 65 73 74 72 6f 79 20 63 61  ^The xDestroy ca
300c0 6c 6c 62 61 63 6b 20 69 73 20 3c 75 3e 6e 6f 74  llback is <u>not
300d0 3c 2f 75 3e 20 63 61 6c 6c 65 64 20 69 66 20 74  </u> called if t
300e0 68 65 20 0a 2a 2a 20 73 71 6c 69 74 65 33 5f 63  he .** sqlite3_c
300f0 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69 6f 6e 5f  reate_collation_
30100 76 32 28 29 20 66 75 6e 63 74 69 6f 6e 20 66 61  v2() function fa
30110 69 6c 73 2e 20 20 41 70 70 6c 69 63 61 74 69 6f  ils.  Applicatio
30120 6e 73 20 74 68 61 74 20 69 6e 76 6f 6b 65 0a 2a  ns that invoke.*
30130 2a 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  * sqlite3_create
30140 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 20  _collation_v2() 
30150 77 69 74 68 20 61 20 6e 6f 6e 2d 4e 55 4c 4c 20  with a non-NULL 
30160 78 44 65 73 74 72 6f 79 20 61 72 67 75 6d 65 6e  xDestroy argumen
30170 74 20 73 68 6f 75 6c 64 20 0a 2a 2a 20 63 68 65  t should .** che
30180 63 6b 20 74 68 65 20 72 65 74 75 72 6e 20 63 6f  ck the return co
30190 64 65 20 61 6e 64 20 64 69 73 70 6f 73 65 20 6f  de and dispose o
301a0 66 20 74 68 65 20 61 70 70 6c 69 63 61 74 69 6f  f the applicatio
301b0 6e 20 64 61 74 61 20 70 6f 69 6e 74 65 72 0a 2a  n data pointer.*
301c0 2a 20 74 68 65 6d 73 65 6c 76 65 73 20 72 61 74  * themselves rat
301d0 68 65 72 20 74 68 61 6e 20 65 78 70 65 63 74 69  her than expecti
301e0 6e 67 20 53 51 4c 69 74 65 20 74 6f 20 64 65 61  ng SQLite to dea
301f0 6c 20 77 69 74 68 20 69 74 20 66 6f 72 20 74 68  l with it for th
30200 65 6d 2e 0a 2a 2a 20 54 68 69 73 20 69 73 20 64  em..** This is d
30210 69 66 66 65 72 65 6e 74 20 66 72 6f 6d 20 65 76  ifferent from ev
30220 65 72 79 20 6f 74 68 65 72 20 53 51 4c 69 74 65  ery other SQLite
30230 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 65   interface.  The
30240 20 69 6e 63 6f 6e 73 69 73 74 65 6e 63 79 20 0a   inconsistency .
30250 2a 2a 20 69 73 20 75 6e 66 6f 72 74 75 6e 61 74  ** is unfortunat
30260 65 20 62 75 74 20 63 61 6e 6e 6f 74 20 62 65 20  e but cannot be 
30270 63 68 61 6e 67 65 64 20 77 69 74 68 6f 75 74 20  changed without 
30280 62 72 65 61 6b 69 6e 67 20 62 61 63 6b 77 61 72  breaking backwar
30290 64 73 20 0a 2a 2a 20 63 6f 6d 70 61 74 69 62 69  ds .** compatibi
302a0 6c 69 74 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  lity..**.** See 
302b0 61 6c 73 6f 3a 20 20 5b 73 71 6c 69 74 65 33 5f  also:  [sqlite3_
302c0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
302d0 28 29 5d 20 61 6e 64 20 5b 73 71 6c 69 74 65 33  ()] and [sqlite3
302e0 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
302f0 64 31 36 28 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73  d16()]..*/.int s
30300 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63 6f  qlite3_create_co
30310 6c 6c 61 74 69 6f 6e 28 0a 20 20 73 71 6c 69 74  llation(.  sqlit
30320 65 33 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68  e3*, .  const ch
30330 61 72 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e  ar *zName, .  in
30340 74 20 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76  t eTextRep, .  v
30350 6f 69 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74  oid *pArg,.  int
30360 28 2a 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64  (*xCompare)(void
30370 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
30380 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64  *,int,const void
30390 2a 29 0a 29 3b 0a 69 6e 74 20 73 71 6c 69 74 65  *).);.int sqlite
303a0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
303b0 6f 6e 5f 76 32 28 0a 20 20 73 71 6c 69 74 65 33  on_v2(.  sqlite3
303c0 2a 2c 20 0a 20 20 63 6f 6e 73 74 20 63 68 61 72  *, .  const char
303d0 20 2a 7a 4e 61 6d 65 2c 20 0a 20 20 69 6e 74 20   *zName, .  int 
303e0 65 54 65 78 74 52 65 70 2c 20 0a 20 20 76 6f 69  eTextRep, .  voi
303f0 64 20 2a 70 41 72 67 2c 0a 20 20 69 6e 74 28 2a  d *pArg,.  int(*
30400 78 43 6f 6d 70 61 72 65 29 28 76 6f 69 64 2a 2c  xCompare)(void*,
30410 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 2c  int,const void*,
30420 69 6e 74 2c 63 6f 6e 73 74 20 76 6f 69 64 2a 29  int,const void*)
30430 2c 0a 20 20 76 6f 69 64 28 2a 78 44 65 73 74 72  ,.  void(*xDestr
30440 6f 79 29 28 76 6f 69 64 2a 29 0a 29 3b 0a 69 6e  oy)(void*).);.in
30450 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  t sqlite3_create
30460 5f 63 6f 6c 6c 61 74 69 6f 6e 31 36 28 0a 20 20  _collation16(.  
30470 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 63 6f 6e  sqlite3*, .  con
30480 73 74 20 76 6f 69 64 20 2a 7a 4e 61 6d 65 2c 0a  st void *zName,.
30490 20 20 69 6e 74 20 65 54 65 78 74 52 65 70 2c 20    int eTextRep, 
304a0 0a 20 20 76 6f 69 64 20 2a 70 41 72 67 2c 0a 20  .  void *pArg,. 
304b0 20 69 6e 74 28 2a 78 43 6f 6d 70 61 72 65 29 28   int(*xCompare)(
304c0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
304d0 76 6f 69 64 2a 2c 69 6e 74 2c 63 6f 6e 73 74 20  void*,int,const 
304e0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 2f 2a 0a 2a 2a  void*).);../*.**
304f0 20 43 41 50 49 33 52 45 46 3a 20 43 6f 6c 6c 61   CAPI3REF: Colla
30500 74 69 6f 6e 20 4e 65 65 64 65 64 20 43 61 6c 6c  tion Needed Call
30510 62 61 63 6b 73 0a 2a 2a 0a 2a 2a 20 5e 54 6f 20  backs.**.** ^To 
30520 61 76 6f 69 64 20 68 61 76 69 6e 67 20 74 6f 20  avoid having to 
30530 72 65 67 69 73 74 65 72 20 61 6c 6c 20 63 6f 6c  register all col
30540 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65 73  lation sequences
30550 20 62 65 66 6f 72 65 20 61 20 64 61 74 61 62 61   before a databa
30560 73 65 0a 2a 2a 20 63 61 6e 20 62 65 20 75 73 65  se.** can be use
30570 64 2c 20 61 20 73 69 6e 67 6c 65 20 63 61 6c 6c  d, a single call
30580 62 61 63 6b 20 66 75 6e 63 74 69 6f 6e 20 6d 61  back function ma
30590 79 20 62 65 20 72 65 67 69 73 74 65 72 65 64 20  y be registered 
305a0 77 69 74 68 20 74 68 65 0a 2a 2a 20 5b 64 61 74  with the.** [dat
305b0 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
305c0 5d 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20  ] to be invoked 
305d0 77 68 65 6e 65 76 65 72 20 61 6e 20 75 6e 64 65  whenever an unde
305e0 66 69 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 0a  fined collation.
305f0 2a 2a 20 73 65 71 75 65 6e 63 65 20 69 73 20 72  ** sequence is r
30600 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  equired..**.** ^
30610 49 66 20 74 68 65 20 66 75 6e 63 74 69 6f 6e 20  If the function 
30620 69 73 20 72 65 67 69 73 74 65 72 65 64 20 75 73  is registered us
30630 69 6e 67 20 74 68 65 20 73 71 6c 69 74 65 33 5f  ing the sqlite3_
30640 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
30650 28 29 20 41 50 49 2c 0a 2a 2a 20 74 68 65 6e 20  () API,.** then 
30660 69 74 20 69 73 20 70 61 73 73 65 64 20 74 68 65  it is passed the
30670 20 6e 61 6d 65 73 20 6f 66 20 75 6e 64 65 66 69   names of undefi
30680 6e 65 64 20 63 6f 6c 6c 61 74 69 6f 6e 20 73 65  ned collation se
30690 71 75 65 6e 63 65 73 20 61 73 20 73 74 72 69 6e  quences as strin
306a0 67 73 0a 2a 2a 20 65 6e 63 6f 64 65 64 20 69 6e  gs.** encoded in
306b0 20 55 54 46 2d 38 2e 20 5e 49 66 20 73 71 6c 69   UTF-8. ^If sqli
306c0 74 65 33 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65  te3_collation_ne
306d0 65 64 65 64 31 36 28 29 20 69 73 20 75 73 65 64  eded16() is used
306e0 2c 0a 2a 2a 20 74 68 65 20 6e 61 6d 65 73 20 61  ,.** the names a
306f0 72 65 20 70 61 73 73 65 64 20 61 73 20 55 54 46  re passed as UTF
30700 2d 31 36 20 69 6e 20 6d 61 63 68 69 6e 65 20 6e  -16 in machine n
30710 61 74 69 76 65 20 62 79 74 65 20 6f 72 64 65 72  ative byte order
30720 2e 0a 2a 2a 20 5e 41 20 63 61 6c 6c 20 74 6f 20  ..** ^A call to 
30730 65 69 74 68 65 72 20 66 75 6e 63 74 69 6f 6e 20  either function 
30740 72 65 70 6c 61 63 65 73 20 74 68 65 20 65 78 69  replaces the exi
30750 73 74 69 6e 67 20 63 6f 6c 6c 61 74 69 6f 6e 2d  sting collation-
30760 6e 65 65 64 65 64 20 63 61 6c 6c 62 61 63 6b 2e  needed callback.
30770 0a 2a 2a 0a 2a 2a 20 5e 28 57 68 65 6e 20 74 68  .**.** ^(When th
30780 65 20 63 61 6c 6c 62 61 63 6b 20 69 73 20 69 6e  e callback is in
30790 76 6f 6b 65 64 2c 20 74 68 65 20 66 69 72 73 74  voked, the first
307a0 20 61 72 67 75 6d 65 6e 74 20 70 61 73 73 65 64   argument passed
307b0 20 69 73 20 61 20 63 6f 70 79 0a 2a 2a 20 6f 66   is a copy.** of
307c0 20 74 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75   the second argu
307d0 6d 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  ment to sqlite3_
307e0 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64  collation_needed
307f0 28 29 20 6f 72 0a 2a 2a 20 73 71 6c 69 74 65 33  () or.** sqlite3
30800 5f 63 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65  _collation_neede
30810 64 31 36 28 29 2e 20 20 54 68 65 20 73 65 63 6f  d16().  The seco
30820 6e 64 20 61 72 67 75 6d 65 6e 74 20 69 73 20 74  nd argument is t
30830 68 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 63  he database.** c
30840 6f 6e 6e 65 63 74 69 6f 6e 2e 20 20 54 68 65 20  onnection.  The 
30850 74 68 69 72 64 20 61 72 67 75 6d 65 6e 74 20 69  third argument i
30860 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54 45  s one of [SQLITE
30870 5f 55 54 46 38 5d 2c 20 5b 53 51 4c 49 54 45 5f  _UTF8], [SQLITE_
30880 55 54 46 31 36 42 45 5d 2c 0a 2a 2a 20 6f 72 20  UTF16BE],.** or 
30890 5b 53 51 4c 49 54 45 5f 55 54 46 31 36 4c 45 5d  [SQLITE_UTF16LE]
308a0 2c 20 69 6e 64 69 63 61 74 69 6e 67 20 74 68 65  , indicating the
308b0 20 6d 6f 73 74 20 64 65 73 69 72 61 62 6c 65 20   most desirable 
308c0 66 6f 72 6d 20 6f 66 20 74 68 65 20 63 6f 6c 6c  form of the coll
308d0 61 74 69 6f 6e 0a 2a 2a 20 73 65 71 75 65 6e 63  ation.** sequenc
308e0 65 20 66 75 6e 63 74 69 6f 6e 20 72 65 71 75 69  e function requi
308f0 72 65 64 2e 20 20 54 68 65 20 66 6f 75 72 74 68  red.  The fourth
30900 20 70 61 72 61 6d 65 74 65 72 20 69 73 20 74 68   parameter is th
30910 65 20 6e 61 6d 65 20 6f 66 20 74 68 65 0a 2a 2a  e name of the.**
30920 20 72 65 71 75 69 72 65 64 20 63 6f 6c 6c 61 74   required collat
30930 69 6f 6e 20 73 65 71 75 65 6e 63 65 2e 29 5e 0a  ion sequence.)^.
30940 2a 2a 0a 2a 2a 20 54 68 65 20 63 61 6c 6c 62 61  **.** The callba
30950 63 6b 20 66 75 6e 63 74 69 6f 6e 20 73 68 6f 75  ck function shou
30960 6c 64 20 72 65 67 69 73 74 65 72 20 74 68 65 20  ld register the 
30970 64 65 73 69 72 65 64 20 63 6f 6c 6c 61 74 69 6f  desired collatio
30980 6e 20 75 73 69 6e 67 0a 2a 2a 20 5b 73 71 6c 69  n using.** [sqli
30990 74 65 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61  te3_create_colla
309a0 74 69 6f 6e 28 29 5d 2c 20 5b 73 71 6c 69 74 65  tion()], [sqlite
309b0 33 5f 63 72 65 61 74 65 5f 63 6f 6c 6c 61 74 69  3_create_collati
309c0 6f 6e 31 36 28 29 5d 2c 20 6f 72 0a 2a 2a 20 5b  on16()], or.** [
309d0 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 63  sqlite3_create_c
309e0 6f 6c 6c 61 74 69 6f 6e 5f 76 32 28 29 5d 2e 0a  ollation_v2()]..
309f0 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63  */.int sqlite3_c
30a00 6f 6c 6c 61 74 69 6f 6e 5f 6e 65 65 64 65 64 28  ollation_needed(
30a10 0a 20 20 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20  .  sqlite3*, .  
30a20 76 6f 69 64 2a 2c 20 0a 20 20 76 6f 69 64 28 2a  void*, .  void(*
30a30 29 28 76 6f 69 64 2a 2c 73 71 6c 69 74 65 33 2a  )(void*,sqlite3*
30a40 2c 69 6e 74 20 65 54 65 78 74 52 65 70 2c 63 6f  ,int eTextRep,co
30a50 6e 73 74 20 63 68 61 72 2a 29 0a 29 3b 0a 69 6e  nst char*).);.in
30a60 74 20 73 71 6c 69 74 65 33 5f 63 6f 6c 6c 61 74  t sqlite3_collat
30a70 69 6f 6e 5f 6e 65 65 64 65 64 31 36 28 0a 20 20  ion_needed16(.  
30a80 73 71 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69  sqlite3*, .  voi
30a90 64 2a 2c 0a 20 20 76 6f 69 64 28 2a 29 28 76 6f  d*,.  void(*)(vo
30aa0 69 64 2a 2c 73 71 6c 69 74 65 33 2a 2c 69 6e 74  id*,sqlite3*,int
30ab0 20 65 54 65 78 74 52 65 70 2c 63 6f 6e 73 74 20   eTextRep,const 
30ac0 76 6f 69 64 2a 29 0a 29 3b 0a 0a 23 69 66 64 65  void*).);..#ifde
30ad0 66 20 53 51 4c 49 54 45 5f 48 41 53 5f 43 4f 44  f SQLITE_HAS_COD
30ae0 45 43 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79  EC./*.** Specify
30af0 20 74 68 65 20 6b 65 79 20 66 6f 72 20 61 6e 20   the key for an 
30b00 65 6e 63 72 79 70 74 65 64 20 64 61 74 61 62 61  encrypted databa
30b10 73 65 2e 20 20 54 68 69 73 20 72 6f 75 74 69 6e  se.  This routin
30b20 65 20 73 68 6f 75 6c 64 20 62 65 0a 2a 2a 20 63  e should be.** c
30b30 61 6c 6c 65 64 20 72 69 67 68 74 20 61 66 74 65  alled right afte
30b40 72 20 73 71 6c 69 74 65 33 5f 6f 70 65 6e 28 29  r sqlite3_open()
30b50 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 63 6f 64 65  ..**.** The code
30b60 20 74 6f 20 69 6d 70 6c 65 6d 65 6e 74 20 74 68   to implement th
30b70 69 73 20 41 50 49 20 69 73 20 6e 6f 74 20 61 76  is API is not av
30b80 61 69 6c 61 62 6c 65 20 69 6e 20 74 68 65 20 70  ailable in the p
30b90 75 62 6c 69 63 20 72 65 6c 65 61 73 65 0a 2a 2a  ublic release.**
30ba0 20 6f 66 20 53 51 4c 69 74 65 2e 0a 2a 2f 0a 69   of SQLite..*/.i
30bb0 6e 74 20 73 71 6c 69 74 65 33 5f 6b 65 79 28 0a  nt sqlite3_key(.
30bc0 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20    sqlite3 *db,  
30bd0 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
30be0 20 2f 2a 20 44 61 74 61 62 61 73 65 20 74 6f 20   /* Database to 
30bf0 62 65 20 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20  be rekeyed */.  
30c00 63 6f 6e 73 74 20 76 6f 69 64 20 2a 70 4b 65 79  const void *pKey
30c10 2c 20 69 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f  , int nKey     /
30c20 2a 20 54 68 65 20 6b 65 79 20 2a 2f 0a 29 3b 0a  * The key */.);.
30c30 0a 2f 2a 0a 2a 2a 20 43 68 61 6e 67 65 20 74 68  ./*.** Change th
30c40 65 20 6b 65 79 20 6f 6e 20 61 6e 20 6f 70 65 6e  e key on an open
30c50 20 64 61 74 61 62 61 73 65 2e 20 20 49 66 20 74   database.  If t
30c60 68 65 20 63 75 72 72 65 6e 74 20 64 61 74 61 62  he current datab
30c70 61 73 65 20 69 73 20 6e 6f 74 0a 2a 2a 20 65 6e  ase is not.** en
30c80 63 72 79 70 74 65 64 2c 20 74 68 69 73 20 72 6f  crypted, this ro
30c90 75 74 69 6e 65 20 77 69 6c 6c 20 65 6e 63 72 79  utine will encry
30ca0 70 74 20 69 74 2e 20 20 49 66 20 70 4e 65 77 3d  pt it.  If pNew=
30cb0 3d 30 20 6f 72 20 6e 4e 65 77 3d 3d 30 2c 20 74  =0 or nNew==0, t
30cc0 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 69  he.** database i
30cd0 73 20 64 65 63 72 79 70 74 65 64 2e 0a 2a 2a 0a  s decrypted..**.
30ce0 2a 2a 20 54 68 65 20 63 6f 64 65 20 74 6f 20 69  ** The code to i
30cf0 6d 70 6c 65 6d 65 6e 74 20 74 68 69 73 20 41 50  mplement this AP
30d00 49 20 69 73 20 6e 6f 74 20 61 76 61 69 6c 61 62  I is not availab
30d10 6c 65 20 69 6e 20 74 68 65 20 70 75 62 6c 69 63  le in the public
30d20 20 72 65 6c 65 61 73 65 0a 2a 2a 20 6f 66 20 53   release.** of S
30d30 51 4c 69 74 65 2e 0a 2a 2f 0a 69 6e 74 20 73 71  QLite..*/.int sq
30d40 6c 69 74 65 33 5f 72 65 6b 65 79 28 0a 20 20 73  lite3_rekey(.  s
30d50 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20  qlite3 *db,     
30d60 20 20 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a                /*
30d70 20 44 61 74 61 62 61 73 65 20 74 6f 20 62 65 20   Database to be 
30d80 72 65 6b 65 79 65 64 20 2a 2f 0a 20 20 63 6f 6e  rekeyed */.  con
30d90 73 74 20 76 6f 69 64 20 2a 70 4b 65 79 2c 20 69  st void *pKey, i
30da0 6e 74 20 6e 4b 65 79 20 20 20 20 20 2f 2a 20 54  nt nKey     /* T
30db0 68 65 20 6e 65 77 20 6b 65 79 20 2a 2f 0a 29 3b  he new key */.);
30dc0 0a 0a 2f 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20  ../*.** Specify 
30dd0 74 68 65 20 61 63 74 69 76 61 74 69 6f 6e 20 6b  the activation k
30de0 65 79 20 66 6f 72 20 61 20 53 45 45 20 64 61 74  ey for a SEE dat
30df0 61 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a  abase.  Unless .
30e00 2a 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f  ** activated, no
30e10 6e 65 20 6f 66 20 74 68 65 20 53 45 45 20 72 6f  ne of the SEE ro
30e20 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72 6b  utines will work
30e30 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74 65  ..*/.void sqlite
30e40 33 5f 61 63 74 69 76 61 74 65 5f 73 65 65 28 0a  3_activate_see(.
30e50 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a 7a 50    const char *zP
30e60 61 73 73 50 68 72 61 73 65 20 20 20 20 20 20 20  assPhrase       
30e70 20 2f 2a 20 41 63 74 69 76 61 74 69 6f 6e 20 70   /* Activation p
30e80 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23 65 6e 64  hrase */.);.#end
30e90 69 66 0a 0a 23 69 66 64 65 66 20 53 51 4c 49 54  if..#ifdef SQLIT
30ea0 45 5f 45 4e 41 42 4c 45 5f 43 45 52 4f 44 0a 2f  E_ENABLE_CEROD./
30eb0 2a 0a 2a 2a 20 53 70 65 63 69 66 79 20 74 68 65  *.** Specify the
30ec0 20 61 63 74 69 76 61 74 69 6f 6e 20 6b 65 79 20   activation key 
30ed0 66 6f 72 20 61 20 43 45 52 4f 44 20 64 61 74 61  for a CEROD data
30ee0 62 61 73 65 2e 20 20 55 6e 6c 65 73 73 20 0a 2a  base.  Unless .*
30ef0 2a 20 61 63 74 69 76 61 74 65 64 2c 20 6e 6f 6e  * activated, non
30f00 65 20 6f 66 20 74 68 65 20 43 45 52 4f 44 20 72  e of the CEROD r
30f10 6f 75 74 69 6e 65 73 20 77 69 6c 6c 20 77 6f 72  outines will wor
30f20 6b 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69 74  k..*/.void sqlit
30f30 65 33 5f 61 63 74 69 76 61 74 65 5f 63 65 72 6f  e3_activate_cero
30f40 64 28 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  d(.  const char 
30f50 2a 7a 50 61 73 73 50 68 72 61 73 65 20 20 20 20  *zPassPhrase    
30f60 20 20 20 20 2f 2a 20 41 63 74 69 76 61 74 69 6f      /* Activatio
30f70 6e 20 70 68 72 61 73 65 20 2a 2f 0a 29 3b 0a 23  n phrase */.);.#
30f80 65 6e 64 69 66 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  endif../*.** CAP
30f90 49 33 52 45 46 3a 20 53 75 73 70 65 6e 64 20 45  I3REF: Suspend E
30fa0 78 65 63 75 74 69 6f 6e 20 46 6f 72 20 41 20 53  xecution For A S
30fb0 68 6f 72 74 20 54 69 6d 65 0a 2a 2a 0a 2a 2a 20  hort Time.**.** 
30fc0 54 68 65 20 73 71 6c 69 74 65 33 5f 73 6c 65 65  The sqlite3_slee
30fd0 70 28 29 20 66 75 6e 63 74 69 6f 6e 20 63 61 75  p() function cau
30fe0 73 65 73 20 74 68 65 20 63 75 72 72 65 6e 74 20  ses the current 
30ff0 74 68 72 65 61 64 20 74 6f 20 73 75 73 70 65 6e  thread to suspen
31000 64 20 65 78 65 63 75 74 69 6f 6e 0a 2a 2a 20 66  d execution.** f
31010 6f 72 20 61 74 20 6c 65 61 73 74 20 61 20 6e 75  or at least a nu
31020 6d 62 65 72 20 6f 66 20 6d 69 6c 6c 69 73 65 63  mber of millisec
31030 6f 6e 64 73 20 73 70 65 63 69 66 69 65 64 20 69  onds specified i
31040 6e 20 69 74 73 20 70 61 72 61 6d 65 74 65 72 2e  n its parameter.
31050 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 6f 70  .**.** If the op
31060 65 72 61 74 69 6e 67 20 73 79 73 74 65 6d 20 64  erating system d
31070 6f 65 73 20 6e 6f 74 20 73 75 70 70 6f 72 74 20  oes not support 
31080 73 6c 65 65 70 20 72 65 71 75 65 73 74 73 20 77  sleep requests w
31090 69 74 68 0a 2a 2a 20 6d 69 6c 6c 69 73 65 63 6f  ith.** milliseco
310a0 6e 64 20 74 69 6d 65 20 72 65 73 6f 6c 75 74 69  nd time resoluti
310b0 6f 6e 2c 20 74 68 65 6e 20 74 68 65 20 74 69 6d  on, then the tim
310c0 65 20 77 69 6c 6c 20 62 65 20 72 6f 75 6e 64 65  e will be rounde
310d0 64 20 75 70 20 74 6f 0a 2a 2a 20 74 68 65 20 6e  d up to.** the n
310e0 65 61 72 65 73 74 20 73 65 63 6f 6e 64 2e 20 54  earest second. T
310f0 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 6d 69 6c  he number of mil
31100 6c 69 73 65 63 6f 6e 64 73 20 6f 66 20 73 6c 65  liseconds of sle
31110 65 70 20 61 63 74 75 61 6c 6c 79 0a 2a 2a 20 72  ep actually.** r
31120 65 71 75 65 73 74 65 64 20 66 72 6f 6d 20 74 68  equested from th
31130 65 20 6f 70 65 72 61 74 69 6e 67 20 73 79 73 74  e operating syst
31140 65 6d 20 69 73 20 72 65 74 75 72 6e 65 64 2e 0a  em is returned..
31150 2a 2a 0a 2a 2a 20 5e 53 51 4c 69 74 65 20 69 6d  **.** ^SQLite im
31160 70 6c 65 6d 65 6e 74 73 20 74 68 69 73 20 69 6e  plements this in
31170 74 65 72 66 61 63 65 20 62 79 20 63 61 6c 6c 69  terface by calli
31180 6e 67 20 74 68 65 20 78 53 6c 65 65 70 28 29 0a  ng the xSleep().
31190 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20 74 68 65  ** method of the
311a0 20 64 65 66 61 75 6c 74 20 5b 73 71 6c 69 74 65   default [sqlite
311b0 33 5f 76 66 73 5d 20 6f 62 6a 65 63 74 2e 20 20  3_vfs] object.  
311c0 49 66 20 74 68 65 20 78 53 6c 65 65 70 28 29 20  If the xSleep() 
311d0 6d 65 74 68 6f 64 0a 2a 2a 20 6f 66 20 74 68 65  method.** of the
311e0 20 64 65 66 61 75 6c 74 20 56 46 53 20 69 73 20   default VFS is 
311f0 6e 6f 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20  not implemented 
31200 63 6f 72 72 65 63 74 6c 79 2c 20 6f 72 20 6e 6f  correctly, or no
31210 74 20 69 6d 70 6c 65 6d 65 6e 74 65 64 20 61 74  t implemented at
31220 0a 2a 2a 20 61 6c 6c 2c 20 74 68 65 6e 20 74 68  .** all, then th
31230 65 20 62 65 68 61 76 69 6f 72 20 6f 66 20 73 71  e behavior of sq
31240 6c 69 74 65 33 5f 73 6c 65 65 70 28 29 20 6d 61  lite3_sleep() ma
31250 79 20 64 65 76 69 61 74 65 20 66 72 6f 6d 20 74  y deviate from t
31260 68 65 20 64 65 73 63 72 69 70 74 69 6f 6e 0a 2a  he description.*
31270 2a 20 69 6e 20 74 68 65 20 70 72 65 76 69 6f 75  * in the previou
31280 73 20 70 61 72 61 67 72 61 70 68 73 2e 0a 2a 2f  s paragraphs..*/
31290 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 73 6c 65  .int sqlite3_sle
312a0 65 70 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ep(int);../*.** 
312b0 43 41 50 49 33 52 45 46 3a 20 4e 61 6d 65 20 4f  CAPI3REF: Name O
312c0 66 20 54 68 65 20 46 6f 6c 64 65 72 20 48 6f 6c  f The Folder Hol
312d0 64 69 6e 67 20 54 65 6d 70 6f 72 61 72 79 20 46  ding Temporary F
312e0 69 6c 65 73 0a 2a 2a 0a 2a 2a 20 5e 28 49 66 20  iles.**.** ^(If 
312f0 74 68 69 73 20 67 6c 6f 62 61 6c 20 76 61 72 69  this global vari
31300 61 62 6c 65 20 69 73 20 6d 61 64 65 20 74 6f 20  able is made to 
31310 70 6f 69 6e 74 20 74 6f 20 61 20 73 74 72 69 6e  point to a strin
31320 67 20 77 68 69 63 68 20 69 73 0a 2a 2a 20 74 68  g which is.** th
31330 65 20 6e 61 6d 65 20 6f 66 20 61 20 66 6f 6c 64  e name of a fold
31340 65 72 20 28 61 2e 6b 2e 61 2e 20 64 69 72 65 63  er (a.k.a. direc
31350 74 6f 72 79 29 2c 20 74 68 65 6e 20 61 6c 6c 20  tory), then all 
31360 74 65 6d 70 6f 72 61 72 79 20 66 69 6c 65 73 0a  temporary files.
31370 2a 2a 20 63 72 65 61 74 65 64 20 62 79 20 53 51  ** created by SQ
31380 4c 69 74 65 20 77 68 65 6e 20 75 73 69 6e 67 20  Lite when using 
31390 61 20 62 75 69 6c 74 2d 69 6e 20 5b 73 71 6c 69  a built-in [sqli
313a0 74 65 33 5f 76 66 73 20 7c 20 56 46 53 5d 0a 2a  te3_vfs | VFS].*
313b0 2a 20 77 69 6c 6c 20 62 65 20 70 6c 61 63 65 64  * will be placed
313c0 20 69 6e 20 74 68 61 74 20 64 69 72 65 63 74 6f   in that directo
313d0 72 79 2e 29 5e 20 20 5e 49 66 20 74 68 69 73 20  ry.)^  ^If this 
313e0 76 61 72 69 61 62 6c 65 0a 2a 2a 20 69 73 20 61  variable.** is a
313f0 20 4e 55 4c 4c 20 70 6f 69 6e 74 65 72 2c 20 74   NULL pointer, t
31400 68 65 6e 20 53 51 4c 69 74 65 20 70 65 72 66 6f  hen SQLite perfo
31410 72 6d 73 20 61 20 73 65 61 72 63 68 20 66 6f 72  rms a search for
31420 20 61 6e 20 61 70 70 72 6f 70 72 69 61 74 65 0a   an appropriate.
31430 2a 2a 20 74 65 6d 70 6f 72 61 72 79 20 66 69 6c  ** temporary fil
31440 65 20 64 69 72 65 63 74 6f 72 79 2e 0a 2a 2a 0a  e directory..**.
31450 2a 2a 20 49 74 20 69 73 20 6e 6f 74 20 73 61 66  ** It is not saf
31460 65 20 74 6f 20 72 65 61 64 20 6f 72 20 6d 6f 64  e to read or mod
31470 69 66 79 20 74 68 69 73 20 76 61 72 69 61 62 6c  ify this variabl
31480 65 20 69 6e 20 6d 6f 72 65 20 74 68 61 6e 20 6f  e in more than o
31490 6e 65 0a 2a 2a 20 74 68 72 65 61 64 20 61 74 20  ne.** thread at 
314a0 61 20 74 69 6d 65 2e 20 20 49 74 20 69 73 20 6e  a time.  It is n
314b0 6f 74 20 73 61 66 65 20 74 6f 20 72 65 61 64 20  ot safe to read 
314c0 6f 72 20 6d 6f 64 69 66 79 20 74 68 69 73 20 76  or modify this v
314d0 61 72 69 61 62 6c 65 0a 2a 2a 20 69 66 20 61 20  ariable.** if a 
314e0 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63  [database connec
314f0 74 69 6f 6e 5d 20 69 73 20 62 65 69 6e 67 20 75  tion] is being u
31500 73 65 64 20 61 74 20 74 68 65 20 73 61 6d 65 20  sed at the same 
31510 74 69 6d 65 20 69 6e 20 61 20 73 65 70 61 72 61  time in a separa
31520 74 65 0a 2a 2a 20 74 68 72 65 61 64 2e 0a 2a 2a  te.** thread..**
31530 20 49 74 20 69 73 20 69 6e 74 65 6e 64 65 64 20   It is intended 
31540 74 68 61 74 20 74 68 69 73 20 76 61 72 69 61 62  that this variab
31550 6c 65 20 62 65 20 73 65 74 20 6f 6e 63 65 0a 2a  le be set once.*
31560 2a 20 61 73 20 70 61 72 74 20 6f 66 20 70 72 6f  * as part of pro
31570 63 65 73 73 20 69 6e 69 74 69 61 6c 69 7a 61 74  cess initializat
31580 69 6f 6e 20 61 6e 64 20 62 65 66 6f 72 65 20 61  ion and before a
31590 6e 79 20 53 51 4c 69 74 65 20 69 6e 74 65 72 66  ny SQLite interf
315a0 61 63 65 0a 2a 2a 20 72 6f 75 74 69 6e 65 73 20  ace.** routines 
315b0 68 61 76 65 20 62 65 65 6e 20 63 61 6c 6c 65 64  have been called
315c0 20 61 6e 64 20 74 68 61 74 20 74 68 69 73 20 76   and that this v
315d0 61 72 69 61 62 6c 65 20 72 65 6d 61 69 6e 20 75  ariable remain u
315e0 6e 63 68 61 6e 67 65 64 0a 2a 2a 20 74 68 65 72  nchanged.** ther
315f0 65 61 66 74 65 72 2e 0a 2a 2a 0a 2a 2a 20 5e 54  eafter..**.** ^T
31600 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
31610 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
31620 20 6d 61 79 20 6d 6f 64 69 66 79 20 74 68 69 73   may modify this
31630 20 76 61 72 69 61 62 6c 65 20 61 6e 64 20 63 61   variable and ca
31640 75 73 65 0a 2a 2a 20 69 74 20 74 6f 20 70 6f 69  use.** it to poi
31650 6e 74 20 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74  nt to memory obt
31660 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
31670 74 65 33 5f 6d 61 6c 6c 6f 63 5d 2e 20 20 5e 46  te3_malloc].  ^F
31680 75 72 74 68 65 72 6d 6f 72 65 2c 0a 2a 2a 20 74  urthermore,.** t
31690 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
316a0 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
316b0 20 61 6c 77 61 79 73 20 61 73 73 75 6d 65 73 20   always assumes 
316c0 74 68 61 74 20 61 6e 79 20 73 74 72 69 6e 67 0a  that any string.
316d0 2a 2a 20 74 68 61 74 20 74 68 69 73 20 76 61 72  ** that this var
316e0 69 61 62 6c 65 20 70 6f 69 6e 74 73 20 74 6f 20  iable points to 
316f0 69 73 20 68 65 6c 64 20 69 6e 20 6d 65 6d 6f 72  is held in memor
31700 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20  y obtained from 
31710 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6d 61 6c  .** [sqlite3_mal
31720 6c 6f 63 5d 20 61 6e 64 20 74 68 65 20 70 72 61  loc] and the pra
31730 67 6d 61 20 6d 61 79 20 61 74 74 65 6d 70 74 20  gma may attempt 
31740 74 6f 20 66 72 65 65 20 74 68 61 74 20 6d 65 6d  to free that mem
31750 6f 72 79 0a 2a 2a 20 75 73 69 6e 67 20 5b 73 71  ory.** using [sq
31760 6c 69 74 65 33 5f 66 72 65 65 5d 2e 0a 2a 2a 20  lite3_free]..** 
31770 48 65 6e 63 65 2c 20 69 66 20 74 68 69 73 20 76  Hence, if this v
31780 61 72 69 61 62 6c 65 20 69 73 20 6d 6f 64 69 66  ariable is modif
31790 69 65 64 20 64 69 72 65 63 74 6c 79 2c 20 65 69  ied directly, ei
317a0 74 68 65 72 20 69 74 20 73 68 6f 75 6c 64 20 62  ther it should b
317b0 65 0a 2a 2a 20 6d 61 64 65 20 4e 55 4c 4c 20 6f  e.** made NULL o
317c0 72 20 6d 61 64 65 20 74 6f 20 70 6f 69 6e 74 20  r made to point 
317d0 74 6f 20 6d 65 6d 6f 72 79 20 6f 62 74 61 69 6e  to memory obtain
317e0 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65 33  ed from [sqlite3
317f0 5f 6d 61 6c 6c 6f 63 5d 0a 2a 2a 20 6f 72 20 65  _malloc].** or e
31800 6c 73 65 20 74 68 65 20 75 73 65 20 6f 66 20 74  lse the use of t
31810 68 65 20 5b 74 65 6d 70 5f 73 74 6f 72 65 5f 64  he [temp_store_d
31820 69 72 65 63 74 6f 72 79 20 70 72 61 67 6d 61 5d  irectory pragma]
31830 20 73 68 6f 75 6c 64 20 62 65 20 61 76 6f 69 64   should be avoid
31840 65 64 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 45 58  ed..*/.SQLITE_EX
31850 54 45 52 4e 20 63 68 61 72 20 2a 73 71 6c 69 74  TERN char *sqlit
31860 65 33 5f 74 65 6d 70 5f 64 69 72 65 63 74 6f 72  e3_temp_director
31870 79 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  y;../*.** CAPI3R
31880 45 46 3a 20 54 65 73 74 20 46 6f 72 20 41 75 74  EF: Test For Aut
31890 6f 2d 43 6f 6d 6d 69 74 20 4d 6f 64 65 0a 2a 2a  o-Commit Mode.**
318a0 20 4b 45 59 57 4f 52 44 53 3a 20 7b 61 75 74 6f   KEYWORDS: {auto
318b0 63 6f 6d 6d 69 74 20 6d 6f 64 65 7d 0a 2a 2a 0a  commit mode}.**.
318c0 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f  ** ^The sqlite3_
318d0 67 65 74 5f 61 75 74 6f 63 6f 6d 6d 69 74 28 29  get_autocommit()
318e0 20 69 6e 74 65 72 66 61 63 65 20 72 65 74 75 72   interface retur
318f0 6e 73 20 6e 6f 6e 2d 7a 65 72 6f 20 6f 72 0a 2a  ns non-zero or.*
31900 2a 20 7a 65 72 6f 20 69 66 20 74 68 65 20 67 69  * zero if the gi
31910 76 65 6e 20 64 61 74 61 62 61 73 65 20 63 6f 6e  ven database con
31920 6e 65 63 74 69 6f 6e 20 69 73 20 6f 72 20 69 73  nection is or is
31930 20 6e 6f 74 20 69 6e 20 61 75 74 6f 63 6f 6d 6d   not in autocomm
31940 69 74 20 6d 6f 64 65 2c 0a 2a 2a 20 72 65 73 70  it mode,.** resp
31950 65 63 74 69 76 65 6c 79 2e 20 20 5e 41 75 74 6f  ectively.  ^Auto
31960 63 6f 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 6f  commit mode is o
31970 6e 20 62 79 20 64 65 66 61 75 6c 74 2e 0a 2a 2a  n by default..**
31980 20 5e 41 75 74 6f 63 6f 6d 6d 69 74 20 6d 6f 64   ^Autocommit mod
31990 65 20 69 73 20 64 69 73 61 62 6c 65 64 20 62 79  e is disabled by
319a0 20 61 20 5b 42 45 47 49 4e 5d 20 73 74 61 74 65   a [BEGIN] state
319b0 6d 65 6e 74 2e 0a 2a 2a 20 5e 41 75 74 6f 63 6f  ment..** ^Autoco
319c0 6d 6d 69 74 20 6d 6f 64 65 20 69 73 20 72 65 2d  mmit mode is re-
319d0 65 6e 61 62 6c 65 64 20 62 79 20 61 20 5b 43 4f  enabled by a [CO
319e0 4d 4d 49 54 5d 20 6f 72 20 5b 52 4f 4c 4c 42 41  MMIT] or [ROLLBA
319f0 43 4b 5d 2e 0a 2a 2a 0a 2a 2a 20 49 66 20 63 65  CK]..**.** If ce
31a00 72 74 61 69 6e 20 6b 69 6e 64 73 20 6f 66 20 65  rtain kinds of e
31a10 72 72 6f 72 73 20 6f 63 63 75 72 20 6f 6e 20 61  rrors occur on a
31a20 20 73 74 61 74 65 6d 65 6e 74 20 77 69 74 68 69   statement withi
31a30 6e 20 61 20 6d 75 6c 74 69 2d 73 74 61 74 65 6d  n a multi-statem
31a40 65 6e 74 0a 2a 2a 20 74 72 61 6e 73 61 63 74 69  ent.** transacti
31a50 6f 6e 20 28 65 72 72 6f 72 73 20 69 6e 63 6c 75  on (errors inclu
31a60 64 69 6e 67 20 5b 53 51 4c 49 54 45 5f 46 55 4c  ding [SQLITE_FUL
31a70 4c 5d 2c 20 5b 53 51 4c 49 54 45 5f 49 4f 45 52  L], [SQLITE_IOER
31a80 52 5d 2c 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 4e  R],.** [SQLITE_N
31a90 4f 4d 45 4d 5d 2c 20 5b 53 51 4c 49 54 45 5f 42  OMEM], [SQLITE_B
31aa0 55 53 59 5d 2c 20 61 6e 64 20 5b 53 51 4c 49 54  USY], and [SQLIT
31ab0 45 5f 49 4e 54 45 52 52 55 50 54 5d 29 20 74 68  E_INTERRUPT]) th
31ac0 65 6e 20 74 68 65 0a 2a 2a 20 74 72 61 6e 73 61  en the.** transa
31ad0 63 74 69 6f 6e 20 6d 69 67 68 74 20 62 65 20 72  ction might be r
31ae0 6f 6c 6c 65 64 20 62 61 63 6b 20 61 75 74 6f 6d  olled back autom
31af0 61 74 69 63 61 6c 6c 79 2e 20 20 54 68 65 20 6f  atically.  The o
31b00 6e 6c 79 20 77 61 79 20 74 6f 0a 2a 2a 20 66 69  nly way to.** fi
31b10 6e 64 20 6f 75 74 20 77 68 65 74 68 65 72 20 53  nd out whether S
31b20 51 4c 69 74 65 20 61 75 74 6f 6d 61 74 69 63 61  QLite automatica
31b30 6c 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20  lly rolled back 
31b40 74 68 65 20 74 72 61 6e 73 61 63 74 69 6f 6e 20  the transaction 
31b50 61 66 74 65 72 0a 2a 2a 20 61 6e 20 65 72 72 6f  after.** an erro
31b60 72 20 69 73 20 74 6f 20 75 73 65 20 74 68 69 73  r is to use this
31b70 20 66 75 6e 63 74 69 6f 6e 2e 0a 2a 2a 0a 2a 2a   function..**.**
31b80 20 49 66 20 61 6e 6f 74 68 65 72 20 74 68 72 65   If another thre
31b90 61 64 20 63 68 61 6e 67 65 73 20 74 68 65 20 61  ad changes the a
31ba0 75 74 6f 63 6f 6d 6d 69 74 20 73 74 61 74 75 73  utocommit status
31bb0 20 6f 66 20 74 68 65 20 64 61 74 61 62 61 73 65   of the database
31bc0 0a 2a 2a 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 77  .** connection w
31bd0 68 69 6c 65 20 74 68 69 73 20 72 6f 75 74 69 6e  hile this routin
31be0 65 20 69 73 20 72 75 6e 6e 69 6e 67 2c 20 74 68  e is running, th
31bf0 65 6e 20 74 68 65 20 72 65 74 75 72 6e 20 76 61  en the return va
31c00 6c 75 65 0a 2a 2a 20 69 73 20 75 6e 64 65 66 69  lue.** is undefi
31c10 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  ned..*/.int sqli
31c20 74 65 33 5f 67 65 74 5f 61 75 74 6f 63 6f 6d 6d  te3_get_autocomm
31c30 69 74 28 73 71 6c 69 74 65 33 2a 29 3b 0a 0a 2f  it(sqlite3*);../
31c40 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46  *.** CAPI3REF: F
31c50 69 6e 64 20 54 68 65 20 44 61 74 61 62 61 73 65  ind The Database
31c60 20 48 61 6e 64 6c 65 20 4f 66 20 41 20 50 72 65   Handle Of A Pre
31c70 70 61 72 65 64 20 53 74 61 74 65 6d 65 6e 74 0a  pared Statement.
31c80 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69 74  **.** ^The sqlit
31c90 65 33 5f 64 62 5f 68 61 6e 64 6c 65 20 69 6e 74  e3_db_handle int
31ca0 65 72 66 61 63 65 20 72 65 74 75 72 6e 73 20 74  erface returns t
31cb0 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
31cc0 6e 65 63 74 69 6f 6e 5d 20 68 61 6e 64 6c 65 0a  nection] handle.
31cd0 2a 2a 20 74 6f 20 77 68 69 63 68 20 61 20 5b 70  ** to which a [p
31ce0 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31cf0 74 5d 20 62 65 6c 6f 6e 67 73 2e 20 20 5e 54 68  t] belongs.  ^Th
31d00 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  e [database conn
31d10 65 63 74 69 6f 6e 5d 0a 2a 2a 20 72 65 74 75 72  ection].** retur
31d20 6e 65 64 20 62 79 20 73 71 6c 69 74 65 33 5f 64  ned by sqlite3_d
31d30 62 5f 68 61 6e 64 6c 65 20 69 73 20 74 68 65 20  b_handle is the 
31d40 73 61 6d 65 20 5b 64 61 74 61 62 61 73 65 20 63  same [database c
31d50 6f 6e 6e 65 63 74 69 6f 6e 5d 0a 2a 2a 20 74 68  onnection].** th
31d60 61 74 20 77 61 73 20 74 68 65 20 66 69 72 73 74  at was the first
31d70 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20 74 6f 20   argument.** to 
31d80 74 68 65 20 5b 73 71 6c 69 74 65 33 5f 70 72 65  the [sqlite3_pre
31d90 70 61 72 65 5f 76 32 28 29 5d 20 63 61 6c 6c 20  pare_v2()] call 
31da0 28 6f 72 20 69 74 73 20 76 61 72 69 61 6e 74 73  (or its variants
31db0 29 20 74 68 61 74 20 77 61 73 20 75 73 65 64 20  ) that was used 
31dc0 74 6f 0a 2a 2a 20 63 72 65 61 74 65 20 74 68 65  to.** create the
31dd0 20 73 74 61 74 65 6d 65 6e 74 20 69 6e 20 74 68   statement in th
31de0 65 20 66 69 72 73 74 20 70 6c 61 63 65 2e 0a 2a  e first place..*
31df0 2f 0a 73 71 6c 69 74 65 33 20 2a 73 71 6c 69 74  /.sqlite3 *sqlit
31e00 65 33 5f 64 62 5f 68 61 6e 64 6c 65 28 73 71 6c  e3_db_handle(sql
31e10 69 74 65 33 5f 73 74 6d 74 2a 29 3b 0a 0a 2f 2a  ite3_stmt*);../*
31e20 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 46 69  .** CAPI3REF: Fi
31e30 6e 64 20 74 68 65 20 6e 65 78 74 20 70 72 65 70  nd the next prep
31e40 61 72 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a  ared statement.*
31e50 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74 65 72  *.** ^This inter
31e60 66 61 63 65 20 72 65 74 75 72 6e 73 20 61 20 70  face returns a p
31e70 6f 69 6e 74 65 72 20 74 6f 20 74 68 65 20 6e 65  ointer to the ne
31e80 78 74 20 5b 70 72 65 70 61 72 65 64 20 73 74 61  xt [prepared sta
31e90 74 65 6d 65 6e 74 5d 20 61 66 74 65 72 0a 2a 2a  tement] after.**
31ea0 20 70 53 74 6d 74 20 61 73 73 6f 63 69 61 74 65   pStmt associate
31eb0 64 20 77 69 74 68 20 74 68 65 20 5b 64 61 74 61  d with the [data
31ec0 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
31ed0 20 70 44 62 2e 20 20 5e 49 66 20 70 53 74 6d 74   pDb.  ^If pStmt
31ee0 20 69 73 20 4e 55 4c 4c 0a 2a 2a 20 74 68 65 6e   is NULL.** then
31ef0 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
31f00 72 65 74 75 72 6e 73 20 61 20 70 6f 69 6e 74 65  returns a pointe
31f10 72 20 74 6f 20 74 68 65 20 66 69 72 73 74 20 70  r to the first p
31f20 72 65 70 61 72 65 64 20 73 74 61 74 65 6d 65 6e  repared statemen
31f30 74 0a 2a 2a 20 61 73 73 6f 63 69 61 74 65 64 20  t.** associated 
31f40 77 69 74 68 20 74 68 65 20 64 61 74 61 62 61 73  with the databas
31f50 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 70 44 62  e connection pDb
31f60 2e 20 20 5e 49 66 20 6e 6f 20 70 72 65 70 61 72  .  ^If no prepar
31f70 65 64 20 73 74 61 74 65 6d 65 6e 74 0a 2a 2a 20  ed statement.** 
31f80 73 61 74 69 73 66 69 65 73 20 74 68 65 20 63 6f  satisfies the co
31f90 6e 64 69 74 69 6f 6e 73 20 6f 66 20 74 68 69 73  nditions of this
31fa0 20 72 6f 75 74 69 6e 65 2c 20 69 74 20 72 65 74   routine, it ret
31fb0 75 72 6e 73 20 4e 55 4c 4c 2e 0a 2a 2a 0a 2a 2a  urns NULL..**.**
31fc0 20 54 68 65 20 5b 64 61 74 61 62 61 73 65 20 63   The [database c
31fd0 6f 6e 6e 65 63 74 69 6f 6e 5d 20 70 6f 69 6e 74  onnection] point
31fe0 65 72 20 44 20 69 6e 20 61 20 63 61 6c 6c 20 74  er D in a call t
31ff0 6f 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 6e 65  o.** [sqlite3_ne
32000 78 74 5f 73 74 6d 74 28 44 2c 53 29 5d 20 6d 75  xt_stmt(D,S)] mu
32010 73 74 20 72 65 66 65 72 20 74 6f 20 61 6e 20 6f  st refer to an o
32020 70 65 6e 20 64 61 74 61 62 61 73 65 0a 2a 2a 20  pen database.** 
32030 63 6f 6e 6e 65 63 74 69 6f 6e 20 61 6e 64 20 69  connection and i
32040 6e 20 70 61 72 74 69 63 75 6c 61 72 20 6d 75 73  n particular mus
32050 74 20 6e 6f 74 20 62 65 20 61 20 4e 55 4c 4c 20  t not be a NULL 
32060 70 6f 69 6e 74 65 72 2e 0a 2a 2f 0a 73 71 6c 69  pointer..*/.sqli
32070 74 65 33 5f 73 74 6d 74 20 2a 73 71 6c 69 74 65  te3_stmt *sqlite
32080 33 5f 6e 65 78 74 5f 73 74 6d 74 28 73 71 6c 69  3_next_stmt(sqli
32090 74 65 33 20 2a 70 44 62 2c 20 73 71 6c 69 74 65  te3 *pDb, sqlite
320a0 33 5f 73 74 6d 74 20 2a 70 53 74 6d 74 29 3b 0a  3_stmt *pStmt);.
320b0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
320c0 20 43 6f 6d 6d 69 74 20 41 6e 64 20 52 6f 6c 6c   Commit And Roll
320d0 62 61 63 6b 20 4e 6f 74 69 66 69 63 61 74 69 6f  back Notificatio
320e0 6e 20 43 61 6c 6c 62 61 63 6b 73 0a 2a 2a 0a 2a  n Callbacks.**.*
320f0 2a 20 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 63  * ^The sqlite3_c
32100 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 20 69 6e 74  ommit_hook() int
32110 65 72 66 61 63 65 20 72 65 67 69 73 74 65 72 73  erface registers
32120 20 61 20 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66   a callback.** f
32130 75 6e 63 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e  unction to be in
32140 76 6f 6b 65 64 20 77 68 65 6e 65 76 65 72 20 61  voked whenever a
32150 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
32160 5b 43 4f 4d 4d 49 54 20 7c 20 63 6f 6d 6d 69 74  [COMMIT | commit
32170 74 65 64 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63 61  ted]..** ^Any ca
32180 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61 20  llback set by a 
32190 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74 6f  previous call to
321a0 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74 5f   sqlite3_commit_
321b0 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72 20 74 68  hook().** for th
321c0 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
321d0 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
321e0 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20 5e 54 68  erridden..** ^Th
321f0 65 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  e sqlite3_rollba
32200 63 6b 5f 68 6f 6f 6b 28 29 20 69 6e 74 65 72 66  ck_hook() interf
32210 61 63 65 20 72 65 67 69 73 74 65 72 73 20 61 20  ace registers a 
32220 63 61 6c 6c 62 61 63 6b 0a 2a 2a 20 66 75 6e 63  callback.** func
32230 74 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b  tion to be invok
32240 65 64 20 77 68 65 6e 65 76 65 72 20 61 20 74 72  ed whenever a tr
32250 61 6e 73 61 63 74 69 6f 6e 20 69 73 20 5b 52 4f  ansaction is [RO
32260 4c 4c 42 41 43 4b 20 7c 20 72 6f 6c 6c 65 64 20  LLBACK | rolled 
32270 62 61 63 6b 5d 2e 0a 2a 2a 20 5e 41 6e 79 20 63  back]..** ^Any c
32280 61 6c 6c 62 61 63 6b 20 73 65 74 20 62 79 20 61  allback set by a
32290 20 70 72 65 76 69 6f 75 73 20 63 61 6c 6c 20 74   previous call t
322a0 6f 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61  o sqlite3_rollba
322b0 63 6b 5f 68 6f 6f 6b 28 29 0a 2a 2a 20 66 6f 72  ck_hook().** for
322c0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
322d0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73  se connection is
322e0 20 6f 76 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 20   overridden..** 
322f0 5e 54 68 65 20 70 41 72 67 20 61 72 67 75 6d 65  ^The pArg argume
32300 6e 74 20 69 73 20 70 61 73 73 65 64 20 74 68 72  nt is passed thr
32310 6f 75 67 68 20 74 6f 20 74 68 65 20 63 61 6c 6c  ough to the call
32320 62 61 63 6b 2e 0a 2a 2a 20 5e 49 66 20 74 68 65  back..** ^If the
32330 20 63 61 6c 6c 62 61 63 6b 20 6f 6e 20 61 20 63   callback on a c
32340 6f 6d 6d 69 74 20 68 6f 6f 6b 20 66 75 6e 63 74  ommit hook funct
32350 69 6f 6e 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d  ion returns non-
32360 7a 65 72 6f 2c 0a 2a 2a 20 74 68 65 6e 20 74 68  zero,.** then th
32370 65 20 63 6f 6d 6d 69 74 20 69 73 20 63 6f 6e 76  e commit is conv
32380 65 72 74 65 64 20 69 6e 74 6f 20 61 20 72 6f 6c  erted into a rol
32390 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68  lback..**.** ^Th
323a0 65 20 73 71 6c 69 74 65 33 5f 63 6f 6d 6d 69 74  e sqlite3_commit
323b0 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 61 6e 64  _hook(D,C,P) and
323c0 20 73 71 6c 69 74 65 33 5f 72 6f 6c 6c 62 61 63   sqlite3_rollbac
323d0 6b 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20 66 75  k_hook(D,C,P) fu
323e0 6e 63 74 69 6f 6e 73 0a 2a 2a 20 72 65 74 75 72  nctions.** retur
323f0 6e 20 74 68 65 20 50 20 61 72 67 75 6d 65 6e 74  n the P argument
32400 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76 69 6f   from the previo
32410 75 73 20 63 61 6c 6c 20 6f 66 20 74 68 65 20 73  us call of the s
32420 61 6d 65 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20  ame function.** 
32430 6f 6e 20 74 68 65 20 73 61 6d 65 20 5b 64 61 74  on the same [dat
32440 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e  abase connection
32450 5d 20 44 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72  ] D, or NULL for
32460 0a 2a 2a 20 74 68 65 20 66 69 72 73 74 20 63 61  .** the first ca
32470 6c 6c 20 66 6f 72 20 65 61 63 68 20 66 75 6e 63  ll for each func
32480 74 69 6f 6e 20 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a  tion on D..**.**
32490 20 54 68 65 20 63 61 6c 6c 62 61 63 6b 20 69 6d   The callback im
324a0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73  plementation mus
324b0 74 20 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e  t not do anythin
324c0 67 20 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69  g that will modi
324d0 66 79 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61  fy.** the databa
324e0 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68  se connection th
324f0 61 74 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 63  at invoked the c
32500 61 6c 6c 62 61 63 6b 2e 20 20 41 6e 79 20 61 63  allback.  Any ac
32510 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64 69  tions.** to modi
32520 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  fy the database 
32530 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74 20  connection must 
32540 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74 69  be deferred unti
32550 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20 63  l after the.** c
32560 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68 65  ompletion of the
32570 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
32580 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69 67  ] call that trig
32590 67 65 72 65 64 20 74 68 65 20 63 6f 6d 6d 69 74  gered the commit
325a0 0a 2a 2a 20 6f 72 20 72 6f 6c 6c 62 61 63 6b 20  .** or rollback 
325b0 68 6f 6f 6b 20 69 6e 20 74 68 65 20 66 69 72 73  hook in the firs
325c0 74 20 70 6c 61 63 65 2e 0a 2a 2a 20 4e 6f 74 65  t place..** Note
325d0 20 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70   that [sqlite3_p
325e0 72 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64  repare_v2()] and
325f0 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29   [sqlite3_step()
32600 5d 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68  ] both modify th
32610 65 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  eir.** database 
32620 63 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20  connections for 
32630 74 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22  the meaning of "
32640 6d 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20  modify" in this 
32650 70 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a  paragraph..**.**
32660 20 5e 52 65 67 69 73 74 65 72 69 6e 67 20 61 20   ^Registering a 
32670 4e 55 4c 4c 20 66 75 6e 63 74 69 6f 6e 20 64 69  NULL function di
32680 73 61 62 6c 65 73 20 74 68 65 20 63 61 6c 6c 62  sables the callb
32690 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20 5e 57 68 65 6e  ack..**.** ^When
326a0 20 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b   the commit hook
326b0 20 63 61 6c 6c 62 61 63 6b 20 72 6f 75 74 69 6e   callback routin
326c0 65 20 72 65 74 75 72 6e 73 20 7a 65 72 6f 2c 20  e returns zero, 
326d0 74 68 65 20 5b 43 4f 4d 4d 49 54 5d 0a 2a 2a 20  the [COMMIT].** 
326e0 6f 70 65 72 61 74 69 6f 6e 20 69 73 20 61 6c 6c  operation is all
326f0 6f 77 65 64 20 74 6f 20 63 6f 6e 74 69 6e 75 65  owed to continue
32700 20 6e 6f 72 6d 61 6c 6c 79 2e 20 20 5e 49 66 20   normally.  ^If 
32710 74 68 65 20 63 6f 6d 6d 69 74 20 68 6f 6f 6b 0a  the commit hook.
32720 2a 2a 20 72 65 74 75 72 6e 73 20 6e 6f 6e 2d 7a  ** returns non-z
32730 65 72 6f 2c 20 74 68 65 6e 20 74 68 65 20 5b 43  ero, then the [C
32740 4f 4d 4d 49 54 5d 20 69 73 20 63 6f 6e 76 65 72  OMMIT] is conver
32750 74 65 64 20 69 6e 74 6f 20 61 20 5b 52 4f 4c 4c  ted into a [ROLL
32760 42 41 43 4b 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72  BACK]..** ^The r
32770 6f 6c 6c 62 61 63 6b 20 68 6f 6f 6b 20 69 73 20  ollback hook is 
32780 69 6e 76 6f 6b 65 64 20 6f 6e 20 61 20 72 6f 6c  invoked on a rol
32790 6c 62 61 63 6b 20 74 68 61 74 20 72 65 73 75 6c  lback that resul
327a0 74 73 20 66 72 6f 6d 20 61 20 63 6f 6d 6d 69 74  ts from a commit
327b0 0a 2a 2a 20 68 6f 6f 6b 20 72 65 74 75 72 6e 69  .** hook returni
327c0 6e 67 20 6e 6f 6e 2d 7a 65 72 6f 2c 20 6a 75 73  ng non-zero, jus
327d0 74 20 61 73 20 69 74 20 77 6f 75 6c 64 20 62 65  t as it would be
327e0 20 77 69 74 68 20 61 6e 79 20 6f 74 68 65 72 20   with any other 
327f0 72 6f 6c 6c 62 61 63 6b 2e 0a 2a 2a 0a 2a 2a 20  rollback..**.** 
32800 5e 46 6f 72 20 74 68 65 20 70 75 72 70 6f 73 65  ^For the purpose
32810 73 20 6f 66 20 74 68 69 73 20 41 50 49 2c 20 61  s of this API, a
32820 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69 73 20   transaction is 
32830 73 61 69 64 20 74 6f 20 68 61 76 65 20 62 65 65  said to have bee
32840 6e 0a 2a 2a 20 72 6f 6c 6c 65 64 20 62 61 63 6b  n.** rolled back
32850 20 69 66 20 61 6e 20 65 78 70 6c 69 63 69 74 20   if an explicit 
32860 22 52 4f 4c 4c 42 41 43 4b 22 20 73 74 61 74 65  "ROLLBACK" state
32870 6d 65 6e 74 20 69 73 20 65 78 65 63 75 74 65 64  ment is executed
32880 2c 20 6f 72 0a 2a 2a 20 61 6e 20 65 72 72 6f 72  , or.** an error
32890 20 6f 72 20 63 6f 6e 73 74 72 61 69 6e 74 20 63   or constraint c
328a0 61 75 73 65 73 20 61 6e 20 69 6d 70 6c 69 63 69  auses an implici
328b0 74 20 72 6f 6c 6c 62 61 63 6b 20 74 6f 20 6f 63  t rollback to oc
328c0 63 75 72 2e 0a 2a 2a 20 5e 54 68 65 20 72 6f 6c  cur..** ^The rol
328d0 6c 62 61 63 6b 20 63 61 6c 6c 62 61 63 6b 20 69  lback callback i
328e0 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 69 66  s not invoked if
328f0 20 61 20 74 72 61 6e 73 61 63 74 69 6f 6e 20 69   a transaction i
32900 73 0a 2a 2a 20 61 75 74 6f 6d 61 74 69 63 61 6c  s.** automatical
32910 6c 79 20 72 6f 6c 6c 65 64 20 62 61 63 6b 20 62  ly rolled back b
32920 65 63 61 75 73 65 20 74 68 65 20 64 61 74 61 62  ecause the datab
32930 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 69  ase connection i
32940 73 20 63 6c 6f 73 65 64 2e 0a 2a 2a 0a 2a 2a 20  s closed..**.** 
32950 53 65 65 20 61 6c 73 6f 20 74 68 65 20 5b 73 71  See also the [sq
32960 6c 69 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f  lite3_update_hoo
32970 6b 28 29 5d 20 69 6e 74 65 72 66 61 63 65 2e 0a  k()] interface..
32980 2a 2f 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33  */.void *sqlite3
32990 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 73 71 6c  _commit_hook(sql
329a0 69 74 65 33 2a 2c 20 69 6e 74 28 2a 29 28 76 6f  ite3*, int(*)(vo
329b0 69 64 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 76 6f  id*), void*);.vo
329c0 69 64 20 2a 73 71 6c 69 74 65 33 5f 72 6f 6c 6c  id *sqlite3_roll
329d0 62 61 63 6b 5f 68 6f 6f 6b 28 73 71 6c 69 74 65  back_hook(sqlite
329e0 33 2a 2c 20 76 6f 69 64 28 2a 29 28 76 6f 69 64  3*, void(*)(void
329f0 20 2a 29 2c 20 76 6f 69 64 2a 29 3b 0a 0a 2f 2a   *), void*);../*
32a00 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 44 61  .** CAPI3REF: Da
32a10 74 61 20 43 68 61 6e 67 65 20 4e 6f 74 69 66 69  ta Change Notifi
32a20 63 61 74 69 6f 6e 20 43 61 6c 6c 62 61 63 6b 73  cation Callbacks
32a30 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71 6c 69  .**.** ^The sqli
32a40 74 65 33 5f 75 70 64 61 74 65 5f 68 6f 6f 6b 28  te3_update_hook(
32a50 29 20 69 6e 74 65 72 66 61 63 65 20 72 65 67 69  ) interface regi
32a60 73 74 65 72 73 20 61 20 63 61 6c 6c 62 61 63 6b  sters a callback
32a70 20 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 77 69 74   function.** wit
32a80 68 20 74 68 65 20 5b 64 61 74 61 62 61 73 65 20  h the [database 
32a90 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 69 64 65 6e  connection] iden
32aa0 74 69 66 69 65 64 20 62 79 20 74 68 65 20 66 69  tified by the fi
32ab0 72 73 74 20 61 72 67 75 6d 65 6e 74 0a 2a 2a 20  rst argument.** 
32ac0 74 6f 20 62 65 20 69 6e 76 6f 6b 65 64 20 77 68  to be invoked wh
32ad0 65 6e 65 76 65 72 20 61 20 72 6f 77 20 69 73 20  enever a row is 
32ae0 75 70 64 61 74 65 64 2c 20 69 6e 73 65 72 74 65  updated, inserte
32af0 64 20 6f 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a  d or deleted..**
32b00 20 5e 41 6e 79 20 63 61 6c 6c 62 61 63 6b 20 73   ^Any callback s
32b10 65 74 20 62 79 20 61 20 70 72 65 76 69 6f 75 73  et by a previous
32b20 20 63 61 6c 6c 20 74 6f 20 74 68 69 73 20 66 75   call to this fu
32b30 6e 63 74 69 6f 6e 0a 2a 2a 20 66 6f 72 20 74 68  nction.** for th
32b40 65 20 73 61 6d 65 20 64 61 74 61 62 61 73 65 20  e same database 
32b50 63 6f 6e 6e 65 63 74 69 6f 6e 20 69 73 20 6f 76  connection is ov
32b60 65 72 72 69 64 64 65 6e 2e 0a 2a 2a 0a 2a 2a 20  erridden..**.** 
32b70 5e 54 68 65 20 73 65 63 6f 6e 64 20 61 72 67 75  ^The second argu
32b80 6d 65 6e 74 20 69 73 20 61 20 70 6f 69 6e 74 65  ment is a pointe
32b90 72 20 74 6f 20 74 68 65 20 66 75 6e 63 74 69 6f  r to the functio
32ba0 6e 20 74 6f 20 69 6e 76 6f 6b 65 20 77 68 65 6e  n to invoke when
32bb0 20 61 0a 2a 2a 20 72 6f 77 20 69 73 20 75 70 64   a.** row is upd
32bc0 61 74 65 64 2c 20 69 6e 73 65 72 74 65 64 20 6f  ated, inserted o
32bd0 72 20 64 65 6c 65 74 65 64 2e 0a 2a 2a 20 5e 54  r deleted..** ^T
32be0 68 65 20 66 69 72 73 74 20 61 72 67 75 6d 65 6e  he first argumen
32bf0 74 20 74 6f 20 74 68 65 20 63 61 6c 6c 62 61 63  t to the callbac
32c00 6b 20 69 73 20 61 20 63 6f 70 79 20 6f 66 20 74  k is a copy of t
32c10 68 65 20 74 68 69 72 64 20 61 72 67 75 6d 65 6e  he third argumen
32c20 74 0a 2a 2a 20 74 6f 20 73 71 6c 69 74 65 33 5f  t.** to sqlite3_
32c30 75 70 64 61 74 65 5f 68 6f 6f 6b 28 29 2e 0a 2a  update_hook()..*
32c40 2a 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 63 61  * ^The second ca
32c50 6c 6c 62 61 63 6b 20 61 72 67 75 6d 65 6e 74 20  llback argument 
32c60 69 73 20 6f 6e 65 20 6f 66 20 5b 53 51 4c 49 54  is one of [SQLIT
32c70 45 5f 49 4e 53 45 52 54 5d 2c 20 5b 53 51 4c 49  E_INSERT], [SQLI
32c80 54 45 5f 44 45 4c 45 54 45 5d 2c 0a 2a 2a 20 6f  TE_DELETE],.** o
32c90 72 20 5b 53 51 4c 49 54 45 5f 55 50 44 41 54 45  r [SQLITE_UPDATE
32ca0 5d 2c 20 64 65 70 65 6e 64 69 6e 67 20 6f 6e 20  ], depending on 
32cb0 74 68 65 20 6f 70 65 72 61 74 69 6f 6e 20 74 68  the operation th
32cc0 61 74 20 63 61 75 73 65 64 20 74 68 65 20 63 61  at caused the ca
32cd0 6c 6c 62 61 63 6b 0a 2a 2a 20 74 6f 20 62 65 20  llback.** to be 
32ce0 69 6e 76 6f 6b 65 64 2e 0a 2a 2a 20 5e 54 68 65  invoked..** ^The
32cf0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
32d00 68 20 61 72 67 75 6d 65 6e 74 73 20 74 6f 20 74  h arguments to t
32d10 68 65 20 63 61 6c 6c 62 61 63 6b 20 63 6f 6e 74  he callback cont
32d20 61 69 6e 20 70 6f 69 6e 74 65 72 73 20 74 6f 20  ain pointers to 
32d30 74 68 65 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  the.** database 
32d40 61 6e 64 20 74 61 62 6c 65 20 6e 61 6d 65 20 63  and table name c
32d50 6f 6e 74 61 69 6e 69 6e 67 20 74 68 65 20 61 66  ontaining the af
32d60 66 65 63 74 65 64 20 72 6f 77 2e 0a 2a 2a 20 5e  fected row..** ^
32d70 54 68 65 20 66 69 6e 61 6c 20 63 61 6c 6c 62 61  The final callba
32d80 63 6b 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ck parameter is 
32d90 74 68 65 20 5b 72 6f 77 69 64 5d 20 6f 66 20 74  the [rowid] of t
32da0 68 65 20 72 6f 77 2e 0a 2a 2a 20 5e 49 6e 20 74  he row..** ^In t
32db0 68 65 20 63 61 73 65 20 6f 66 20 61 6e 20 75 70  he case of an up
32dc0 64 61 74 65 2c 20 74 68 69 73 20 69 73 20 74 68  date, this is th
32dd0 65 20 5b 72 6f 77 69 64 5d 20 61 66 74 65 72 20  e [rowid] after 
32de0 74 68 65 20 75 70 64 61 74 65 20 74 61 6b 65 73  the update takes
32df0 20 70 6c 61 63 65 2e 0a 2a 2a 0a 2a 2a 20 5e 28   place..**.** ^(
32e00 54 68 65 20 75 70 64 61 74 65 20 68 6f 6f 6b 20  The update hook 
32e10 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
32e20 68 65 6e 20 69 6e 74 65 72 6e 61 6c 20 73 79 73  hen internal sys
32e30 74 65 6d 20 74 61 62 6c 65 73 20 61 72 65 0a 2a  tem tables are.*
32e40 2a 20 6d 6f 64 69 66 69 65 64 20 28 69 2e 65 2e  * modified (i.e.
32e50 20 73 71 6c 69 74 65 5f 6d 61 73 74 65 72 20 61   sqlite_master a
32e60 6e 64 20 73 71 6c 69 74 65 5f 73 65 71 75 65 6e  nd sqlite_sequen
32e70 63 65 29 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 49 6e  ce).)^.**.** ^In
32e80 20 74 68 65 20 63 75 72 72 65 6e 74 20 69 6d 70   the current imp
32e90 6c 65 6d 65 6e 74 61 74 69 6f 6e 2c 20 74 68 65  lementation, the
32ea0 20 75 70 64 61 74 65 20 68 6f 6f 6b 0a 2a 2a 20   update hook.** 
32eb0 69 73 20 6e 6f 74 20 69 6e 76 6f 6b 65 64 20 77  is not invoked w
32ec0 68 65 6e 20 64 75 70 6c 69 63 61 74 69 6f 6e 20  hen duplication 
32ed0 72 6f 77 73 20 61 72 65 20 64 65 6c 65 74 65 64  rows are deleted
32ee0 20 62 65 63 61 75 73 65 20 6f 66 20 61 6e 0a 2a   because of an.*
32ef0 2a 20 5b 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 7c  * [ON CONFLICT |
32f00 20 4f 4e 20 43 4f 4e 46 4c 49 43 54 20 52 45 50   ON CONFLICT REP
32f10 4c 41 43 45 5d 20 63 6c 61 75 73 65 2e 20 20 5e  LACE] clause.  ^
32f20 4e 6f 72 20 69 73 20 74 68 65 20 75 70 64 61 74  Nor is the updat
32f30 65 20 68 6f 6f 6b 0a 2a 2a 20 69 6e 76 6f 6b 65  e hook.** invoke
32f40 64 20 77 68 65 6e 20 72 6f 77 73 20 61 72 65 20  d when rows are 
32f50 64 65 6c 65 74 65 64 20 75 73 69 6e 67 20 74 68  deleted using th
32f60 65 20 5b 74 72 75 6e 63 61 74 65 20 6f 70 74 69  e [truncate opti
32f70 6d 69 7a 61 74 69 6f 6e 5d 2e 0a 2a 2a 20 54 68  mization]..** Th
32f80 65 20 65 78 63 65 70 74 69 6f 6e 73 20 64 65 66  e exceptions def
32f90 69 6e 65 64 20 69 6e 20 74 68 69 73 20 70 61 72  ined in this par
32fa0 61 67 72 61 70 68 20 6d 69 67 68 74 20 63 68 61  agraph might cha
32fb0 6e 67 65 20 69 6e 20 61 20 66 75 74 75 72 65 0a  nge in a future.
32fc0 2a 2a 20 72 65 6c 65 61 73 65 20 6f 66 20 53 51  ** release of SQ
32fd0 4c 69 74 65 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20  Lite..**.** The 
32fe0 75 70 64 61 74 65 20 68 6f 6f 6b 20 69 6d 70 6c  update hook impl
32ff0 65 6d 65 6e 74 61 74 69 6f 6e 20 6d 75 73 74 20  ementation must 
33000 6e 6f 74 20 64 6f 20 61 6e 79 74 68 69 6e 67 20  not do anything 
33010 74 68 61 74 20 77 69 6c 6c 20 6d 6f 64 69 66 79  that will modify
33020 0a 2a 2a 20 74 68 65 20 64 61 74 61 62 61 73 65  .** the database
33030 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 68 61 74   connection that
33040 20 69 6e 76 6f 6b 65 64 20 74 68 65 20 75 70 64   invoked the upd
33050 61 74 65 20 68 6f 6f 6b 2e 20 20 41 6e 79 20 61  ate hook.  Any a
33060 63 74 69 6f 6e 73 0a 2a 2a 20 74 6f 20 6d 6f 64  ctions.** to mod
33070 69 66 79 20 74 68 65 20 64 61 74 61 62 61 73 65  ify the database
33080 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 6d 75 73 74   connection must
33090 20 62 65 20 64 65 66 65 72 72 65 64 20 75 6e 74   be deferred unt
330a0 69 6c 20 61 66 74 65 72 20 74 68 65 0a 2a 2a 20  il after the.** 
330b0 63 6f 6d 70 6c 65 74 69 6f 6e 20 6f 66 20 74 68  completion of th
330c0 65 20 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28  e [sqlite3_step(
330d0 29 5d 20 63 61 6c 6c 20 74 68 61 74 20 74 72 69  )] call that tri
330e0 67 67 65 72 65 64 20 74 68 65 20 75 70 64 61 74  ggered the updat
330f0 65 20 68 6f 6f 6b 2e 0a 2a 2a 20 4e 6f 74 65 20  e hook..** Note 
33100 74 68 61 74 20 5b 73 71 6c 69 74 65 33 5f 70 72  that [sqlite3_pr
33110 65 70 61 72 65 5f 76 32 28 29 5d 20 61 6e 64 20  epare_v2()] and 
33120 5b 73 71 6c 69 74 65 33 5f 73 74 65 70 28 29 5d  [sqlite3_step()]
33130 20 62 6f 74 68 20 6d 6f 64 69 66 79 20 74 68 65   both modify the
33140 69 72 0a 2a 2a 20 64 61 74 61 62 61 73 65 20 63  ir.** database c
33150 6f 6e 6e 65 63 74 69 6f 6e 73 20 66 6f 72 20 74  onnections for t
33160 68 65 20 6d 65 61 6e 69 6e 67 20 6f 66 20 22 6d  he meaning of "m
33170 6f 64 69 66 79 22 20 69 6e 20 74 68 69 73 20 70  odify" in this p
33180 61 72 61 67 72 61 70 68 2e 0a 2a 2a 0a 2a 2a 20  aragraph..**.** 
33190 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 75 70 64  ^The sqlite3_upd
331a0 61 74 65 5f 68 6f 6f 6b 28 44 2c 43 2c 50 29 20  ate_hook(D,C,P) 
331b0 66 75 6e 63 74 69 6f 6e 0a 2a 2a 20 72 65 74 75  function.** retu
331c0 72 6e 73 20 74 68 65 20 50 20 61 72 67 75 6d 65  rns the P argume
331d0 6e 74 20 66 72 6f 6d 20 74 68 65 20 70 72 65 76  nt from the prev
331e0 69 6f 75 73 20 63 61 6c 6c 0a 2a 2a 20 6f 6e 20  ious call.** on 
331f0 74 68 65 20 73 61 6d 65 20 5b 64 61 74 61 62 61  the same [databa
33200 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d 20 44  se connection] D
33210 2c 20 6f 72 20 4e 55 4c 4c 20 66 6f 72 0a 2a 2a  , or NULL for.**
33220 20 74 68 65 20 66 69 72 73 74 20 63 61 6c 6c 20   the first call 
33230 6f 6e 20 44 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  on D..**.** See 
33240 61 6c 73 6f 20 74 68 65 20 5b 73 71 6c 69 74 65  also the [sqlite
33250 33 5f 63 6f 6d 6d 69 74 5f 68 6f 6f 6b 28 29 5d  3_commit_hook()]
33260 20 61 6e 64 20 5b 73 71 6c 69 74 65 33 5f 72 6f   and [sqlite3_ro
33270 6c 6c 62 61 63 6b 5f 68 6f 6f 6b 28 29 5d 0a 2a  llback_hook()].*
33280 2a 20 69 6e 74 65 72 66 61 63 65 73 2e 0a 2a 2f  * interfaces..*/
33290 0a 76 6f 69 64 20 2a 73 71 6c 69 74 65 33 5f 75  .void *sqlite3_u
332a0 70 64 61 74 65 5f 68 6f 6f 6b 28 0a 20 20 73 71  pdate_hook(.  sq
332b0 6c 69 74 65 33 2a 2c 20 0a 20 20 76 6f 69 64 28  lite3*, .  void(
332c0 2a 29 28 76 6f 69 64 20 2a 2c 69 6e 74 20 2c 63  *)(void *,int ,c
332d0 68 61 72 20 63 6f 6e 73 74 20 2a 2c 63 68 61 72  har const *,char
332e0 20 63 6f 6e 73 74 20 2a 2c 73 71 6c 69 74 65 33   const *,sqlite3
332f0 5f 69 6e 74 36 34 29 2c 0a 20 20 76 6f 69 64 2a  _int64),.  void*
33300 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33  .);../*.** CAPI3
33310 52 45 46 3a 20 45 6e 61 62 6c 65 20 4f 72 20 44  REF: Enable Or D
33320 69 73 61 62 6c 65 20 53 68 61 72 65 64 20 50 61  isable Shared Pa
33330 67 65 72 20 43 61 63 68 65 0a 2a 2a 20 4b 45 59  ger Cache.** KEY
33340 57 4f 52 44 53 3a 20 7b 73 68 61 72 65 64 20 63  WORDS: {shared c
33350 61 63 68 65 7d 0a 2a 2a 0a 2a 2a 20 5e 28 54 68  ache}.**.** ^(Th
33360 69 73 20 72 6f 75 74 69 6e 65 20 65 6e 61 62 6c  is routine enabl
33370 65 73 20 6f 72 20 64 69 73 61 62 6c 65 73 20 74  es or disables t
33380 68 65 20 73 68 61 72 69 6e 67 20 6f 66 20 74 68  he sharing of th
33390 65 20 64 61 74 61 62 61 73 65 20 63 61 63 68 65  e database cache
333a0 0a 2a 2a 20 61 6e 64 20 73 63 68 65 6d 61 20 64  .** and schema d
333b0 61 74 61 20 73 74 72 75 63 74 75 72 65 73 20 62  ata structures b
333c0 65 74 77 65 65 6e 20 5b 64 61 74 61 62 61 73 65  etween [database
333d0 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 7c 20 63 6f   connection | co
333e0 6e 6e 65 63 74 69 6f 6e 73 5d 0a 2a 2a 20 74 6f  nnections].** to
333f0 20 74 68 65 20 73 61 6d 65 20 64 61 74 61 62 61   the same databa
33400 73 65 2e 20 53 68 61 72 69 6e 67 20 69 73 20 65  se. Sharing is e
33410 6e 61 62 6c 65 64 20 69 66 20 74 68 65 20 61 72  nabled if the ar
33420 67 75 6d 65 6e 74 20 69 73 20 74 72 75 65 0a 2a  gument is true.*
33430 2a 20 61 6e 64 20 64 69 73 61 62 6c 65 64 20 69  * and disabled i
33440 66 20 74 68 65 20 61 72 67 75 6d 65 6e 74 20 69  f the argument i
33450 73 20 66 61 6c 73 65 2e 29 5e 0a 2a 2a 0a 2a 2a  s false.)^.**.**
33460 20 5e 43 61 63 68 65 20 73 68 61 72 69 6e 67 20   ^Cache sharing 
33470 69 73 20 65 6e 61 62 6c 65 64 20 61 6e 64 20 64  is enabled and d
33480 69 73 61 62 6c 65 64 20 66 6f 72 20 61 6e 20 65  isabled for an e
33490 6e 74 69 72 65 20 70 72 6f 63 65 73 73 2e 0a 2a  ntire process..*
334a0 2a 20 54 68 69 73 20 69 73 20 61 20 63 68 61 6e  * This is a chan
334b0 67 65 20 61 73 20 6f 66 20 53 51 4c 69 74 65 20  ge as of SQLite 
334c0 76 65 72 73 69 6f 6e 20 33 2e 35 2e 30 2e 20 49  version 3.5.0. I
334d0 6e 20 70 72 69 6f 72 20 76 65 72 73 69 6f 6e 73  n prior versions
334e0 20 6f 66 20 53 51 4c 69 74 65 2c 0a 2a 2a 20 73   of SQLite,.** s
334f0 68 61 72 69 6e 67 20 77 61 73 20 65 6e 61 62 6c  haring was enabl
33500 65 64 20 6f 72 20 64 69 73 61 62 6c 65 64 20 66  ed or disabled f
33510 6f 72 20 65 61 63 68 20 74 68 72 65 61 64 20 73  or each thread s
33520 65 70 61 72 61 74 65 6c 79 2e 0a 2a 2a 0a 2a 2a  eparately..**.**
33530 20 5e 28 54 68 65 20 63 61 63 68 65 20 73 68 61   ^(The cache sha
33540 72 69 6e 67 20 6d 6f 64 65 20 73 65 74 20 62 79  ring mode set by
33550 20 74 68 69 73 20 69 6e 74 65 72 66 61 63 65 20   this interface 
33560 65 66 66 65 63 74 73 20 61 6c 6c 20 73 75 62 73  effects all subs
33570 65 71 75 65 6e 74 0a 2a 2a 20 63 61 6c 6c 73 20  equent.** calls 
33580 74 6f 20 5b 73 71 6c 69 74 65 33 5f 6f 70 65 6e  to [sqlite3_open
33590 28 29 5d 2c 20 5b 73 71 6c 69 74 65 33 5f 6f 70  ()], [sqlite3_op
335a0 65 6e 5f 76 32 28 29 5d 2c 20 61 6e 64 20 5b 73  en_v2()], and [s
335b0 71 6c 69 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d  qlite3_open16()]
335c0 2e 0a 2a 2a 20 45 78 69 73 74 69 6e 67 20 64 61  ..** Existing da
335d0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
335e0 6e 73 20 63 6f 6e 74 69 6e 75 65 20 75 73 65 20  ns continue use 
335f0 74 68 65 20 73 68 61 72 69 6e 67 20 6d 6f 64 65  the sharing mode
33600 0a 2a 2a 20 74 68 61 74 20 77 61 73 20 69 6e 20  .** that was in 
33610 65 66 66 65 63 74 20 61 74 20 74 68 65 20 74 69  effect at the ti
33620 6d 65 20 74 68 65 79 20 77 65 72 65 20 6f 70 65  me they were ope
33630 6e 65 64 2e 29 5e 0a 2a 2a 0a 2a 2a 20 5e 28 54  ned.)^.**.** ^(T
33640 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74 75  his routine retu
33650 72 6e 73 20 5b 53 51 4c 49 54 45 5f 4f 4b 5d 20  rns [SQLITE_OK] 
33660 69 66 20 73 68 61 72 65 64 20 63 61 63 68 65 20  if shared cache 
33670 77 61 73 20 65 6e 61 62 6c 65 64 20 6f 72 20 64  was enabled or d
33680 69 73 61 62 6c 65 64 0a 2a 2a 20 73 75 63 63 65  isabled.** succe
33690 73 73 66 75 6c 6c 79 2e 20 20 41 6e 20 5b 65 72  ssfully.  An [er
336a0 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65 74  ror code] is ret
336b0 75 72 6e 65 64 20 6f 74 68 65 72 77 69 73 65 2e  urned otherwise.
336c0 29 5e 0a 2a 2a 0a 2a 2a 20 5e 53 68 61 72 65 64  )^.**.** ^Shared
336d0 20 63 61 63 68 65 20 69 73 20 64 69 73 61 62 6c   cache is disabl
336e0 65 64 20 62 79 20 64 65 66 61 75 6c 74 2e 20 42  ed by default. B
336f0 75 74 20 74 68 69 73 20 6d 69 67 68 74 20 63 68  ut this might ch
33700 61 6e 67 65 20 69 6e 0a 2a 2a 20 66 75 74 75 72  ange in.** futur
33710 65 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51  e releases of SQ
33720 4c 69 74 65 2e 20 20 41 70 70 6c 69 63 61 74 69  Lite.  Applicati
33730 6f 6e 73 20 74 68 61 74 20 63 61 72 65 20 61 62  ons that care ab
33740 6f 75 74 20 73 68 61 72 65 64 0a 2a 2a 20 63 61  out shared.** ca
33750 63 68 65 20 73 65 74 74 69 6e 67 20 73 68 6f 75  che setting shou
33760 6c 64 20 73 65 74 20 69 74 20 65 78 70 6c 69 63  ld set it explic
33770 69 74 6c 79 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20  itly..**.** See 
33780 41 6c 73 6f 3a 20 20 5b 53 51 4c 69 74 65 20 53  Also:  [SQLite S
33790 68 61 72 65 64 2d 43 61 63 68 65 20 4d 6f 64 65  hared-Cache Mode
337a0 5d 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74 65 33  ].*/.int sqlite3
337b0 5f 65 6e 61 62 6c 65 5f 73 68 61 72 65 64 5f 63  _enable_shared_c
337c0 61 63 68 65 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a  ache(int);../*.*
337d0 2a 20 43 41 50 49 33 52 45 46 3a 20 41 74 74 65  * CAPI3REF: Atte
337e0 6d 70 74 20 54 6f 20 46 72 65 65 20 48 65 61 70  mpt To Free Heap
337f0 20 4d 65 6d 6f 72 79 0a 2a 2a 0a 2a 2a 20 5e 54   Memory.**.** ^T
33800 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c 65 61  he sqlite3_relea
33810 73 65 5f 6d 65 6d 6f 72 79 28 29 20 69 6e 74 65  se_memory() inte
33820 72 66 61 63 65 20 61 74 74 65 6d 70 74 73 20 74  rface attempts t
33830 6f 20 66 72 65 65 20 4e 20 62 79 74 65 73 0a 2a  o free N bytes.*
33840 2a 20 6f 66 20 68 65 61 70 20 6d 65 6d 6f 72 79  * of heap memory
33850 20 62 79 20 64 65 61 6c 6c 6f 63 61 74 69 6e 67   by deallocating
33860 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61 6c 20 6d   non-essential m
33870 65 6d 6f 72 79 20 61 6c 6c 6f 63 61 74 69 6f 6e  emory allocation
33880 73 0a 2a 2a 20 68 65 6c 64 20 62 79 20 74 68 65  s.** held by the
33890 20 64 61 74 61 62 61 73 65 20 6c 69 62 72 61 72   database librar
338a0 79 2e 20 20 20 4d 65 6d 6f 72 79 20 75 73 65 64  y.   Memory used
338b0 20 74 6f 20 63 61 63 68 65 20 64 61 74 61 62 61   to cache databa
338c0 73 65 0a 2a 2a 20 70 61 67 65 73 20 74 6f 20 69  se.** pages to i
338d0 6d 70 72 6f 76 65 20 70 65 72 66 6f 72 6d 61 6e  mprove performan
338e0 63 65 20 69 73 20 61 6e 20 65 78 61 6d 70 6c 65  ce is an example
338f0 20 6f 66 20 6e 6f 6e 2d 65 73 73 65 6e 74 69 61   of non-essentia
33900 6c 20 6d 65 6d 6f 72 79 2e 0a 2a 2a 20 5e 73 71  l memory..** ^sq
33910 6c 69 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65  lite3_release_me
33920 6d 6f 72 79 28 29 20 72 65 74 75 72 6e 73 20 74  mory() returns t
33930 68 65 20 6e 75 6d 62 65 72 20 6f 66 20 62 79 74  he number of byt
33940 65 73 20 61 63 74 75 61 6c 6c 79 20 66 72 65 65  es actually free
33950 64 2c 0a 2a 2a 20 77 68 69 63 68 20 6d 69 67 68  d,.** which migh
33960 74 20 62 65 20 6d 6f 72 65 20 6f 72 20 6c 65 73  t be more or les
33970 73 20 74 68 61 6e 20 74 68 65 20 61 6d 6f 75 6e  s than the amoun
33980 74 20 72 65 71 75 65 73 74 65 64 2e 0a 2a 2a 20  t requested..** 
33990 5e 54 68 65 20 73 71 6c 69 74 65 33 5f 72 65 6c  ^The sqlite3_rel
339a0 65 61 73 65 5f 6d 65 6d 6f 72 79 28 29 20 72 6f  ease_memory() ro
339b0 75 74 69 6e 65 20 69 73 20 61 20 6e 6f 2d 6f 70  utine is a no-op
339c0 20 72 65 74 75 72 6e 69 6e 67 20 7a 65 72 6f 0a   returning zero.
339d0 2a 2a 20 69 66 20 53 51 4c 69 74 65 20 69 73 20  ** if SQLite is 
339e0 6e 6f 74 20 63 6f 6d 70 69 6c 65 64 20 77 69 74  not compiled wit
339f0 68 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45  h [SQLITE_ENABLE
33a00 5f 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45  _MEMORY_MANAGEME
33a10 4e 54 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69  NT]..*/.int sqli
33a20 74 65 33 5f 72 65 6c 65 61 73 65 5f 6d 65 6d 6f  te3_release_memo
33a30 72 79 28 69 6e 74 29 3b 0a 0a 2f 2a 0a 2a 2a 20  ry(int);../*.** 
33a40 43 41 50 49 33 52 45 46 3a 20 49 6d 70 6f 73 65  CAPI3REF: Impose
33a50 20 41 20 4c 69 6d 69 74 20 4f 6e 20 48 65 61 70   A Limit On Heap
33a60 20 53 69 7a 65 0a 2a 2a 0a 2a 2a 20 5e 54 68 65   Size.**.** ^The
33a70 20 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65   sqlite3_soft_he
33a80 61 70 5f 6c 69 6d 69 74 36 34 28 29 20 69 6e 74  ap_limit64() int
33a90 65 72 66 61 63 65 20 73 65 74 73 20 61 6e 64 2f  erface sets and/
33aa0 6f 72 20 71 75 65 72 69 65 73 20 74 68 65 0a 2a  or queries the.*
33ab0 2a 20 73 6f 66 74 20 6c 69 6d 69 74 20 6f 6e 20  * soft limit on 
33ac0 74 68 65 20 61 6d 6f 75 6e 74 20 6f 66 20 68 65  the amount of he
33ad0 61 70 20 6d 65 6d 6f 72 79 20 74 68 61 74 20 6d  ap memory that m
33ae0 61 79 20 62 65 20 61 6c 6c 6f 63 61 74 65 64 20  ay be allocated 
33af0 62 79 20 53 51 4c 69 74 65 2e 0a 2a 2a 20 5e 53  by SQLite..** ^S
33b00 51 4c 69 74 65 20 73 74 72 69 76 65 73 20 74 6f  QLite strives to
33b10 20 6b 65 65 70 20 68 65 61 70 20 6d 65 6d 6f 72   keep heap memor
33b20 79 20 75 74 69 6c 69 7a 61 74 69 6f 6e 20 62 65  y utilization be
33b30 6c 6f 77 20 74 68 65 20 73 6f 66 74 20 68 65 61  low the soft hea
33b40 70 0a 2a 2a 20 6c 69 6d 69 74 20 62 79 20 72 65  p.** limit by re
33b50 64 75 63 69 6e 67 20 74 68 65 20 6e 75 6d 62 65  ducing the numbe
33b60 72 20 6f 66 20 70 61 67 65 73 20 68 65 6c 64 20  r of pages held 
33b70 69 6e 20 74 68 65 20 70 61 67 65 20 63 61 63 68  in the page cach
33b80 65 0a 2a 2a 20 61 73 20 68 65 61 70 20 6d 65 6d  e.** as heap mem
33b90 6f 72 79 20 75 73 61 67 65 73 20 61 70 70 72 6f  ory usages appro
33ba0 61 63 68 65 73 20 74 68 65 20 6c 69 6d 69 74 2e  aches the limit.
33bb0 0a 2a 2a 20 5e 54 68 65 20 73 6f 66 74 20 68 65  .** ^The soft he
33bc0 61 70 20 6c 69 6d 69 74 20 69 73 20 22 73 6f 66  ap limit is "sof
33bd0 74 22 20 62 65 63 61 75 73 65 20 65 76 65 6e 20  t" because even 
33be0 74 68 6f 75 67 68 20 53 51 4c 69 74 65 20 73 74  though SQLite st
33bf0 72 69 76 65 73 20 74 6f 20 73 74 61 79 0a 2a 2a  rives to stay.**
33c00 20 62 65 6c 6f 77 20 74 68 65 20 6c 69 6d 69 74   below the limit
33c10 2c 20 69 74 20 77 69 6c 6c 20 65 78 63 65 65 64  , it will exceed
33c20 20 74 68 65 20 6c 69 6d 69 74 20 72 61 74 68 65   the limit rathe
33c30 72 20 74 68 61 6e 20 67 65 6e 65 72 61 74 65 0a  r than generate.
33c40 2a 2a 20 61 6e 20 5b 53 51 4c 49 54 45 5f 4e 4f  ** an [SQLITE_NO
33c50 4d 45 4d 5d 20 65 72 72 6f 72 2e 20 20 49 6e 20  MEM] error.  In 
33c60 6f 74 68 65 72 20 77 6f 72 64 73 2c 20 74 68 65  other words, the
33c70 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
33c80 20 0a 2a 2a 20 69 73 20 61 64 76 69 73 6f 72 79   .** is advisory
33c90 20 6f 6e 6c 79 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68   only..**.** ^Th
33ca0 65 20 72 65 74 75 72 6e 20 76 61 6c 75 65 20 66  e return value f
33cb0 72 6f 6d 20 73 71 6c 69 74 65 33 5f 73 6f 66 74  rom sqlite3_soft
33cc0 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29 20  _heap_limit64() 
33cd0 69 73 20 74 68 65 20 73 69 7a 65 20 6f 66 0a 2a  is the size of.*
33ce0 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
33cf0 6c 69 6d 69 74 20 70 72 69 6f 72 20 74 6f 20 74  limit prior to t
33d00 68 65 20 63 61 6c 6c 2e 20 20 5e 49 66 20 74 68  he call.  ^If th
33d10 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73 20  e argument N is 
33d20 6e 65 67 61 74 69 76 65 0a 2a 2a 20 74 68 65 6e  negative.** then
33d30 20 6e 6f 20 63 68 61 6e 67 65 20 69 73 20 6d 61   no change is ma
33d40 64 65 20 74 6f 20 74 68 65 20 73 6f 66 74 20 68  de to the soft h
33d50 65 61 70 20 6c 69 6d 69 74 2e 20 20 48 65 6e 63  eap limit.  Henc
33d60 65 2c 20 74 68 65 20 63 75 72 72 65 6e 74 0a 2a  e, the current.*
33d70 2a 20 73 69 7a 65 20 6f 66 20 74 68 65 20 73 6f  * size of the so
33d80 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 63 61  ft heap limit ca
33d90 6e 20 62 65 20 64 65 74 65 72 6d 69 6e 65 64 20  n be determined 
33da0 62 79 20 69 6e 76 6f 6b 69 6e 67 0a 2a 2a 20 73  by invoking.** s
33db0 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65 61 70  qlite3_soft_heap
33dc0 5f 6c 69 6d 69 74 36 34 28 29 20 77 69 74 68 20  _limit64() with 
33dd0 61 20 6e 65 67 61 74 69 76 65 20 61 72 67 75 6d  a negative argum
33de0 65 6e 74 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74  ent..**.** ^If t
33df0 68 65 20 61 72 67 75 6d 65 6e 74 20 4e 20 69 73  he argument N is
33e00 20 7a 65 72 6f 20 74 68 65 6e 20 74 68 65 20 73   zero then the s
33e10 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74 20 69  oft heap limit i
33e20 73 20 64 69 73 61 62 6c 65 64 2e 0a 2a 2a 0a 2a  s disabled..**.*
33e30 2a 20 5e 28 54 68 65 20 73 6f 66 74 20 68 65 61  * ^(The soft hea
33e40 70 20 6c 69 6d 69 74 20 69 73 20 6e 6f 74 20 65  p limit is not e
33e50 6e 66 6f 72 63 65 64 20 69 6e 20 74 68 65 20 63  nforced in the c
33e60 75 72 72 65 6e 74 20 69 6d 70 6c 65 6d 65 6e 74  urrent implement
33e70 61 74 69 6f 6e 0a 2a 2a 20 69 66 20 6f 6e 65 20  ation.** if one 
33e80 6f 72 20 6d 6f 72 65 20 6f 66 20 66 6f 6c 6c 6f  or more of follo
33e90 77 69 6e 67 20 63 6f 6e 64 69 74 69 6f 6e 73 20  wing conditions 
33ea0 61 72 65 20 74 72 75 65 3a 0a 2a 2a 0a 2a 2a 20  are true:.**.** 
33eb0 3c 75 6c 3e 0a 2a 2a 20 3c 6c 69 3e 20 54 68 65  <ul>.** <li> The
33ec0 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
33ed0 20 69 73 20 73 65 74 20 74 6f 20 7a 65 72 6f 2e   is set to zero.
33ee0 0a 2a 2a 20 3c 6c 69 3e 20 4d 65 6d 6f 72 79 20  .** <li> Memory 
33ef0 61 63 63 6f 75 6e 74 69 6e 67 20 69 73 20 64 69  accounting is di
33f00 73 61 62 6c 65 64 20 75 73 69 6e 67 20 61 20 63  sabled using a c
33f10 6f 6d 62 69 6e 61 74 69 6f 6e 20 6f 66 20 74 68  ombination of th
33f20 65 0a 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74  e.**      [sqlit
33f30 65 33 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49  e3_config]([SQLI
33f40 54 45 5f 43 4f 4e 46 49 47 5f 4d 45 4d 53 54 41  TE_CONFIG_MEMSTA
33f50 54 55 53 5d 2c 2e 2e 2e 29 20 73 74 61 72 74 2d  TUS],...) start-
33f60 74 69 6d 65 20 6f 70 74 69 6f 6e 20 61 6e 64 0a  time option and.
33f70 2a 2a 20 20 20 20 20 20 74 68 65 20 5b 53 51 4c  **      the [SQL
33f80 49 54 45 5f 44 45 46 41 55 4c 54 5f 4d 45 4d 53  ITE_DEFAULT_MEMS
33f90 54 41 54 55 53 5d 20 63 6f 6d 70 69 6c 65 2d 74  TATUS] compile-t
33fa0 69 6d 65 20 6f 70 74 69 6f 6e 2e 0a 2a 2a 20 3c  ime option..** <
33fb0 6c 69 3e 20 41 6e 20 61 6c 74 65 72 6e 61 74 69  li> An alternati
33fc0 76 65 20 70 61 67 65 20 63 61 63 68 65 20 69 6d  ve page cache im
33fd0 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 69 73 20  plementation is 
33fe0 73 70 65 63 69 66 69 65 64 20 75 73 69 6e 67 0a  specified using.
33ff0 2a 2a 20 20 20 20 20 20 5b 73 71 6c 69 74 65 33  **      [sqlite3
34000 5f 63 6f 6e 66 69 67 5d 28 5b 53 51 4c 49 54 45  _config]([SQLITE
34010 5f 43 4f 4e 46 49 47 5f 50 43 41 43 48 45 5d 2c  _CONFIG_PCACHE],
34020 2e 2e 2e 29 2e 0a 2a 2a 20 3c 6c 69 3e 20 54 68  ...)..** <li> Th
34030 65 20 70 61 67 65 20 63 61 63 68 65 20 61 6c 6c  e page cache all
34040 6f 63 61 74 65 73 20 66 72 6f 6d 20 69 74 73 20  ocates from its 
34050 6f 77 6e 20 6d 65 6d 6f 72 79 20 70 6f 6f 6c 20  own memory pool 
34060 73 75 70 70 6c 69 65 64 0a 2a 2a 20 20 20 20 20  supplied.**     
34070 20 62 79 20 5b 73 71 6c 69 74 65 33 5f 63 6f 6e   by [sqlite3_con
34080 66 69 67 5d 28 5b 53 51 4c 49 54 45 5f 43 4f 4e  fig]([SQLITE_CON
34090 46 49 47 5f 50 41 47 45 43 41 43 48 45 5d 2c 2e  FIG_PAGECACHE],.
340a0 2e 2e 29 20 72 61 74 68 65 72 20 74 68 61 6e 0a  ..) rather than.
340b0 2a 2a 20 20 20 20 20 20 66 72 6f 6d 20 74 68 65  **      from the
340c0 20 68 65 61 70 2e 0a 2a 2a 20 3c 2f 75 6c 3e 29   heap..** </ul>)
340d0 5e 0a 2a 2a 0a 2a 2a 20 42 65 67 69 6e 6e 69 6e  ^.**.** Beginnin
340e0 67 20 77 69 74 68 20 53 51 4c 69 74 65 20 76 65  g with SQLite ve
340f0 72 73 69 6f 6e 20 33 2e 37 2e 33 2c 20 74 68 65  rsion 3.7.3, the
34100 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
34110 20 69 73 20 65 6e 66 6f 72 63 65 64 0a 2a 2a 20   is enforced.** 
34120 72 65 67 61 72 64 6c 65 73 73 20 6f 66 20 77 68  regardless of wh
34130 65 74 68 65 72 20 6f 72 20 6e 6f 74 20 74 68 65  ether or not the
34140 20 5b 53 51 4c 49 54 45 5f 45 4e 41 42 4c 45 5f   [SQLITE_ENABLE_
34150 4d 45 4d 4f 52 59 5f 4d 41 4e 41 47 45 4d 45 4e  MEMORY_MANAGEMEN
34160 54 5d 0a 2a 2a 20 63 6f 6d 70 69 6c 65 2d 74 69  T].** compile-ti
34170 6d 65 20 6f 70 74 69 6f 6e 20 69 73 20 69 6e 76  me option is inv
34180 6f 6b 65 64 2e 20 20 57 69 74 68 20 5b 53 51 4c  oked.  With [SQL
34190 49 54 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52  ITE_ENABLE_MEMOR
341a0 59 5f 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 0a 2a  Y_MANAGEMENT],.*
341b0 2a 20 74 68 65 20 73 6f 66 74 20 68 65 61 70 20  * the soft heap 
341c0 6c 69 6d 69 74 20 69 73 20 65 6e 66 6f 72 63 65  limit is enforce
341d0 64 20 6f 6e 20 65 76 65 72 79 20 6d 65 6d 6f 72  d on every memor
341e0 79 20 61 6c 6c 6f 63 61 74 69 6f 6e 2e 20 20 57  y allocation.  W
341f0 69 74 68 6f 75 74 0a 2a 2a 20 5b 53 51 4c 49 54  ithout.** [SQLIT
34200 45 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f  E_ENABLE_MEMORY_
34210 4d 41 4e 41 47 45 4d 45 4e 54 5d 2c 20 74 68 65  MANAGEMENT], the
34220 20 73 6f 66 74 20 68 65 61 70 20 6c 69 6d 69 74   soft heap limit
34230 20 69 73 20 6f 6e 6c 79 20 65 6e 66 6f 72 63 65   is only enforce
34240 64 0a 2a 2a 20 77 68 65 6e 20 6d 65 6d 6f 72 79  d.** when memory
34250 20 69 73 20 61 6c 6c 6f 63 61 74 65 64 20 62 79   is allocated by
34260 20 74 68 65 20 70 61 67 65 20 63 61 63 68 65 2e   the page cache.
34270 20 20 54 65 73 74 69 6e 67 20 73 75 67 67 65 73    Testing sugges
34280 74 73 20 74 68 61 74 20 62 65 63 61 75 73 65 0a  ts that because.
34290 2a 2a 20 74 68 65 20 70 61 67 65 20 63 61 63 68  ** the page cach
342a0 65 20 69 73 20 74 68 65 20 70 72 65 64 6f 6d 69  e is the predomi
342b0 6e 61 74 65 20 6d 65 6d 6f 72 79 20 75 73 65 72  nate memory user
342c0 20 69 6e 20 53 51 4c 69 74 65 2c 20 6d 6f 73 74   in SQLite, most
342d0 0a 2a 2a 20 61 70 70 6c 69 63 61 74 69 6f 6e 73  .** applications
342e0 20 77 69 6c 6c 20 61 63 68 69 65 76 65 20 61 64   will achieve ad
342f0 65 71 75 61 74 65 20 73 6f 66 74 20 68 65 61 70  equate soft heap
34300 20 6c 69 6d 69 74 20 65 6e 66 6f 72 63 65 6d 65   limit enforceme
34310 6e 74 20 77 69 74 68 6f 75 74 0a 2a 2a 20 74 68  nt without.** th
34320 65 20 75 73 65 20 6f 66 20 5b 53 51 4c 49 54 45  e use of [SQLITE
34330 5f 45 4e 41 42 4c 45 5f 4d 45 4d 4f 52 59 5f 4d  _ENABLE_MEMORY_M
34340 41 4e 41 47 45 4d 45 4e 54 5d 2e 0a 2a 2a 0a 2a  ANAGEMENT]..**.*
34350 2a 20 54 68 65 20 63 69 72 63 75 6d 73 74 61 6e  * The circumstan
34360 63 65 73 20 75 6e 64 65 72 20 77 68 69 63 68 20  ces under which 
34370 53 51 4c 69 74 65 20 77 69 6c 6c 20 65 6e 66 6f  SQLite will enfo
34380 72 63 65 20 74 68 65 20 73 6f 66 74 20 68 65 61  rce the soft hea
34390 70 20 6c 69 6d 69 74 20 6d 61 79 0a 2a 2a 20 63  p limit may.** c
343a0 68 61 6e 67 65 73 20 69 6e 20 66 75 74 75 72 65  hanges in future
343b0 20 72 65 6c 65 61 73 65 73 20 6f 66 20 53 51 4c   releases of SQL
343c0 69 74 65 2e 0a 2a 2f 0a 73 71 6c 69 74 65 33 5f  ite..*/.sqlite3_
343d0 69 6e 74 36 34 20 73 71 6c 69 74 65 33 5f 73 6f  int64 sqlite3_so
343e0 66 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28  ft_heap_limit64(
343f0 73 71 6c 69 74 65 33 5f 69 6e 74 36 34 20 4e 29  sqlite3_int64 N)
34400 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45  ;../*.** CAPI3RE
34410 46 3a 20 44 65 70 72 65 63 61 74 65 64 20 53 6f  F: Deprecated So
34420 66 74 20 48 65 61 70 20 4c 69 6d 69 74 20 49 6e  ft Heap Limit In
34430 74 65 72 66 61 63 65 0a 2a 2a 20 44 45 50 52 45  terface.** DEPRE
34440 43 41 54 45 44 0a 2a 2a 0a 2a 2a 20 54 68 69 73  CATED.**.** This
34450 20 69 73 20 61 20 64 65 70 72 65 63 61 74 65 64   is a deprecated
34460 20 76 65 72 73 69 6f 6e 20 6f 66 20 74 68 65 20   version of the 
34470 5b 73 71 6c 69 74 65 33 5f 73 6f 66 74 5f 68 65  [sqlite3_soft_he
34480 61 70 5f 6c 69 6d 69 74 36 34 28 29 5d 0a 2a 2a  ap_limit64()].**
34490 20 69 6e 74 65 72 66 61 63 65 2e 20 20 54 68 69   interface.  Thi
344a0 73 20 72 6f 75 74 69 6e 65 20 69 73 20 70 72 6f  s routine is pro
344b0 76 69 64 65 64 20 66 6f 72 20 68 69 73 74 6f 72  vided for histor
344c0 69 63 61 6c 20 63 6f 6d 70 61 74 69 62 69 6c 69  ical compatibili
344d0 74 79 0a 2a 2a 20 6f 6e 6c 79 2e 20 20 41 6c 6c  ty.** only.  All
344e0 20 6e 65 77 20 61 70 70 6c 69 63 61 74 69 6f 6e   new application
344f0 73 20 73 68 6f 75 6c 64 20 75 73 65 20 74 68 65  s should use the
34500 0a 2a 2a 20 5b 73 71 6c 69 74 65 33 5f 73 6f 66  .** [sqlite3_sof
34510 74 5f 68 65 61 70 5f 6c 69 6d 69 74 36 34 28 29  t_heap_limit64()
34520 5d 20 69 6e 74 65 72 66 61 63 65 20 72 61 74 68  ] interface rath
34530 65 72 20 74 68 61 6e 20 74 68 69 73 20 6f 6e 65  er than this one
34540 2e 0a 2a 2f 0a 53 51 4c 49 54 45 5f 44 45 50 52  ..*/.SQLITE_DEPR
34550 45 43 41 54 45 44 20 76 6f 69 64 20 73 71 6c 69  ECATED void sqli
34560 74 65 33 5f 73 6f 66 74 5f 68 65 61 70 5f 6c 69  te3_soft_heap_li
34570 6d 69 74 28 69 6e 74 20 4e 29 3b 0a 0a 0a 2f 2a  mit(int N);.../*
34580 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 45 78  .** CAPI3REF: Ex
34590 74 72 61 63 74 20 4d 65 74 61 64 61 74 61 20 41  tract Metadata A
345a0 62 6f 75 74 20 41 20 43 6f 6c 75 6d 6e 20 4f 66  bout A Column Of
345b0 20 41 20 54 61 62 6c 65 0a 2a 2a 0a 2a 2a 20 5e   A Table.**.** ^
345c0 54 68 69 73 20 72 6f 75 74 69 6e 65 20 72 65 74  This routine ret
345d0 75 72 6e 73 20 6d 65 74 61 64 61 74 61 20 61 62  urns metadata ab
345e0 6f 75 74 20 61 20 73 70 65 63 69 66 69 63 20 63  out a specific c
345f0 6f 6c 75 6d 6e 20 6f 66 20 61 20 73 70 65 63 69  olumn of a speci
34600 66 69 63 0a 2a 2a 20 64 61 74 61 62 61 73 65 20  fic.** database 
34610 74 61 62 6c 65 20 61 63 63 65 73 73 69 62 6c 65  table accessible
34620 20 75 73 69 6e 67 20 74 68 65 20 5b 64 61 74 61   using the [data
34630 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34640 20 68 61 6e 64 6c 65 0a 2a 2a 20 70 61 73 73 65   handle.** passe
34650 64 20 61 73 20 74 68 65 20 66 69 72 73 74 20 66  d as the first f
34660 75 6e 63 74 69 6f 6e 20 61 72 67 75 6d 65 6e 74  unction argument
34670 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 63 6f 6c  ..**.** ^The col
34680 75 6d 6e 20 69 73 20 69 64 65 6e 74 69 66 69 65  umn is identifie
34690 64 20 62 79 20 74 68 65 20 73 65 63 6f 6e 64 2c  d by the second,
346a0 20 74 68 69 72 64 20 61 6e 64 20 66 6f 75 72 74   third and fourt
346b0 68 20 70 61 72 61 6d 65 74 65 72 73 20 74 6f 0a  h parameters to.
346c0 2a 2a 20 74 68 69 73 20 66 75 6e 63 74 69 6f 6e  ** this function
346d0 2e 20 5e 54 68 65 20 73 65 63 6f 6e 64 20 70 61  . ^The second pa
346e0 72 61 6d 65 74 65 72 20 69 73 20 65 69 74 68 65  rameter is eithe
346f0 72 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68  r the name of th
34700 65 20 64 61 74 61 62 61 73 65 0a 2a 2a 20 28 69  e database.** (i
34710 2e 65 2e 20 22 6d 61 69 6e 22 2c 20 22 74 65 6d  .e. "main", "tem
34720 70 22 2c 20 6f 72 20 61 6e 20 61 74 74 61 63 68  p", or an attach
34730 65 64 20 64 61 74 61 62 61 73 65 29 20 63 6f 6e  ed database) con
34740 74 61 69 6e 69 6e 67 20 74 68 65 20 73 70 65 63  taining the spec
34750 69 66 69 65 64 0a 2a 2a 20 74 61 62 6c 65 20 6f  ified.** table o
34760 72 20 4e 55 4c 4c 2e 20 5e 49 66 20 69 74 20 69  r NULL. ^If it i
34770 73 20 4e 55 4c 4c 2c 20 74 68 65 6e 20 61 6c 6c  s NULL, then all
34780 20 61 74 74 61 63 68 65 64 20 64 61 74 61 62 61   attached databa
34790 73 65 73 20 61 72 65 20 73 65 61 72 63 68 65 64  ses are searched
347a0 0a 2a 2a 20 66 6f 72 20 74 68 65 20 74 61 62 6c  .** for the tabl
347b0 65 20 75 73 69 6e 67 20 74 68 65 20 73 61 6d 65  e using the same
347c0 20 61 6c 67 6f 72 69 74 68 6d 20 75 73 65 64 20   algorithm used 
347d0 62 79 20 74 68 65 20 64 61 74 61 62 61 73 65 20  by the database 
347e0 65 6e 67 69 6e 65 20 74 6f 0a 2a 2a 20 72 65 73  engine to.** res
347f0 6f 6c 76 65 20 75 6e 71 75 61 6c 69 66 69 65 64  olve unqualified
34800 20 74 61 62 6c 65 20 72 65 66 65 72 65 6e 63 65   table reference
34810 73 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 74 68  s..**.** ^The th
34820 69 72 64 20 61 6e 64 20 66 6f 75 72 74 68 20 70  ird and fourth p
34830 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68 69  arameters to thi
34840 73 20 66 75 6e 63 74 69 6f 6e 20 61 72 65 20 74  s function are t
34850 68 65 20 74 61 62 6c 65 20 61 6e 64 20 63 6f 6c  he table and col
34860 75 6d 6e 0a 2a 2a 20 6e 61 6d 65 20 6f 66 20 74  umn.** name of t
34870 68 65 20 64 65 73 69 72 65 64 20 63 6f 6c 75 6d  he desired colum
34880 6e 2c 20 72 65 73 70 65 63 74 69 76 65 6c 79 2e  n, respectively.
34890 20 4e 65 69 74 68 65 72 20 6f 66 20 74 68 65 73   Neither of thes
348a0 65 20 70 61 72 61 6d 65 74 65 72 73 0a 2a 2a 20  e parameters.** 
348b0 6d 61 79 20 62 65 20 4e 55 4c 4c 2e 0a 2a 2a 0a  may be NULL..**.
348c0 2a 2a 20 5e 4d 65 74 61 64 61 74 61 20 69 73 20  ** ^Metadata is 
348d0 72 65 74 75 72 6e 65 64 20 62 79 20 77 72 69 74  returned by writ
348e0 69 6e 67 20 74 6f 20 74 68 65 20 6d 65 6d 6f 72  ing to the memor
348f0 79 20 6c 6f 63 61 74 69 6f 6e 73 20 70 61 73 73  y locations pass
34900 65 64 20 61 73 20 74 68 65 20 35 74 68 0a 2a 2a  ed as the 5th.**
34910 20 61 6e 64 20 73 75 62 73 65 71 75 65 6e 74 20   and subsequent 
34920 70 61 72 61 6d 65 74 65 72 73 20 74 6f 20 74 68  parameters to th
34930 69 73 20 66 75 6e 63 74 69 6f 6e 2e 20 5e 41 6e  is function. ^An
34940 79 20 6f 66 20 74 68 65 73 65 20 61 72 67 75 6d  y of these argum
34950 65 6e 74 73 20 6d 61 79 20 62 65 0a 2a 2a 20 4e  ents may be.** N
34960 55 4c 4c 2c 20 69 6e 20 77 68 69 63 68 20 63 61  ULL, in which ca
34970 73 65 20 74 68 65 20 63 6f 72 72 65 73 70 6f 6e  se the correspon
34980 64 69 6e 67 20 65 6c 65 6d 65 6e 74 20 6f 66 20  ding element of 
34990 6d 65 74 61 64 61 74 61 20 69 73 20 6f 6d 69 74  metadata is omit
349a0 74 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e 28 3c 62 6c  ted..**.** ^(<bl
349b0 6f 63 6b 71 75 6f 74 65 3e 0a 2a 2a 20 3c 74 61  ockquote>.** <ta
349c0 62 6c 65 20 62 6f 72 64 65 72 3d 22 31 22 3e 0a  ble border="1">.
349d0 2a 2a 20 3c 74 72 3e 3c 74 68 3e 20 50 61 72 61  ** <tr><th> Para
349e0 6d 65 74 65 72 20 3c 74 68 3e 20 4f 75 74 70 75  meter <th> Outpu
349f0 74 3c 62 72 3e 54 79 70 65 20 3c 74 68 3e 20 20  t<br>Type <th>  
34a00 44 65 73 63 72 69 70 74 69 6f 6e 0a 2a 2a 0a 2a  Description.**.*
34a10 2a 20 3c 74 72 3e 3c 74 64 3e 20 35 74 68 20 3c  * <tr><td> 5th <
34a20 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
34a30 3c 74 64 3e 20 44 61 74 61 20 74 79 70 65 0a 2a  <td> Data type.*
34a40 2a 20 3c 74 72 3e 3c 74 64 3e 20 36 74 68 20 3c  * <tr><td> 6th <
34a50 74 64 3e 20 63 6f 6e 73 74 20 63 68 61 72 2a 20  td> const char* 
34a60 3c 74 64 3e 20 4e 61 6d 65 20 6f 66 20 64 65 66  <td> Name of def
34a70 61 75 6c 74 20 63 6f 6c 6c 61 74 69 6f 6e 20 73  ault collation s
34a80 65 71 75 65 6e 63 65 0a 2a 2a 20 3c 74 72 3e 3c  equence.** <tr><
34a90 74 64 3e 20 37 74 68 20 3c 74 64 3e 20 69 6e 74  td> 7th <td> int
34aa0 20 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72           <td> Tr
34ab0 75 65 20 69 66 20 63 6f 6c 75 6d 6e 20 68 61 73  ue if column has
34ac0 20 61 20 4e 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73   a NOT NULL cons
34ad0 74 72 61 69 6e 74 0a 2a 2a 20 3c 74 72 3e 3c 74  traint.** <tr><t
34ae0 64 3e 20 38 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 8th <td> int 
34af0 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
34b00 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 70  e if column is p
34b10 61 72 74 20 6f 66 20 74 68 65 20 50 52 49 4d 41  art of the PRIMA
34b20 52 59 20 4b 45 59 0a 2a 2a 20 3c 74 72 3e 3c 74  RY KEY.** <tr><t
34b30 64 3e 20 39 74 68 20 3c 74 64 3e 20 69 6e 74 20  d> 9th <td> int 
34b40 20 20 20 20 20 20 20 20 3c 74 64 3e 20 54 72 75          <td> Tru
34b50 65 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 5b  e if column is [
34b60 41 55 54 4f 49 4e 43 52 45 4d 45 4e 54 5d 0a 2a  AUTOINCREMENT].*
34b70 2a 20 3c 2f 74 61 62 6c 65 3e 0a 2a 2a 20 3c 2f  * </table>.** </
34b80 62 6c 6f 63 6b 71 75 6f 74 65 3e 29 5e 0a 2a 2a  blockquote>)^.**
34b90 0a 2a 2a 20 5e 54 68 65 20 6d 65 6d 6f 72 79 20  .** ^The memory 
34ba0 70 6f 69 6e 74 65 64 20 74 6f 20 62 79 20 74 68  pointed to by th
34bb0 65 20 63 68 61 72 61 63 74 65 72 20 70 6f 69 6e  e character poin
34bc0 74 65 72 73 20 72 65 74 75 72 6e 65 64 20 66 6f  ters returned fo
34bd0 72 20 74 68 65 0a 2a 2a 20 64 65 63 6c 61 72 61  r the.** declara
34be0 74 69 6f 6e 20 74 79 70 65 20 61 6e 64 20 63 6f  tion type and co
34bf0 6c 6c 61 74 69 6f 6e 20 73 65 71 75 65 6e 63 65  llation sequence
34c00 20 69 73 20 76 61 6c 69 64 20 6f 6e 6c 79 20 75   is valid only u
34c10 6e 74 69 6c 20 74 68 65 20 6e 65 78 74 0a 2a 2a  ntil the next.**
34c20 20 63 61 6c 6c 20 74 6f 20 61 6e 79 20 53 51 4c   call to any SQL
34c30 69 74 65 20 41 50 49 20 66 75 6e 63 74 69 6f 6e  ite API function
34c40 2e 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20  ..**.** ^If the 
34c50 73 70 65 63 69 66 69 65 64 20 74 61 62 6c 65 20  specified table 
34c60 69 73 20 61 63 74 75 61 6c 6c 79 20 61 20 76 69  is actually a vi
34c70 65 77 2c 20 61 6e 20 5b 65 72 72 6f 72 20 63 6f  ew, an [error co
34c80 64 65 5d 20 69 73 20 72 65 74 75 72 6e 65 64 2e  de] is returned.
34c90 0a 2a 2a 0a 2a 2a 20 5e 49 66 20 74 68 65 20 73  .**.** ^If the s
34ca0 70 65 63 69 66 69 65 64 20 63 6f 6c 75 6d 6e 20  pecified column 
34cb0 69 73 20 22 72 6f 77 69 64 22 2c 20 22 6f 69 64  is "rowid", "oid
34cc0 22 20 6f 72 20 22 5f 72 6f 77 69 64 5f 22 20 61  " or "_rowid_" a
34cd0 6e 64 20 61 6e 0a 2a 2a 20 5b 49 4e 54 45 47 45  nd an.** [INTEGE
34ce0 52 20 50 52 49 4d 41 52 59 20 4b 45 59 5d 20 63  R PRIMARY KEY] c
34cf0 6f 6c 75 6d 6e 20 68 61 73 20 62 65 65 6e 20 65  olumn has been e
34d00 78 70 6c 69 63 69 74 6c 79 20 64 65 63 6c 61 72  xplicitly declar
34d10 65 64 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  ed, then the out
34d20 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
34d30 73 20 61 72 65 20 73 65 74 20 66 6f 72 20 74 68  s are set for th
34d40 65 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  e explicitly dec
34d50 6c 61 72 65 64 20 63 6f 6c 75 6d 6e 2e 20 5e 28  lared column. ^(
34d60 49 66 20 74 68 65 72 65 20 69 73 20 6e 6f 0a 2a  If there is no.*
34d70 2a 20 65 78 70 6c 69 63 69 74 6c 79 20 64 65 63  * explicitly dec
34d80 6c 61 72 65 64 20 5b 49 4e 54 45 47 45 52 20 50  lared [INTEGER P
34d90 52 49 4d 41 52 59 20 4b 45 59 5d 20 63 6f 6c 75  RIMARY KEY] colu
34da0 6d 6e 2c 20 74 68 65 6e 20 74 68 65 20 6f 75 74  mn, then the out
34db0 70 75 74 0a 2a 2a 20 70 61 72 61 6d 65 74 65 72  put.** parameter
34dc0 73 20 61 72 65 20 73 65 74 20 61 73 20 66 6f 6c  s are set as fol
34dd0 6c 6f 77 73 3a 0a 2a 2a 0a 2a 2a 20 3c 70 72 65  lows:.**.** <pre
34de0 3e 0a 2a 2a 20 20 20 20 20 64 61 74 61 20 74 79  >.**     data ty
34df0 70 65 3a 20 22 49 4e 54 45 47 45 52 22 0a 2a 2a  pe: "INTEGER".**
34e00 20 20 20 20 20 63 6f 6c 6c 61 74 69 6f 6e 20 73       collation s
34e10 65 71 75 65 6e 63 65 3a 20 22 42 49 4e 41 52 59  equence: "BINARY
34e20 22 0a 2a 2a 20 20 20 20 20 6e 6f 74 20 6e 75 6c  ".**     not nul
34e30 6c 3a 20 30 0a 2a 2a 20 20 20 20 20 70 72 69 6d  l: 0.**     prim
34e40 61 72 79 20 6b 65 79 3a 20 31 0a 2a 2a 20 20 20  ary key: 1.**   
34e50 20 20 61 75 74 6f 20 69 6e 63 72 65 6d 65 6e 74    auto increment
34e60 3a 20 30 0a 2a 2a 20 3c 2f 70 72 65 3e 29 5e 0a  : 0.** </pre>)^.
34e70 2a 2a 0a 2a 2a 20 5e 28 54 68 69 73 20 66 75 6e  **.** ^(This fun
34e80 63 74 69 6f 6e 20 6d 61 79 20 6c 6f 61 64 20 6f  ction may load o
34e90 6e 65 20 6f 72 20 6d 6f 72 65 20 73 63 68 65 6d  ne or more schem
34ea0 61 73 20 66 72 6f 6d 20 64 61 74 61 62 61 73 65  as from database
34eb0 20 66 69 6c 65 73 2e 20 49 66 20 61 6e 0a 2a 2a   files. If an.**
34ec0 20 65 72 72 6f 72 20 6f 63 63 75 72 73 20 64 75   error occurs du
34ed0 72 69 6e 67 20 74 68 69 73 20 70 72 6f 63 65 73  ring this proces
34ee0 73 2c 20 6f 72 20 69 66 20 74 68 65 20 72 65 71  s, or if the req
34ef0 75 65 73 74 65 64 20 74 61 62 6c 65 20 6f 72 20  uested table or 
34f00 63 6f 6c 75 6d 6e 0a 2a 2a 20 63 61 6e 6e 6f 74  column.** cannot
34f10 20 62 65 20 66 6f 75 6e 64 2c 20 61 6e 20 5b 65   be found, an [e
34f20 72 72 6f 72 20 63 6f 64 65 5d 20 69 73 20 72 65  rror code] is re
34f30 74 75 72 6e 65 64 20 61 6e 64 20 61 6e 20 65 72  turned and an er
34f40 72 6f 72 20 6d 65 73 73 61 67 65 20 6c 65 66 74  ror message left
34f50 0a 2a 2a 20 69 6e 20 74 68 65 20 5b 64 61 74 61  .** in the [data
34f60 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 5d  base connection]
34f70 20 28 74 6f 20 62 65 20 72 65 74 72 69 65 76 65   (to be retrieve
34f80 64 20 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f  d using sqlite3_
34f90 65 72 72 6d 73 67 28 29 29 2e 29 5e 0a 2a 2a 0a  errmsg()).)^.**.
34fa0 2a 2a 20 5e 54 68 69 73 20 41 50 49 20 69 73 20  ** ^This API is 
34fb0 6f 6e 6c 79 20 61 76 61 69 6c 61 62 6c 65 20 69  only available i
34fc0 66 20 74 68 65 20 6c 69 62 72 61 72 79 20 77 61  f the library wa
34fd0 73 20 63 6f 6d 70 69 6c 65 64 20 77 69 74 68 20  s compiled with 
34fe0 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54 45 5f 45  the.** [SQLITE_E
34ff0 4e 41 42 4c 45 5f 43 4f 4c 55 4d 4e 5f 4d 45 54  NABLE_COLUMN_MET
35000 41 44 41 54 41 5d 20 43 2d 70 72 65 70 72 6f 63  ADATA] C-preproc
35010 65 73 73 6f 72 20 73 79 6d 62 6f 6c 20 64 65 66  essor symbol def
35020 69 6e 65 64 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c  ined..*/.int sql
35030 69 74 65 33 5f 74 61 62 6c 65 5f 63 6f 6c 75 6d  ite3_table_colum
35040 6e 5f 6d 65 74 61 64 61 74 61 28 0a 20 20 73 71  n_metadata(.  sq
35050 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
35060 20 20 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6e            /* Con
35070 6e 65 63 74 69 6f 6e 20 68 61 6e 64 6c 65 20 2a  nection handle *
35080 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20 2a  /.  const char *
35090 7a 44 62 4e 61 6d 65 2c 20 20 20 20 20 20 20 20  zDbName,        
350a0 2f 2a 20 44 61 74 61 62 61 73 65 20 6e 61 6d 65  /* Database name
350b0 20 6f 72 20 4e 55 4c 4c 20 2a 2f 0a 20 20 63 6f   or NULL */.  co
350c0 6e 73 74 20 63 68 61 72 20 2a 7a 54 61 62 6c 65  nst char *zTable
350d0 4e 61 6d 65 2c 20 20 20 20 20 2f 2a 20 54 61 62  Name,     /* Tab
350e0 6c 65 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 6f 6e  le name */.  con
350f0 73 74 20 63 68 61 72 20 2a 7a 43 6f 6c 75 6d 6e  st char *zColumn
35100 4e 61 6d 65 2c 20 20 20 20 2f 2a 20 43 6f 6c 75  Name,    /* Colu
35110 6d 6e 20 6e 61 6d 65 20 2a 2f 0a 20 20 63 68 61  mn name */.  cha
35120 72 20 63 6f 6e 73 74 20 2a 2a 70 7a 44 61 74 61  r const **pzData
35130 54 79 70 65 2c 20 20 20 20 2f 2a 20 4f 55 54 50  Type,    /* OUTP
35140 55 54 3a 20 44 65 63 6c 61 72 65 64 20 64 61 74  UT: Declared dat
35150 61 20 74 79 70 65 20 2a 2f 0a 20 20 63 68 61 72  a type */.  char
35160 20 63 6f 6e 73 74 20 2a 2a 70 7a 43 6f 6c 6c 53   const **pzCollS
35170 65 71 2c 20 20 20 20 20 2f 2a 20 4f 55 54 50 55  eq,     /* OUTPU
35180 54 3a 20 43 6f 6c 6c 61 74 69 6f 6e 20 73 65 71  T: Collation seq
35190 75 65 6e 63 65 20 6e 61 6d 65 20 2a 2f 0a 20 20  uence name */.  
351a0 69 6e 74 20 2a 70 4e 6f 74 4e 75 6c 6c 2c 20 20  int *pNotNull,  
351b0 20 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f              /* O
351c0 55 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 4e  UTPUT: True if N
351d0 4f 54 20 4e 55 4c 4c 20 63 6f 6e 73 74 72 61 69  OT NULL constrai
351e0 6e 74 20 65 78 69 73 74 73 20 2a 2f 0a 20 20 69  nt exists */.  i
351f0 6e 74 20 2a 70 50 72 69 6d 61 72 79 4b 65 79 2c  nt *pPrimaryKey,
35200 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4f 55             /* OU
35210 54 50 55 54 3a 20 54 72 75 65 20 69 66 20 63 6f  TPUT: True if co
35220 6c 75 6d 6e 20 70 61 72 74 20 6f 66 20 50 4b 20  lumn part of PK 
35230 2a 2f 0a 20 20 69 6e 74 20 2a 70 41 75 74 6f 69  */.  int *pAutoi
35240 6e 63 20 20 20 20 20 20 20 20 20 20 20 20 20 20  nc              
35250 20 2f 2a 20 4f 55 54 50 55 54 3a 20 54 72 75 65   /* OUTPUT: True
35260 20 69 66 20 63 6f 6c 75 6d 6e 20 69 73 20 61 75   if column is au
35270 74 6f 2d 69 6e 63 72 65 6d 65 6e 74 20 2a 2f 0a  to-increment */.
35280 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52  );../*.** CAPI3R
35290 45 46 3a 20 4c 6f 61 64 20 41 6e 20 45 78 74 65  EF: Load An Exte
352a0 6e 73 69 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 69  nsion.**.** ^Thi
352b0 73 20 69 6e 74 65 72 66 61 63 65 20 6c 6f 61 64  s interface load
352c0 73 20 61 6e 20 53 51 4c 69 74 65 20 65 78 74 65  s an SQLite exte
352d0 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79 20 66 72  nsion library fr
352e0 6f 6d 20 74 68 65 20 6e 61 6d 65 64 20 66 69 6c  om the named fil
352f0 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  e..**.** ^The sq
35300 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
35310 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
35320 20 61 74 74 65 6d 70 74 73 20 74 6f 20 6c 6f 61   attempts to loa
35330 64 20 61 6e 0a 2a 2a 20 53 51 4c 69 74 65 20 65  d an.** SQLite e
35340 78 74 65 6e 73 69 6f 6e 20 6c 69 62 72 61 72 79  xtension library
35350 20 63 6f 6e 74 61 69 6e 65 64 20 69 6e 20 74 68   contained in th
35360 65 20 66 69 6c 65 20 7a 46 69 6c 65 2e 0a 2a 2a  e file zFile..**
35370 0a 2a 2a 20 5e 54 68 65 20 65 6e 74 72 79 20 70  .** ^The entry p
35380 6f 69 6e 74 20 69 73 20 7a 50 72 6f 63 2e 0a 2a  oint is zProc..*
35390 2a 20 5e 7a 50 72 6f 63 20 6d 61 79 20 62 65 20  * ^zProc may be 
353a0 30 2c 20 69 6e 20 77 68 69 63 68 20 63 61 73 65  0, in which case
353b0 20 74 68 65 20 6e 61 6d 65 20 6f 66 20 74 68 65   the name of the
353c0 20 65 6e 74 72 79 20 70 6f 69 6e 74 0a 2a 2a 20   entry point.** 
353d0 64 65 66 61 75 6c 74 73 20 74 6f 20 22 73 71 6c  defaults to "sql
353e0 69 74 65 33 5f 65 78 74 65 6e 73 69 6f 6e 5f 69  ite3_extension_i
353f0 6e 69 74 22 2e 0a 2a 2a 20 5e 54 68 65 20 73 71  nit"..** ^The sq
35400 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
35410 73 69 6f 6e 28 29 20 69 6e 74 65 72 66 61 63 65  sion() interface
35420 20 72 65 74 75 72 6e 73 0a 2a 2a 20 5b 53 51 4c   returns.** [SQL
35430 49 54 45 5f 4f 4b 5d 20 6f 6e 20 73 75 63 63 65  ITE_OK] on succe
35440 73 73 20 61 6e 64 20 5b 53 51 4c 49 54 45 5f 45  ss and [SQLITE_E
35450 52 52 4f 52 5d 20 69 66 20 73 6f 6d 65 74 68 69  RROR] if somethi
35460 6e 67 20 67 6f 65 73 20 77 72 6f 6e 67 2e 0a 2a  ng goes wrong..*
35470 2a 20 5e 49 66 20 61 6e 20 65 72 72 6f 72 20 6f  * ^If an error o
35480 63 63 75 72 73 20 61 6e 64 20 70 7a 45 72 72 4d  ccurs and pzErrM
35490 73 67 20 69 73 20 6e 6f 74 20 30 2c 20 74 68 65  sg is not 0, the
354a0 6e 20 74 68 65 0a 2a 2a 20 5b 73 71 6c 69 74 65  n the.** [sqlite
354b0 33 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f 6e  3_load_extension
354c0 28 29 5d 20 69 6e 74 65 72 66 61 63 65 20 73 68  ()] interface sh
354d0 61 6c 6c 20 61 74 74 65 6d 70 74 20 74 6f 0a 2a  all attempt to.*
354e0 2a 20 66 69 6c 6c 20 2a 70 7a 45 72 72 4d 73 67  * fill *pzErrMsg
354f0 20 77 69 74 68 20 65 72 72 6f 72 20 6d 65 73 73   with error mess
35500 61 67 65 20 74 65 78 74 20 73 74 6f 72 65 64 20  age text stored 
35510 69 6e 20 6d 65 6d 6f 72 79 0a 2a 2a 20 6f 62 74  in memory.** obt
35520 61 69 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69  ained from [sqli
35530 74 65 33 5f 6d 61 6c 6c 6f 63 28 29 5d 2e 20 54  te3_malloc()]. T
35540 68 65 20 63 61 6c 6c 69 6e 67 20 66 75 6e 63 74  he calling funct
35550 69 6f 6e 0a 2a 2a 20 73 68 6f 75 6c 64 20 66 72  ion.** should fr
35560 65 65 20 74 68 69 73 20 6d 65 6d 6f 72 79 20 62  ee this memory b
35570 79 20 63 61 6c 6c 69 6e 67 20 5b 73 71 6c 69 74  y calling [sqlit
35580 65 33 5f 66 72 65 65 28 29 5d 2e 0a 2a 2a 0a 2a  e3_free()]..**.*
35590 2a 20 5e 45 78 74 65 6e 73 69 6f 6e 20 6c 6f 61  * ^Extension loa
355a0 64 69 6e 67 20 6d 75 73 74 20 62 65 20 65 6e 61  ding must be ena
355b0 62 6c 65 64 20 75 73 69 6e 67 0a 2a 2a 20 5b 73  bled using.** [s
355c0 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
355d0 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20  ad_extension()] 
355e0 70 72 69 6f 72 20 74 6f 20 63 61 6c 6c 69 6e 67  prior to calling
355f0 20 74 68 69 73 20 41 50 49 2c 0a 2a 2a 20 6f 74   this API,.** ot
35600 68 65 72 77 69 73 65 20 61 6e 20 65 72 72 6f 72  herwise an error
35610 20 77 69 6c 6c 20 62 65 20 72 65 74 75 72 6e 65   will be returne
35620 64 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73  d..**.** See als
35630 6f 20 74 68 65 20 5b 6c 6f 61 64 5f 65 78 74 65  o the [load_exte
35640 6e 73 69 6f 6e 28 29 20 53 51 4c 20 66 75 6e 63  nsion() SQL func
35650 74 69 6f 6e 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71  tion]..*/.int sq
35660 6c 69 74 65 33 5f 6c 6f 61 64 5f 65 78 74 65 6e  lite3_load_exten
35670 73 69 6f 6e 28 0a 20 20 73 71 6c 69 74 65 33 20  sion(.  sqlite3 
35680 2a 64 62 2c 20 20 20 20 20 20 20 20 20 20 2f 2a  *db,          /*
35690 20 4c 6f 61 64 20 74 68 65 20 65 78 74 65 6e 73   Load the extens
356a0 69 6f 6e 20 69 6e 74 6f 20 74 68 69 73 20 64 61  ion into this da
356b0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
356c0 6e 20 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61  n */.  const cha
356d0 72 20 2a 7a 46 69 6c 65 2c 20 20 20 20 2f 2a 20  r *zFile,    /* 
356e0 4e 61 6d 65 20 6f 66 20 74 68 65 20 73 68 61 72  Name of the shar
356f0 65 64 20 6c 69 62 72 61 72 79 20 63 6f 6e 74 61  ed library conta
35700 69 6e 69 6e 67 20 65 78 74 65 6e 73 69 6f 6e 20  ining extension 
35710 2a 2f 0a 20 20 63 6f 6e 73 74 20 63 68 61 72 20  */.  const char 
35720 2a 7a 50 72 6f 63 2c 20 20 20 20 2f 2a 20 45 6e  *zProc,    /* En
35730 74 72 79 20 70 6f 69 6e 74 2e 20 20 44 65 72 69  try point.  Deri
35740 76 65 64 20 66 72 6f 6d 20 7a 46 69 6c 65 20 69  ved from zFile i
35750 66 20 30 20 2a 2f 0a 20 20 63 68 61 72 20 2a 2a  f 0 */.  char **
35760 70 7a 45 72 72 4d 73 67 20 20 20 20 20 20 20 2f  pzErrMsg       /
35770 2a 20 50 75 74 20 65 72 72 6f 72 20 6d 65 73 73  * Put error mess
35780 61 67 65 20 68 65 72 65 20 69 66 20 6e 6f 74 20  age here if not 
35790 30 20 2a 2f 0a 29 3b 0a 0a 2f 2a 0a 2a 2a 20 43  0 */.);../*.** C
357a0 41 50 49 33 52 45 46 3a 20 45 6e 61 62 6c 65 20  API3REF: Enable 
357b0 4f 72 20 44 69 73 61 62 6c 65 20 45 78 74 65 6e  Or Disable Exten
357c0 73 69 6f 6e 20 4c 6f 61 64 69 6e 67 0a 2a 2a 0a  sion Loading.**.
357d0 2a 2a 20 5e 53 6f 20 61 73 20 6e 6f 74 20 74 6f  ** ^So as not to
357e0 20 6f 70 65 6e 20 73 65 63 75 72 69 74 79 20 68   open security h
357f0 6f 6c 65 73 20 69 6e 20 6f 6c 64 65 72 20 61 70  oles in older ap
35800 70 6c 69 63 61 74 69 6f 6e 73 20 74 68 61 74 20  plications that 
35810 61 72 65 0a 2a 2a 20 75 6e 70 72 65 70 61 72 65  are.** unprepare
35820 64 20 74 6f 20 64 65 61 6c 20 77 69 74 68 20 65  d to deal with e
35830 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e 67  xtension loading
35840 2c 20 61 6e 64 20 61 73 20 61 20 6d 65 61 6e 73  , and as a means
35850 20 6f 66 20 64 69 73 61 62 6c 69 6e 67 0a 2a 2a   of disabling.**
35860 20 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69   extension loadi
35870 6e 67 20 77 68 69 6c 65 20 65 76 61 6c 75 61 74  ng while evaluat
35880 69 6e 67 20 75 73 65 72 2d 65 6e 74 65 72 65 64  ing user-entered
35890 20 53 51 4c 2c 20 74 68 65 20 66 6f 6c 6c 6f 77   SQL, the follow
358a0 69 6e 67 20 41 50 49 0a 2a 2a 20 69 73 20 70 72  ing API.** is pr
358b0 6f 76 69 64 65 64 20 74 6f 20 74 75 72 6e 20 74  ovided to turn t
358c0 68 65 20 5b 73 71 6c 69 74 65 33 5f 6c 6f 61 64  he [sqlite3_load
358d0 5f 65 78 74 65 6e 73 69 6f 6e 28 29 5d 20 6d 65  _extension()] me
358e0 63 68 61 6e 69 73 6d 20 6f 6e 20 61 6e 64 20 6f  chanism on and o
358f0 66 66 2e 0a 2a 2a 0a 2a 2a 20 5e 45 78 74 65 6e  ff..**.** ^Exten
35900 73 69 6f 6e 20 6c 6f 61 64 69 6e 67 20 69 73 20  sion loading is 
35910 6f 66 66 20 62 79 20 64 65 66 61 75 6c 74 2e 20  off by default. 
35920 53 65 65 20 74 69 63 6b 65 74 20 23 31 38 36 33  See ticket #1863
35930 2e 0a 2a 2a 20 5e 43 61 6c 6c 20 74 68 65 20 73  ..** ^Call the s
35940 71 6c 69 74 65 33 5f 65 6e 61 62 6c 65 5f 6c 6f  qlite3_enable_lo
35950 61 64 5f 65 78 74 65 6e 73 69 6f 6e 28 29 20 72  ad_extension() r
35960 6f 75 74 69 6e 65 20 77 69 74 68 20 6f 6e 6f 66  outine with onof
35970 66 3d 3d 31 0a 2a 2a 20 74 6f 20 74 75 72 6e 20  f==1.** to turn 
35980 65 78 74 65 6e 73 69 6f 6e 20 6c 6f 61 64 69 6e  extension loadin
35990 67 20 6f 6e 20 61 6e 64 20 63 61 6c 6c 20 69 74  g on and call it
359a0 20 77 69 74 68 20 6f 6e 6f 66 66 3d 3d 30 20 74   with onoff==0 t
359b0 6f 20 74 75 72 6e 0a 2a 2a 20 69 74 20 62 61 63  o turn.** it bac
359c0 6b 20 6f 66 66 20 61 67 61 69 6e 2e 0a 2a 2f 0a  k off again..*/.
359d0 69 6e 74 20 73 71 6c 69 74 65 33 5f 65 6e 61 62  int sqlite3_enab
359e0 6c 65 5f 6c 6f 61 64 5f 65 78 74 65 6e 73 69 6f  le_load_extensio
359f0 6e 28 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 69  n(sqlite3 *db, i
35a00 6e 74 20 6f 6e 6f 66 66 29 3b 0a 0a 2f 2a 0a 2a  nt onoff);../*.*
35a10 2a 20 43 41 50 49 33 52 45 46 3a 20 41 75 74 6f  * CAPI3REF: Auto
35a20 6d 61 74 69 63 61 6c 6c 79 20 4c 6f 61 64 20 53  matically Load S
35a30 74 61 74 69 63 61 6c 6c 79 20 4c 69 6e 6b 65 64  tatically Linked
35a40 20 45 78 74 65 6e 73 69 6f 6e 73 0a 2a 2a 0a 2a   Extensions.**.*
35a50 2a 20 5e 54 68 69 73 20 69 6e 74 65 72 66 61 63  * ^This interfac
35a60 65 20 63 61 75 73 65 73 20 74 68 65 20 78 45 6e  e causes the xEn
35a70 74 72 79 50 6f 69 6e 74 28 29 20 66 75 6e 63 74  tryPoint() funct
35a80 69 6f 6e 20 74 6f 20 62 65 20 69 6e 76 6f 6b 65  ion to be invoke
35a90 64 20 66 6f 72 0a 2a 2a 20 65 61 63 68 20 6e 65  d for.** each ne
35aa0 77 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e 6e  w [database conn
35ab0 65 63 74 69 6f 6e 5d 20 74 68 61 74 20 69 73 20  ection] that is 
35ac0 63 72 65 61 74 65 64 2e 20 20 54 68 65 20 69 64  created.  The id
35ad0 65 61 20 68 65 72 65 20 69 73 20 74 68 61 74 0a  ea here is that.
35ae0 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29  ** xEntryPoint()
35af0 20 69 73 20 74 68 65 20 65 6e 74 72 79 20 70 6f   is the entry po
35b00 69 6e 74 20 66 6f 72 20 61 20 73 74 61 74 69 63  int for a static
35b10 61 6c 6c 79 20 6c 69 6e 6b 65 64 20 53 51 4c 69  ally linked SQLi
35b20 74 65 20 65 78 74 65 6e 73 69 6f 6e 0a 2a 2a 20  te extension.** 
35b30 74 68 61 74 20 69 73 20 74 6f 20 62 65 20 61 75  that is to be au
35b40 74 6f 6d 61 74 69 63 61 6c 6c 79 20 6c 6f 61 64  tomatically load
35b50 65 64 20 69 6e 74 6f 20 61 6c 6c 20 6e 65 77 20  ed into all new 
35b60 64 61 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74  database connect
35b70 69 6f 6e 73 2e 0a 2a 2a 0a 2a 2a 20 5e 28 45 76  ions..**.** ^(Ev
35b80 65 6e 20 74 68 6f 75 67 68 20 74 68 65 20 66 75  en though the fu
35b90 6e 63 74 69 6f 6e 20 70 72 6f 74 6f 74 79 70 65  nction prototype
35ba0 20 73 68 6f 77 73 20 74 68 61 74 20 78 45 6e 74   shows that xEnt
35bb0 72 79 50 6f 69 6e 74 28 29 20 74 61 6b 65 73 0a  ryPoint() takes.
35bc0 2a 2a 20 6e 6f 20 61 72 67 75 6d 65 6e 74 73 20  ** no arguments 
35bd0 61 6e 64 20 72 65 74 75 72 6e 73 20 76 6f 69 64  and returns void
35be0 2c 20 53 51 4c 69 74 65 20 69 6e 76 6f 6b 65 73  , SQLite invokes
35bf0 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77   xEntryPoint() w
35c00 69 74 68 20 74 68 72 65 65 0a 2a 2a 20 61 72 67  ith three.** arg
35c10 75 6d 65 6e 74 73 20 61 6e 64 20 65 78 70 65 63  uments and expec
35c20 74 73 20 61 6e 64 20 69 6e 74 65 67 65 72 20 72  ts and integer r
35c30 65 73 75 6c 74 20 61 73 20 69 66 20 74 68 65 20  esult as if the 
35c40 73 69 67 6e 61 74 75 72 65 20 6f 66 20 74 68 65  signature of the
35c50 0a 2a 2a 20 65 6e 74 72 79 20 70 6f 69 6e 74 20  .** entry point 
35c60 77 68 65 72 65 20 61 73 20 66 6f 6c 6c 6f 77 73  where as follows
35c70 3a 0a 2a 2a 0a 2a 2a 20 3c 62 6c 6f 63 6b 71 75  :.**.** <blockqu
35c80 6f 74 65 3e 3c 70 72 65 3e 0a 2a 2a 20 26 6e 62  ote><pre>.** &nb
35c90 73 70 3b 20 20 69 6e 74 20 78 45 6e 74 72 79 50  sp;  int xEntryP
35ca0 6f 69 6e 74 28 0a 2a 2a 20 26 6e 62 73 70 3b 20  oint(.** &nbsp; 
35cb0 20 20 20 73 71 6c 69 74 65 33 20 2a 64 62 2c 0a     sqlite3 *db,.
35cc0 2a 2a 20 26 6e 62 73 70 3b 20 20 20 20 63 6f 6e  ** &nbsp;    con
35cd0 73 74 20 63 68 61 72 20 2a 2a 70 7a 45 72 72 4d  st char **pzErrM
35ce0 73 67 2c 0a 2a 2a 20 26 6e 62 73 70 3b 20 20 20  sg,.** &nbsp;   
35cf0 20 63 6f 6e 73 74 20 73 74 72 75 63 74 20 73 71   const struct sq
35d00 6c 69 74 65 33 5f 61 70 69 5f 72 6f 75 74 69 6e  lite3_api_routin
35d10 65 73 20 2a 70 54 68 75 6e 6b 0a 2a 2a 20 26 6e  es *pThunk.** &n
35d20 62 73 70 3b 20 20 29 3b 0a 2a 2a 20 3c 2f 70 72  bsp;  );.** </pr
35d30 65 3e 3c 2f 62 6c 6f 63 6b 71 75 6f 74 65 3e 29  e></blockquote>)
35d40 5e 0a 2a 2a 0a 2a 2a 20 49 66 20 74 68 65 20 78  ^.**.** If the x
35d50 45 6e 74 72 79 50 6f 69 6e 74 20 72 6f 75 74 69  EntryPoint routi
35d60 6e 65 20 65 6e 63 6f 75 6e 74 65 72 73 20 61 6e  ne encounters an
35d70 20 65 72 72 6f 72 2c 20 69 74 20 73 68 6f 75 6c   error, it shoul
35d80 64 20 6d 61 6b 65 20 2a 70 7a 45 72 72 4d 73 67  d make *pzErrMsg
35d90 0a 2a 2a 20 70 6f 69 6e 74 20 74 6f 20 61 6e 20  .** point to an 
35da0 61 70 70 72 6f 70 72 69 61 74 65 20 65 72 72 6f  appropriate erro
35db0 72 20 6d 65 73 73 61 67 65 20 28 6f 62 74 61 69  r message (obtai
35dc0 6e 65 64 20 66 72 6f 6d 20 5b 73 71 6c 69 74 65  ned from [sqlite
35dd0 33 5f 6d 70 72 69 6e 74 66 28 29 5d 29 0a 2a 2a  3_mprintf()]).**
35de0 20 61 6e 64 20 72 65 74 75 72 6e 20 61 6e 20 61   and return an a
35df0 70 70 72 6f 70 72 69 61 74 65 20 5b 65 72 72 6f  ppropriate [erro
35e00 72 20 63 6f 64 65 5d 2e 20 20 5e 53 51 4c 69 74  r code].  ^SQLit
35e10 65 20 65 6e 73 75 72 65 73 20 74 68 61 74 20 2a  e ensures that *
35e20 70 7a 45 72 72 4d 73 67 0a 2a 2a 20 69 73 20 4e  pzErrMsg.** is N
35e30 55 4c 4c 20 62 65 66 6f 72 65 20 63 61 6c 6c 69  ULL before calli
35e40 6e 67 20 74 68 65 20 78 45 6e 74 72 79 50 6f 69  ng the xEntryPoi
35e50 6e 74 28 29 2e 20 20 5e 53 51 4c 69 74 65 20 77  nt().  ^SQLite w
35e60 69 6c 6c 20 69 6e 76 6f 6b 65 0a 2a 2a 20 5b 73  ill invoke.** [s
35e70 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d 20 6f  qlite3_free()] o
35e80 6e 20 2a 70 7a 45 72 72 4d 73 67 20 61 66 74 65  n *pzErrMsg afte
35e90 72 20 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20  r xEntryPoint() 
35ea0 72 65 74 75 72 6e 73 2e 20 20 5e 49 66 20 61 6e  returns.  ^If an
35eb0 79 0a 2a 2a 20 78 45 6e 74 72 79 50 6f 69 6e 74  y.** xEntryPoint
35ec0 28 29 20 72 65 74 75 72 6e 73 20 61 6e 20 65 72  () returns an er
35ed0 72 6f 72 2c 20 74 68 65 20 5b 73 71 6c 69 74 65  ror, the [sqlite
35ee0 33 5f 6f 70 65 6e 28 29 5d 2c 20 5b 73 71 6c 69  3_open()], [sqli
35ef0 74 65 33 5f 6f 70 65 6e 31 36 28 29 5d 2c 0a 2a  te3_open16()],.*
35f00 2a 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f 6f 70  * or [sqlite3_op
35f10 65 6e 5f 76 32 28 29 5d 20 63 61 6c 6c 20 74 68  en_v2()] call th
35f20 61 74 20 70 72 6f 76 6f 6b 65 64 20 74 68 65 20  at provoked the 
35f30 78 45 6e 74 72 79 50 6f 69 6e 74 28 29 20 77 69  xEntryPoint() wi
35f40 6c 6c 20 66 61 69 6c 2e 0a 2a 2a 0a 2a 2a 20 5e  ll fail..**.** ^
35f50 43 61 6c 6c 69 6e 67 20 73 71 6c 69 74 65 33 5f  Calling sqlite3_
35f60 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28 58  auto_extension(X
35f70 29 20 77 69 74 68 20 61 6e 20 65 6e 74 72 79 20  ) with an entry 
35f80 70 6f 69 6e 74 20 58 20 74 68 61 74 20 69 73 20  point X that is 
35f90 61 6c 72 65 61 64 79 0a 2a 2a 20 6f 6e 20 74 68  already.** on th
35fa0 65 20 6c 69 73 74 20 6f 66 20 61 75 74 6f 6d 61  e list of automa
35fb0 74 69 63 20 65 78 74 65 6e 73 69 6f 6e 73 20 69  tic extensions i
35fc0 73 20 61 20 68 61 72 6d 6c 65 73 73 20 6e 6f 2d  s a harmless no-
35fd0 6f 70 2e 20 5e 4e 6f 20 65 6e 74 72 79 20 70 6f  op. ^No entry po
35fe0 69 6e 74 0a 2a 2a 20 77 69 6c 6c 20 62 65 20 63  int.** will be c
35ff0 61 6c 6c 65 64 20 6d 6f 72 65 20 74 68 61 6e 20  alled more than 
36000 6f 6e 63 65 20 66 6f 72 20 65 61 63 68 20 64 61  once for each da
36010 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
36020 6e 20 74 68 61 74 20 69 73 20 6f 70 65 6e 65 64  n that is opened
36030 2e 0a 2a 2a 0a 2a 2a 20 53 65 65 20 61 6c 73 6f  ..**.** See also
36040 3a 20 5b 73 71 6c 69 74 65 33 5f 72 65 73 65 74  : [sqlite3_reset
36050 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
36060 29 5d 2e 0a 2a 2f 0a 69 6e 74 20 73 71 6c 69 74  )]..*/.int sqlit
36070 65 33 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f  e3_auto_extensio
36080 6e 28 76 6f 69 64 20 28 2a 78 45 6e 74 72 79 50  n(void (*xEntryP
36090 6f 69 6e 74 29 28 76 6f 69 64 29 29 3b 0a 0a 2f  oint)(void));../
360a0 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 52  *.** CAPI3REF: R
360b0 65 73 65 74 20 41 75 74 6f 6d 61 74 69 63 20 45  eset Automatic E
360c0 78 74 65 6e 73 69 6f 6e 20 4c 6f 61 64 69 6e 67  xtension Loading
360d0 0a 2a 2a 0a 2a 2a 20 5e 54 68 69 73 20 69 6e 74  .**.** ^This int
360e0 65 72 66 61 63 65 20 64 69 73 61 62 6c 65 73 20  erface disables 
360f0 61 6c 6c 20 61 75 74 6f 6d 61 74 69 63 20 65 78  all automatic ex
36100 74 65 6e 73 69 6f 6e 73 20 70 72 65 76 69 6f 75  tensions previou
36110 73 6c 79 0a 2a 2a 20 72 65 67 69 73 74 65 72 65  sly.** registere
36120 64 20 75 73 69 6e 67 20 5b 73 71 6c 69 74 65 33  d using [sqlite3
36130 5f 61 75 74 6f 5f 65 78 74 65 6e 73 69 6f 6e 28  _auto_extension(
36140 29 5d 2e 0a 2a 2f 0a 76 6f 69 64 20 73 71 6c 69  )]..*/.void sqli
36150 74 65 33 5f 72 65 73 65 74 5f 61 75 74 6f 5f 65  te3_reset_auto_e
36160 78 74 65 6e 73 69 6f 6e 28 76 6f 69 64 29 3b 0a  xtension(void);.
36170 0a 2f 2a 0a 2a 2a 20 54 68 65 20 69 6e 74 65 72  ./*.** The inter
36180 66 61 63 65 20 74 6f 20 74 68 65 20 76 69 72 74  face to the virt
36190 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
361a0 69 73 6d 20 69 73 20 63 75 72 72 65 6e 74 6c 79  ism is currently
361b0 20 63 6f 6e 73 69 64 65 72 65 64 0a 2a 2a 20 74   considered.** t
361c0 6f 20 62 65 20 65 78 70 65 72 69 6d 65 6e 74 61  o be experimenta
361d0 6c 2e 20 20 54 68 65 20 69 6e 74 65 72 66 61 63  l.  The interfac
361e0 65 20 6d 69 67 68 74 20 63 68 61 6e 67 65 20 69  e might change i
361f0 6e 20 69 6e 63 6f 6d 70 61 74 69 62 6c 65 20 77  n incompatible w
36200 61 79 73 2e 0a 2a 2a 20 49 66 20 74 68 69 73 20  ays..** If this 
36210 69 73 20 61 20 70 72 6f 62 6c 65 6d 20 66 6f 72  is a problem for
36220 20 79 6f 75 2c 20 64 6f 20 6e 6f 74 20 75 73 65   you, do not use
36230 20 74 68 65 20 69 6e 74 65 72 66 61 63 65 20 61   the interface a
36240 74 20 74 68 69 73 20 74 69 6d 65 2e 0a 2a 2a 0a  t this time..**.
36250 2a 2a 20 57 68 65 6e 20 74 68 65 20 76 69 72 74  ** When the virt
36260 75 61 6c 2d 74 61 62 6c 65 20 6d 65 63 68 61 6e  ual-table mechan
36270 69 73 6d 20 73 74 61 62 69 6c 69 7a 65 73 2c 20  ism stabilizes, 
36280 77 65 20 77 69 6c 6c 20 64 65 63 6c 61 72 65 20  we will declare 
36290 74 68 65 0a 2a 2a 20 69 6e 74 65 72 66 61 63 65  the.** interface
362a0 20 66 69 78 65 64 2c 20 73 75 70 70 6f 72 74 20   fixed, support 
362b0 69 74 20 69 6e 64 65 66 69 6e 69 74 65 6c 79 2c  it indefinitely,
362c0 20 61 6e 64 20 72 65 6d 6f 76 65 20 74 68 69 73   and remove this
362d0 20 63 6f 6d 6d 65 6e 74 2e 0a 2a 2f 0a 0a 2f 2a   comment..*/../*
362e0 0a 2a 2a 20 53 74 72 75 63 74 75 72 65 73 20 75  .** Structures u
362f0 73 65 64 20 62 79 20 74 68 65 20 76 69 72 74 75  sed by the virtu
36300 61 6c 20 74 61 62 6c 65 20 69 6e 74 65 72 66 61  al table interfa
36310 63 65 0a 2a 2f 0a 74 79 70 65 64 65 66 20 73 74  ce.*/.typedef st
36320 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
36330 62 20 73 71 6c 69 74 65 33 5f 76 74 61 62 3b 0a  b sqlite3_vtab;.
36340 74 79 70 65 64 65 66 20 73 74 72 75 63 74 20 73  typedef struct s
36350 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66  qlite3_index_inf
36360 6f 20 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f  o sqlite3_index_
36370 69 6e 66 6f 3b 0a 74 79 70 65 64 65 66 20 73 74  info;.typedef st
36380 72 75 63 74 20 73 71 6c 69 74 65 33 5f 76 74 61  ruct sqlite3_vta
36390 62 5f 63 75 72 73 6f 72 20 73 71 6c 69 74 65 33  b_cursor sqlite3
363a0 5f 76 74 61 62 5f 63 75 72 73 6f 72 3b 0a 74 79  _vtab_cursor;.ty
363b0 70 65 64 65 66 20 73 74 72 75 63 74 20 73 71 6c  pedef struct sql
363c0 69 74 65 33 5f 6d 6f 64 75 6c 65 20 73 71 6c 69  ite3_module sqli
363d0 74 65 33 5f 6d 6f 64 75 6c 65 3b 0a 0a 2f 2a 0a  te3_module;../*.
363e0 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56 69 72  ** CAPI3REF: Vir
363f0 74 75 61 6c 20 54 61 62 6c 65 20 4f 62 6a 65 63  tual Table Objec
36400 74 0a 2a 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73  t.** KEYWORDS: s
36410 71 6c 69 74 65 33 5f 6d 6f 64 75 6c 65 20 7b 76  qlite3_module {v
36420 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
36430 75 6c 65 7d 0a 2a 2a 0a 2a 2a 20 54 68 69 73 20  ule}.**.** This 
36440 73 74 72 75 63 74 75 72 65 2c 20 73 6f 6d 65 74  structure, somet
36450 69 6d 65 73 20 63 61 6c 6c 65 64 20 61 20 22 76  imes called a "v
36460 69 72 74 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64  irtual table mod
36470 75 6c 65 22 2c 20 0a 2a 2a 20 64 65 66 69 6e 65  ule", .** define
36480 73 20 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61  s the implementa
36490 74 69 6f 6e 20 6f 66 20 61 20 5b 76 69 72 74 75  tion of a [virtu
364a0 61 6c 20 74 61 62 6c 65 73 5d 2e 20 20 0a 2a 2a  al tables].  .**
364b0 20 54 68 69 73 20 73 74 72 75 63 74 75 72 65 20   This structure 
364c0 63 6f 6e 73 69 73 74 73 20 6d 6f 73 74 6c 79 20  consists mostly 
364d0 6f 66 20 6d 65 74 68 6f 64 73 20 66 6f 72 20 74  of methods for t
364e0 68 65 20 6d 6f 64 75 6c 65 2e 0a 2a 2a 0a 2a 2a  he module..**.**
364f0 20 5e 41 20 76 69 72 74 75 61 6c 20 74 61 62 6c   ^A virtual tabl
36500 65 20 6d 6f 64 75 6c 65 20 69 73 20 63 72 65 61  e module is crea
36510 74 65 64 20 62 79 20 66 69 6c 6c 69 6e 67 20 69  ted by filling i
36520 6e 20 61 20 70 65 72 73 69 73 74 65 6e 74 0a 2a  n a persistent.*
36530 2a 20 69 6e 73 74 61 6e 63 65 20 6f 66 20 74 68  * instance of th
36540 69 73 20 73 74 72 75 63 74 75 72 65 20 61 6e 64  is structure and
36550 20 70 61 73 73 69 6e 67 20 61 20 70 6f 69 6e 74   passing a point
36560 65 72 20 74 6f 20 74 68 61 74 20 69 6e 73 74 61  er to that insta
36570 6e 63 65 0a 2a 2a 20 74 6f 20 5b 73 71 6c 69 74  nce.** to [sqlit
36580 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65  e3_create_module
36590 28 29 5d 20 6f 72 20 5b 73 71 6c 69 74 65 33 5f  ()] or [sqlite3_
365a0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
365b0 28 29 5d 2e 0a 2a 2a 20 5e 54 68 65 20 72 65 67  ()]..** ^The reg
365c0 69 73 74 72 61 74 69 6f 6e 20 72 65 6d 61 69 6e  istration remain
365d0 73 20 76 61 6c 69 64 20 75 6e 74 69 6c 20 69 74  s valid until it
365e0 20 69 73 20 72 65 70 6c 61 63 65 64 20 62 79 20   is replaced by 
365f0 61 20 64 69 66 66 65 72 65 6e 74 0a 2a 2a 20 6d  a different.** m
36600 6f 64 75 6c 65 20 6f 72 20 75 6e 74 69 6c 20 74  odule or until t
36610 68 65 20 5b 64 61 74 61 62 61 73 65 20 63 6f 6e  he [database con
36620 6e 65 63 74 69 6f 6e 5d 20 63 6c 6f 73 65 73 2e  nection] closes.
36630 20 20 54 68 65 20 63 6f 6e 74 65 6e 74 0a 2a 2a    The content.**
36640 20 6f 66 20 74 68 69 73 20 73 74 72 75 63 74 75   of this structu
36650 72 65 20 6d 75 73 74 20 6e 6f 74 20 63 68 61 6e  re must not chan
36660 67 65 20 77 68 69 6c 65 20 69 74 20 69 73 20 72  ge while it is r
36670 65 67 69 73 74 65 72 65 64 20 77 69 74 68 0a 2a  egistered with.*
36680 2a 20 61 6e 79 20 64 61 74 61 62 61 73 65 20 63  * any database c
36690 6f 6e 6e 65 63 74 69 6f 6e 2e 0a 2a 2f 0a 73 74  onnection..*/.st
366a0 72 75 63 74 20 73 71 6c 69 74 65 33 5f 6d 6f 64  ruct sqlite3_mod
366b0 75 6c 65 20 7b 0a 20 20 69 6e 74 20 69 56 65 72  ule {.  int iVer
366c0 73 69 6f 6e 3b 0a 20 20 69 6e 74 20 28 2a 78 43  sion;.  int (*xC
366d0 72 65 61 74 65 29 28 73 71 6c 69 74 65 33 2a 2c  reate)(sqlite3*,
366e0 20 76 6f 69 64 20 2a 70 41 75 78 2c 0a 20 20 20   void *pAux,.   
366f0 20 20 20 20 20 20 20 20 20 20 20 20 69 6e 74 20              int 
36700 61 72 67 63 2c 20 63 6f 6e 73 74 20 63 68 61 72  argc, const char
36710 20 2a 63 6f 6e 73 74 2a 61 72 67 76 2c 0a 20 20   *const*argv,.  
36720 20 20 20 20 20 20 20 20 20 20 20 20 20 73 71 6c               sql
36730 69 74 65 33 5f 76 74 61 62 20 2a 2a 70 70 56 54  ite3_vtab **ppVT
36740 61 62 2c 20 63 68 61 72 2a 2a 29 3b 0a 20 20 69  ab, char**);.  i
36750 6e 74 20 28 2a 78 43 6f 6e 6e 65 63 74 29 28 73  nt (*xConnect)(s
36760 71 6c 69 74 65 33 2a 2c 20 76 6f 69 64 20 2a 70  qlite3*, void *p
36770 41 75 78 2c 0a 20 20 20 20 20 20 20 20 20 20 20  Aux,.           
36780 20 20 20 20 69 6e 74 20 61 72 67 63 2c 20 63 6f      int argc, co
36790 6e 73 74 20 63 68 61 72 20 2a 63 6f 6e 73 74 2a  nst char *const*
367a0 61 72 67 76 2c 0a 20 20 20 20 20 20 20 20 20 20  argv,.          
367b0 20 20 20 20 20 73 71 6c 69 74 65 33 5f 76 74 61       sqlite3_vta
367c0 62 20 2a 2a 70 70 56 54 61 62 2c 20 63 68 61 72  b **ppVTab, char
367d0 2a 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 42 65  **);.  int (*xBe
367e0 73 74 49 6e 64 65 78 29 28 73 71 6c 69 74 65 33  stIndex)(sqlite3
367f0 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20 73 71  _vtab *pVTab, sq
36800 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f  lite3_index_info
36810 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 44 69 73  *);.  int (*xDis
36820 63 6f 6e 6e 65 63 74 29 28 73 71 6c 69 74 65 33  connect)(sqlite3
36830 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
36840 20 69 6e 74 20 28 2a 78 44 65 73 74 72 6f 79 29   int (*xDestroy)
36850 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70  (sqlite3_vtab *p
36860 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a 78  VTab);.  int (*x
36870 4f 70 65 6e 29 28 73 71 6c 69 74 65 33 5f 76 74  Open)(sqlite3_vt
36880 61 62 20 2a 70 56 54 61 62 2c 20 73 71 6c 69 74  ab *pVTab, sqlit
36890 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 20 2a  e3_vtab_cursor *
368a0 2a 70 70 43 75 72 73 6f 72 29 3b 0a 20 20 69 6e  *ppCursor);.  in
368b0 74 20 28 2a 78 43 6c 6f 73 65 29 28 73 71 6c 69  t (*xClose)(sqli
368c0 74 65 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a  te3_vtab_cursor*
368d0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 46 69 6c 74  );.  int (*xFilt
368e0 65 72 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  er)(sqlite3_vtab
368f0 5f 63 75 72 73 6f 72 2a 2c 20 69 6e 74 20 69 64  _cursor*, int id
36900 78 4e 75 6d 2c 20 63 6f 6e 73 74 20 63 68 61 72  xNum, const char
36910 20 2a 69 64 78 53 74 72 2c 0a 20 20 20 20 20 20   *idxStr,.      
36920 20 20 20 20 20 20 20 20 20 20 69 6e 74 20 61 72            int ar
36930 67 63 2c 20 73 71 6c 69 74 65 33 5f 76 61 6c 75  gc, sqlite3_valu
36940 65 20 2a 2a 61 72 67 76 29 3b 0a 20 20 69 6e 74  e **argv);.  int
36950 20 28 2a 78 4e 65 78 74 29 28 73 71 6c 69 74 65   (*xNext)(sqlite
36960 33 5f 76 74 61 62 5f 63 75 72 73 6f 72 2a 29 3b  3_vtab_cursor*);
36970 0a 20 20 69 6e 74 20 28 2a 78 45 6f 66 29 28 73  .  int (*xEof)(s
36980 71 6c 69 74 65 33 5f 76 74 61 62 5f 63 75 72 73  qlite3_vtab_curs
36990 6f 72 2a 29 3b 0a 20 20 69 6e 74 20 28 2a 78 43  or*);.  int (*xC
369a0 6f 6c 75 6d 6e 29 28 73 71 6c 69 74 65 33 5f 76  olumn)(sqlite3_v
369b0 74 61 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c  tab_cursor*, sql
369c0 69 74 65 33 5f 63 6f 6e 74 65 78 74 2a 2c 20 69  ite3_context*, i
369d0 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f  nt);.  int (*xRo
369e0 77 69 64 29 28 73 71 6c 69 74 65 33 5f 76 74 61  wid)(sqlite3_vta
369f0 62 5f 63 75 72 73 6f 72 2a 2c 20 73 71 6c 69 74  b_cursor*, sqlit
36a00 65 33 5f 69 6e 74 36 34 20 2a 70 52 6f 77 69 64  e3_int64 *pRowid
36a10 29 3b 0a 20 20 69 6e 74 20 28 2a 78 55 70 64 61  );.  int (*xUpda
36a20 74 65 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62  te)(sqlite3_vtab
36a30 20 2a 2c 20 69 6e 74 2c 20 73 71 6c 69 74 65 33   *, int, sqlite3
36a40 5f 76 61 6c 75 65 20 2a 2a 2c 20 73 71 6c 69 74  _value **, sqlit
36a50 65 33 5f 69 6e 74 36 34 20 2a 29 3b 0a 20 20 69  e3_int64 *);.  i
36a60 6e 74 20 28 2a 78 42 65 67 69 6e 29 28 73 71 6c  nt (*xBegin)(sql
36a70 69 74 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62  ite3_vtab *pVTab
36a80 29 3b 0a 20 20 69 6e 74 20 28 2a 78 53 79 6e 63  );.  int (*xSync
36a90 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
36aa0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
36ab0 78 43 6f 6d 6d 69 74 29 28 73 71 6c 69 74 65 33  xCommit)(sqlite3
36ac0 5f 76 74 61 62 20 2a 70 56 54 61 62 29 3b 0a 20  _vtab *pVTab);. 
36ad0 20 69 6e 74 20 28 2a 78 52 6f 6c 6c 62 61 63 6b   int (*xRollback
36ae0 29 28 73 71 6c 69 74 65 33 5f 76 74 61 62 20 2a  )(sqlite3_vtab *
36af0 70 56 54 61 62 29 3b 0a 20 20 69 6e 74 20 28 2a  pVTab);.  int (*
36b00 78 46 69 6e 64 46 75 6e 63 74 69 6f 6e 29 28 73  xFindFunction)(s
36b10 71 6c 69 74 65 33 5f 76 74 61 62 20 2a 70 56 74  qlite3_vtab *pVt
36b20 61 62 2c 20 69 6e 74 20 6e 41 72 67 2c 20 63 6f  ab, int nArg, co
36b30 6e 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c  nst char *zName,
36b40 0a 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20  .               
36b50 20 20 20 20 20 20 20 20 76 6f 69 64 20 28 2a 2a          void (**
36b60 70 78 46 75 6e 63 29 28 73 71 6c 69 74 65 33 5f  pxFunc)(sqlite3_
36b70 63 6f 6e 74 65 78 74 2a 2c 69 6e 74 2c 73 71 6c  context*,int,sql
36b80 69 74 65 33 5f 76 61 6c 75 65 2a 2a 29 2c 0a 20  ite3_value**),. 
36b90 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20 20                  
36ba0 20 20 20 20 20 20 76 6f 69 64 20 2a 2a 70 70 41        void **ppA
36bb0 72 67 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 65  rg);.  int (*xRe
36bc0 6e 61 6d 65 29 28 73 71 6c 69 74 65 33 5f 76 74  name)(sqlite3_vt
36bd0 61 62 20 2a 70 56 74 61 62 2c 20 63 6f 6e 73 74  ab *pVtab, const
36be0 20 63 68 61 72 20 2a 7a 4e 65 77 29 3b 0a 20 20   char *zNew);.  
36bf0 2f 2a 20 54 68 65 20 6d 65 74 68 6f 64 73 20 61  /* The methods a
36c00 62 6f 76 65 20 61 72 65 20 69 6e 20 76 65 72 73  bove are in vers
36c10 69 6f 6e 20 31 20 6f 66 20 74 68 65 20 73 71 6c  ion 1 of the sql
36c20 69 74 65 5f 6d 6f 64 75 6c 65 20 6f 62 6a 65 63  ite_module objec
36c30 74 2e 20 54 68 6f 73 65 20 0a 20 20 2a 2a 20 62  t. Those .  ** b
36c40 65 6c 6f 77 20 61 72 65 20 66 6f 72 20 76 65 72  elow are for ver
36c50 73 69 6f 6e 20 32 20 61 6e 64 20 67 72 65 61 74  sion 2 and great
36c60 65 72 2e 20 2a 2f 0a 20 20 69 6e 74 20 28 2a 78  er. */.  int (*x
36c70 53 61 76 65 70 6f 69 6e 74 29 28 73 71 6c 69 74  Savepoint)(sqlit
36c80 65 33 5f 76 74 61 62 20 2a 70 56 54 61 62 2c 20  e3_vtab *pVTab, 
36c90 69 6e 74 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52  int);.  int (*xR
36ca0 65 6c 65 61 73 65 29 28 73 71 6c 69 74 65 33 5f  elease)(sqlite3_
36cb0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 69 6e 74  vtab *pVTab, int
36cc0 29 3b 0a 20 20 69 6e 74 20 28 2a 78 52 6f 6c 6c  );.  int (*xRoll
36cd0 62 61 63 6b 54 6f 29 28 73 71 6c 69 74 65 33 5f  backTo)(sqlite3_
36ce0 76 74 61 62 20 2a 70 56 54 61 62 2c 20 69 6e 74  vtab *pVTab, int
36cf0 29 3b 0a 7d 3b 0a 0a 2f 2a 0a 2a 2a 20 43 41 50  );.};../*.** CAP
36d00 49 33 52 45 46 3a 20 56 69 72 74 75 61 6c 20 54  I3REF: Virtual T
36d10 61 62 6c 65 20 49 6e 64 65 78 69 6e 67 20 49 6e  able Indexing In
36d20 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a 20 4b 45 59  formation.** KEY
36d30 57 4f 52 44 53 3a 20 73 71 6c 69 74 65 33 5f 69  WORDS: sqlite3_i
36d40 6e 64 65 78 5f 69 6e 66 6f 0a 2a 2a 0a 2a 2a 20  ndex_info.**.** 
36d50 54 68 65 20 73 71 6c 69 74 65 33 5f 69 6e 64 65  The sqlite3_inde
36d60 78 5f 69 6e 66 6f 20 73 74 72 75 63 74 75 72 65  x_info structure
36d70 20 61 6e 64 20 69 74 73 20 73 75 62 73 74 72 75   and its substru
36d80 63 74 75 72 65 73 20 69 73 20 75 73 65 64 20 61  ctures is used a
36d90 73 20 70 61 72 74 0a 2a 2a 20 6f 66 20 74 68 65  s part.** of the
36da0 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
36db0 20 69 6e 74 65 72 66 61 63 65 20 74 6f 0a 2a 2a   interface to.**
36dc0 20 70 61 73 73 20 69 6e 66 6f 72 6d 61 74 69 6f   pass informatio
36dd0 6e 20 69 6e 74 6f 20 61 6e 64 20 72 65 63 65 69  n into and recei
36de0 76 65 20 74 68 65 20 72 65 70 6c 79 20 66 72 6f  ve the reply fro
36df0 6d 20 74 68 65 20 5b 78 42 65 73 74 49 6e 64 65  m the [xBestInde
36e00 78 5d 0a 2a 2a 20 6d 65 74 68 6f 64 20 6f 66 20  x].** method of 
36e10 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65  a [virtual table
36e20 20 6d 6f 64 75 6c 65 5d 2e 20 20 54 68 65 20 66   module].  The f
36e30 69 65 6c 64 73 20 75 6e 64 65 72 20 2a 2a 49 6e  ields under **In
36e40 70 75 74 73 2a 2a 20 61 72 65 20 74 68 65 0a 2a  puts** are the.*
36e50 2a 20 69 6e 70 75 74 73 20 74 6f 20 78 42 65 73  * inputs to xBes
36e60 74 49 6e 64 65 78 20 61 6e 64 20 61 72 65 20 72  tIndex and are r
36e70 65 61 64 2d 6f 6e 6c 79 2e 20 20 78 42 65 73 74  ead-only.  xBest
36e80 49 6e 64 65 78 20 69 6e 73 65 72 74 73 20 69 74  Index inserts it
36e90 73 0a 2a 2a 20 72 65 73 75 6c 74 73 20 69 6e 74  s.** results int
36ea0 6f 20 74 68 65 20 2a 2a 4f 75 74 70 75 74 73 2a  o the **Outputs*
36eb0 2a 20 66 69 65 6c 64 73 2e 0a 2a 2a 0a 2a 2a 20  * fields..**.** 
36ec0 5e 28 54 68 65 20 61 43 6f 6e 73 74 72 61 69 6e  ^(The aConstrain
36ed0 74 5b 5d 20 61 72 72 61 79 20 72 65 63 6f 72 64  t[] array record
36ee0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 63  s WHERE clause c
36ef0 6f 6e 73 74 72 61 69 6e 74 73 20 6f 66 20 74 68  onstraints of th
36f00 65 20 66 6f 72 6d 3a 0a 2a 2a 0a 2a 2a 20 3c 62  e form:.**.** <b
36f10 6c 6f 63 6b 71 75 6f 74 65 3e 63 6f 6c 75 6d 6e  lockquote>column
36f20 20 4f 50 20 65 78 70 72 3c 2f 62 6c 6f 63 6b 71   OP expr</blockq
36f30 75 6f 74 65 3e 0a 2a 2a 0a 2a 2a 20 77 68 65 72  uote>.**.** wher
36f40 65 20 4f 50 20 69 73 20 3d 2c 20 26 6c 74 3b 2c  e OP is =, &lt;,
36f50 20 26 6c 74 3b 3d 2c 20 26 67 74 3b 2c 20 6f 72   &lt;=, &gt;, or
36f60 20 26 67 74 3b 3d 2e 29 5e 20 20 5e 28 54 68 65   &gt;=.)^  ^(The
36f70 20 70 61 72 74 69 63 75 6c 61 72 20 6f 70 65 72   particular oper
36f80 61 74 6f 72 20 69 73 0a 2a 2a 20 73 74 6f 72 65  ator is.** store
36f90 64 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e 74  d in aConstraint
36fa0 5b 5d 2e 6f 70 20 75 73 69 6e 67 20 6f 6e 65 20  [].op using one 
36fb0 6f 66 20 74 68 65 0a 2a 2a 20 5b 53 51 4c 49 54  of the.** [SQLIT
36fc0 45 5f 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49  E_INDEX_CONSTRAI
36fd0 4e 54 5f 45 51 20 7c 20 53 51 4c 49 54 45 5f 49  NT_EQ | SQLITE_I
36fe0 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f  NDEX_CONSTRAINT_
36ff0 20 76 61 6c 75 65 73 5d 2e 29 5e 0a 2a 2a 20 5e   values].)^.** ^
37000 28 54 68 65 20 69 6e 64 65 78 20 6f 66 20 74 68  (The index of th
37010 65 20 63 6f 6c 75 6d 6e 20 69 73 20 73 74 6f 72  e column is stor
37020 65 64 20 69 6e 0a 2a 2a 20 61 43 6f 6e 73 74 72  ed in.** aConstr
37030 61 69 6e 74 5b 5d 2e 69 43 6f 6c 75 6d 6e 2e 29  aint[].iColumn.)
37040 5e 20 20 5e 28 61 43 6f 6e 73 74 72 61 69 6e 74  ^  ^(aConstraint
37050 5b 5d 2e 75 73 61 62 6c 65 20 69 73 20 54 52 55  [].usable is TRU
37060 45 20 69 66 20 74 68 65 0a 2a 2a 20 65 78 70 72  E if the.** expr
37070 20 6f 6e 20 74 68 65 20 72 69 67 68 74 2d 68 61   on the right-ha
37080 6e 64 20 73 69 64 65 20 63 61 6e 20 62 65 20 65  nd side can be e
37090 76 61 6c 75 61 74 65 64 20 28 61 6e 64 20 74 68  valuated (and th
370a0 75 73 20 74 68 65 20 63 6f 6e 73 74 72 61 69 6e  us the constrain
370b0 74 0a 2a 2a 20 69 73 20 75 73 61 62 6c 65 29 20  t.** is usable) 
370c0 61 6e 64 20 66 61 6c 73 65 20 69 66 20 69 74 20  and false if it 
370d0 63 61 6e 6e 6f 74 2e 29 5e 0a 2a 2a 0a 2a 2a 20  cannot.)^.**.** 
370e0 5e 54 68 65 20 6f 70 74 69 6d 69 7a 65 72 20 61  ^The optimizer a
370f0 75 74 6f 6d 61 74 69 63 61 6c 6c 79 20 69 6e 76  utomatically inv
37100 65 72 74 73 20 74 65 72 6d 73 20 6f 66 20 74 68  erts terms of th
37110 65 20 66 6f 72 6d 20 22 65 78 70 72 20 4f 50 20  e form "expr OP 
37120 63 6f 6c 75 6d 6e 22 0a 2a 2a 20 61 6e 64 20 6d  column".** and m
37130 61 6b 65 73 20 6f 74 68 65 72 20 73 69 6d 70 6c  akes other simpl
37140 69 66 69 63 61 74 69 6f 6e 73 20 74 6f 20 74 68  ifications to th
37150 65 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 69  e WHERE clause i
37160 6e 20 61 6e 20 61 74 74 65 6d 70 74 20 74 6f 0a  n an attempt to.
37170 2a 2a 20 67 65 74 20 61 73 20 6d 61 6e 79 20 57  ** get as many W
37180 48 45 52 45 20 63 6c 61 75 73 65 20 74 65 72 6d  HERE clause term
37190 73 20 69 6e 74 6f 20 74 68 65 20 66 6f 72 6d 20  s into the form 
371a0 73 68 6f 77 6e 20 61 62 6f 76 65 20 61 73 20 70  shown above as p
371b0 6f 73 73 69 62 6c 65 2e 0a 2a 2a 20 5e 54 68 65  ossible..** ^The
371c0 20 61 43 6f 6e 73 74 72 61 69 6e 74 5b 5d 20 61   aConstraint[] a
371d0 72 72 61 79 20 6f 6e 6c 79 20 72 65 70 6f 72 74  rray only report
371e0 73 20 57 48 45 52 45 20 63 6c 61 75 73 65 20 74  s WHERE clause t
371f0 65 72 6d 73 20 74 68 61 74 20 61 72 65 0a 2a 2a  erms that are.**
37200 20 72 65 6c 65 76 61 6e 74 20 74 6f 20 74 68 65   relevant to the
37210 20 70 61 72 74 69 63 75 6c 61 72 20 76 69 72 74   particular virt
37220 75 61 6c 20 74 61 62 6c 65 20 62 65 69 6e 67 20  ual table being 
37230 71 75 65 72 69 65 64 2e 0a 2a 2a 0a 2a 2a 20 5e  queried..**.** ^
37240 49 6e 66 6f 72 6d 61 74 69 6f 6e 20 61 62 6f 75  Information abou
37250 74 20 74 68 65 20 4f 52 44 45 52 20 42 59 20 63  t the ORDER BY c
37260 6c 61 75 73 65 20 69 73 20 73 74 6f 72 65 64 20  lause is stored 
37270 69 6e 20 61 4f 72 64 65 72 42 79 5b 5d 2e 0a 2a  in aOrderBy[]..*
37280 2a 20 5e 45 61 63 68 20 74 65 72 6d 20 6f 66 20  * ^Each term of 
37290 61 4f 72 64 65 72 42 79 20 72 65 63 6f 72 64 73  aOrderBy records
372a0 20 61 20 63 6f 6c 75 6d 6e 20 6f 66 20 74 68 65   a column of the
372b0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
372c0 2e 0a 2a 2a 0a 2a 2a 20 54 68 65 20 5b 78 42 65  ..**.** The [xBe
372d0 73 74 49 6e 64 65 78 5d 20 6d 65 74 68 6f 64 20  stIndex] method 
372e0 6d 75 73 74 20 66 69 6c 6c 20 61 43 6f 6e 73 74  must fill aConst
372f0 72 61 69 6e 74 55 73 61 67 65 5b 5d 20 77 69 74  raintUsage[] wit
37300 68 20 69 6e 66 6f 72 6d 61 74 69 6f 6e 0a 2a 2a  h information.**
37310 20 61 62 6f 75 74 20 77 68 61 74 20 70 61 72 61   about what para
37320 6d 65 74 65 72 73 20 74 6f 20 70 61 73 73 20 74  meters to pass t
37330 6f 20 78 46 69 6c 74 65 72 2e 20 20 5e 49 66 20  o xFilter.  ^If 
37340 61 72 67 76 49 6e 64 65 78 3e 30 20 74 68 65 6e  argvIndex>0 then
37350 0a 2a 2a 20 74 68 65 20 72 69 67 68 74 2d 68 61  .** the right-ha
37360 6e 64 20 73 69 64 65 20 6f 66 20 74 68 65 20 63  nd side of the c
37370 6f 72 72 65 73 70 6f 6e 64 69 6e 67 20 61 43 6f  orresponding aCo
37380 6e 73 74 72 61 69 6e 74 5b 5d 20 69 73 20 65 76  nstraint[] is ev
37390 61 6c 75 61 74 65 64 0a 2a 2a 20 61 6e 64 20 62  aluated.** and b
373a0 65 63 6f 6d 65 73 20 74 68 65 20 61 72 67 76 49  ecomes the argvI
373b0 6e 64 65 78 2d 74 68 20 65 6e 74 72 79 20 69 6e  ndex-th entry in
373c0 20 61 72 67 76 2e 20 20 5e 28 49 66 20 61 43 6f   argv.  ^(If aCo
373d0 6e 73 74 72 61 69 6e 74 55 73 61 67 65 5b 5d 2e  nstraintUsage[].
373e0 6f 6d 69 74 0a 2a 2a 20 69 73 20 74 72 75 65 2c  omit.** is true,
373f0 20 74 68 65 6e 20 74 68 65 20 63 6f 6e 73 74 72   then the constr
37400 61 69 6e 74 20 69 73 20 61 73 73 75 6d 65 64 20  aint is assumed 
37410 74 6f 20 62 65 20 66 75 6c 6c 79 20 68 61 6e 64  to be fully hand
37420 6c 65 64 20 62 79 20 74 68 65 0a 2a 2a 20 76 69  led by the.** vi
37430 72 74 75 61 6c 20 74 61 62 6c 65 20 61 6e 64 20  rtual table and 
37440 69 73 20 6e 6f 74 20 63 68 65 63 6b 65 64 20 61  is not checked a
37450 67 61 69 6e 20 62 79 20 53 51 4c 69 74 65 2e 29  gain by SQLite.)
37460 5e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 69 64 78  ^.**.** ^The idx
37470 4e 75 6d 20 61 6e 64 20 69 64 78 50 74 72 20 76  Num and idxPtr v
37480 61 6c 75 65 73 20 61 72 65 20 72 65 63 6f 72 64  alues are record
37490 65 64 20 61 6e 64 20 70 61 73 73 65 64 20 69 6e  ed and passed in
374a0 74 6f 20 74 68 65 0a 2a 2a 20 5b 78 46 69 6c 74  to the.** [xFilt
374b0 65 72 5d 20 6d 65 74 68 6f 64 2e 0a 2a 2a 20 5e  er] method..** ^
374c0 5b 73 71 6c 69 74 65 33 5f 66 72 65 65 28 29 5d  [sqlite3_free()]
374d0 20 69 73 20 75 73 65 64 20 74 6f 20 66 72 65 65   is used to free
374e0 20 69 64 78 50 74 72 20 69 66 20 61 6e 64 20 6f   idxPtr if and o
374f0 6e 6c 79 20 69 66 0a 2a 2a 20 6e 65 65 64 54 6f  nly if.** needTo
37500 46 72 65 65 49 64 78 50 74 72 20 69 73 20 74 72  FreeIdxPtr is tr
37510 75 65 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6f  ue..**.** ^The o
37520 72 64 65 72 42 79 43 6f 6e 73 75 6d 65 64 20 6d  rderByConsumed m
37530 65 61 6e 73 20 74 68 61 74 20 6f 75 74 70 75 74  eans that output
37540 20 66 72 6f 6d 20 5b 78 46 69 6c 74 65 72 5d 2f   from [xFilter]/
37550 5b 78 4e 65 78 74 5d 20 77 69 6c 6c 20 6f 63 63  [xNext] will occ
37560 75 72 20 69 6e 0a 2a 2a 20 74 68 65 20 63 6f 72  ur in.** the cor
37570 72 65 63 74 20 6f 72 64 65 72 20 74 6f 20 73 61  rect order to sa
37580 74 69 73 66 79 20 74 68 65 20 4f 52 44 45 52 20  tisfy the ORDER 
37590 42 59 20 63 6c 61 75 73 65 20 73 6f 20 74 68 61  BY clause so tha
375a0 74 20 6e 6f 20 73 65 70 61 72 61 74 65 0a 2a 2a  t no separate.**
375b0 20 73 6f 72 74 69 6e 67 20 73 74 65 70 20 69 73   sorting step is
375c0 20 72 65 71 75 69 72 65 64 2e 0a 2a 2a 0a 2a 2a   required..**.**
375d0 20 5e 54 68 65 20 65 73 74 69 6d 61 74 65 64 43   ^The estimatedC
375e0 6f 73 74 20 76 61 6c 75 65 20 69 73 20 61 6e 20  ost value is an 
375f0 65 73 74 69 6d 61 74 65 20 6f 66 20 74 68 65 20  estimate of the 
37600 63 6f 73 74 20 6f 66 20 64 6f 69 6e 67 20 74 68  cost of doing th
37610 65 0a 2a 2a 20 70 61 72 74 69 63 75 6c 61 72 20  e.** particular 
37620 6c 6f 6f 6b 75 70 2e 20 20 41 20 66 75 6c 6c 20  lookup.  A full 
37630 73 63 61 6e 20 6f 66 20 61 20 74 61 62 6c 65 20  scan of a table 
37640 77 69 74 68 20 4e 20 65 6e 74 72 69 65 73 20 73  with N entries s
37650 68 6f 75 6c 64 20 68 61 76 65 0a 2a 2a 20 61 20  hould have.** a 
37660 63 6f 73 74 20 6f 66 20 4e 2e 20 20 41 20 62 69  cost of N.  A bi
37670 6e 61 72 79 20 73 65 61 72 63 68 20 6f 66 20 61  nary search of a
37680 20 74 61 62 6c 65 20 6f 66 20 4e 20 65 6e 74 72   table of N entr
37690 69 65 73 20 73 68 6f 75 6c 64 20 68 61 76 65 20  ies should have 
376a0 61 0a 2a 2a 20 63 6f 73 74 20 6f 66 20 61 70 70  a.** cost of app
376b0 72 6f 78 69 6d 61 74 65 6c 79 20 6c 6f 67 28 4e  roximately log(N
376c0 29 2e 0a 2a 2f 0a 73 74 72 75 63 74 20 73 71 6c  )..*/.struct sql
376d0 69 74 65 33 5f 69 6e 64 65 78 5f 69 6e 66 6f 20  ite3_index_info 
376e0 7b 0a 20 20 2f 2a 20 49 6e 70 75 74 73 20 2a 2f  {.  /* Inputs */
376f0 0a 20 20 69 6e 74 20 6e 43 6f 6e 73 74 72 61 69  .  int nConstrai
37700 6e 74 3b 20 20 20 20 20 20 20 20 20 20 20 2f 2a  nt;           /*
37710 20 4e 75 6d 62 65 72 20 6f 66 20 65 6e 74 72 69   Number of entri
37720 65 73 20 69 6e 20 61 43 6f 6e 73 74 72 61 69 6e  es in aConstrain
37730 74 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71  t */.  struct sq
37740 6c 69 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73  lite3_index_cons
37750 74 72 61 69 6e 74 20 7b 0a 20 20 20 20 20 69 6e  traint {.     in
37760 74 20 69 43 6f 6c 75 6d 6e 3b 20 20 20 20 20 20  t iColumn;      
37770 20 20 20 20 20 20 20 20 2f 2a 20 43 6f 6c 75 6d          /* Colum
37780 6e 20 6f 6e 20 6c 65 66 74 2d 68 61 6e 64 20 73  n on left-hand s
37790 69 64 65 20 6f 66 20 63 6f 6e 73 74 72 61 69 6e  ide of constrain
377a0 74 20 2a 2f 0a 20 20 20 20 20 75 6e 73 69 67 6e  t */.     unsign
377b0 65 64 20 63 68 61 72 20 6f 70 3b 20 20 20 20 20  ed char op;     
377c0 20 20 20 20 2f 2a 20 43 6f 6e 73 74 72 61 69 6e      /* Constrain
377d0 74 20 6f 70 65 72 61 74 6f 72 20 2a 2f 0a 20 20  t operator */.  
377e0 20 20 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72     unsigned char
377f0 20 75 73 61 62 6c 65 3b 20 20 20 20 20 2f 2a 20   usable;     /* 
37800 54 72 75 65 20 69 66 20 74 68 69 73 20 63 6f 6e  True if this con
37810 73 74 72 61 69 6e 74 20 69 73 20 75 73 61 62 6c  straint is usabl
37820 65 20 2a 2f 0a 20 20 20 20 20 69 6e 74 20 69 54  e */.     int iT
37830 65 72 6d 4f 66 66 73 65 74 3b 20 20 20 20 20 20  ermOffset;      
37840 20 20 20 20 2f 2a 20 55 73 65 64 20 69 6e 74 65      /* Used inte
37850 72 6e 61 6c 6c 79 20 2d 20 78 42 65 73 74 49 6e  rnally - xBestIn
37860 64 65 78 20 73 68 6f 75 6c 64 20 69 67 6e 6f 72  dex should ignor
37870 65 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e 73 74  e */.  } *aConst
37880 72 61 69 6e 74 3b 20 20 20 20 20 20 20 20 20 20  raint;          
37890 20 20 2f 2a 20 54 61 62 6c 65 20 6f 66 20 57 48    /* Table of WH
378a0 45 52 45 20 63 6c 61 75 73 65 20 63 6f 6e 73 74  ERE clause const
378b0 72 61 69 6e 74 73 20 2a 2f 0a 20 20 69 6e 74 20  raints */.  int 
378c0 6e 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20 20  nOrderBy;       
378d0 20 20 20 20 20 20 20 2f 2a 20 4e 75 6d 62 65 72         /* Number
378e0 20 6f 66 20 74 65 72 6d 73 20 69 6e 20 74 68 65   of terms in the
378f0 20 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65   ORDER BY clause
37900 20 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c   */.  struct sql
37910 69 74 65 33 5f 69 6e 64 65 78 5f 6f 72 64 65 72  ite3_index_order
37920 62 79 20 7b 0a 20 20 20 20 20 69 6e 74 20 69 43  by {.     int iC
37930 6f 6c 75 6d 6e 3b 20 20 20 20 20 20 20 20 20 20  olumn;          
37940 20 20 20 20 2f 2a 20 43 6f 6c 75 6d 6e 20 6e 75      /* Column nu
37950 6d 62 65 72 20 2a 2f 0a 20 20 20 20 20 75 6e 73  mber */.     uns
37960 69 67 6e 65 64 20 63 68 61 72 20 64 65 73 63 3b  igned char desc;
37970 20 20 20 20 20 20 20 2f 2a 20 54 72 75 65 20 66         /* True f
37980 6f 72 20 44 45 53 43 2e 20 20 46 61 6c 73 65 20  or DESC.  False 
37990 66 6f 72 20 41 53 43 2e 20 2a 2f 0a 20 20 7d 20  for ASC. */.  } 
379a0 2a 61 4f 72 64 65 72 42 79 3b 20 20 20 20 20 20  *aOrderBy;      
379b0 20 20 20 20 20 20 20 20 20 2f 2a 20 54 68 65 20           /* The 
379c0 4f 52 44 45 52 20 42 59 20 63 6c 61 75 73 65 20  ORDER BY clause 
379d0 2a 2f 0a 20 20 2f 2a 20 4f 75 74 70 75 74 73 20  */.  /* Outputs 
379e0 2a 2f 0a 20 20 73 74 72 75 63 74 20 73 71 6c 69  */.  struct sqli
379f0 74 65 33 5f 69 6e 64 65 78 5f 63 6f 6e 73 74 72  te3_index_constr
37a00 61 69 6e 74 5f 75 73 61 67 65 20 7b 0a 20 20 20  aint_usage {.   
37a10 20 69 6e 74 20 61 72 67 76 49 6e 64 65 78 3b 20   int argvIndex; 
37a20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 69 66 20            /* if 
37a30 3e 30 2c 20 63 6f 6e 73 74 72 61 69 6e 74 20 69  >0, constraint i
37a40 73 20 70 61 72 74 20 6f 66 20 61 72 67 76 20 74  s part of argv t
37a50 6f 20 78 46 69 6c 74 65 72 20 2a 2f 0a 20 20 20  o xFilter */.   
37a60 20 75 6e 73 69 67 6e 65 64 20 63 68 61 72 20 6f   unsigned char o
37a70 6d 69 74 3b 20 20 20 20 20 20 2f 2a 20 44 6f 20  mit;      /* Do 
37a80 6e 6f 74 20 63 6f 64 65 20 61 20 74 65 73 74 20  not code a test 
37a90 66 6f 72 20 74 68 69 73 20 63 6f 6e 73 74 72 61  for this constra
37aa0 69 6e 74 20 2a 2f 0a 20 20 7d 20 2a 61 43 6f 6e  int */.  } *aCon
37ab0 73 74 72 61 69 6e 74 55 73 61 67 65 3b 0a 20 20  straintUsage;.  
37ac0 69 6e 74 20 69 64 78 4e 75 6d 3b 20 20 20 20 20  int idxNum;     
37ad0 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 4e 75             /* Nu
37ae0 6d 62 65 72 20 75 73 65 64 20 74 6f 20 69 64 65  mber used to ide
37af0 6e 74 69 66 79 20 74 68 65 20 69 6e 64 65 78 20  ntify the index 
37b00 2a 2f 0a 20 20 63 68 61 72 20 2a 69 64 78 53 74  */.  char *idxSt
37b10 72 3b 20 20 20 20 20 20 20 20 20 20 20 20 20 20  r;              
37b20 2f 2a 20 53 74 72 69 6e 67 2c 20 70 6f 73 73 69  /* String, possi
37b30 62 6c 79 20 6f 62 74 61 69 6e 65 64 20 66 72 6f  bly obtained fro
37b40 6d 20 73 71 6c 69 74 65 33 5f 6d 61 6c 6c 6f 63  m sqlite3_malloc
37b50 20 2a 2f 0a 20 20 69 6e 74 20 6e 65 65 64 54 6f   */.  int needTo
37b60 46 72 65 65 49 64 78 53 74 72 3b 20 20 20 20 20  FreeIdxStr;     
37b70 20 2f 2a 20 46 72 65 65 20 69 64 78 53 74 72 20   /* Free idxStr 
37b80 75 73 69 6e 67 20 73 71 6c 69 74 65 33 5f 66 72  using sqlite3_fr
37b90 65 65 28 29 20 69 66 20 74 72 75 65 20 2a 2f 0a  ee() if true */.
37ba0 20 20 69 6e 74 20 6f 72 64 65 72 42 79 43 6f 6e    int orderByCon
37bb0 73 75 6d 65 64 3b 20 20 20 20 20 20 20 2f 2a 20  sumed;       /* 
37bc0 54 72 75 65 20 69 66 20 6f 75 74 70 75 74 20 69  True if output i
37bd0 73 20 61 6c 72 65 61 64 79 20 6f 72 64 65 72 65  s already ordere
37be0 64 20 2a 2f 0a 20 20 64 6f 75 62 6c 65 20 65 73  d */.  double es
37bf0 74 69 6d 61 74 65 64 43 6f 73 74 3b 20 20 20 20  timatedCost;    
37c00 20 20 2f 2a 20 45 73 74 69 6d 61 74 65 64 20 63    /* Estimated c
37c10 6f 73 74 20 6f 66 20 75 73 69 6e 67 20 74 68 69  ost of using thi
37c20 73 20 69 6e 64 65 78 20 2a 2f 0a 7d 3b 0a 0a 2f  s index */.};../
37c30 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a 20 56  *.** CAPI3REF: V
37c40 69 72 74 75 61 6c 20 54 61 62 6c 65 20 43 6f 6e  irtual Table Con
37c50 73 74 72 61 69 6e 74 20 4f 70 65 72 61 74 6f 72  straint Operator
37c60 20 43 6f 64 65 73 0a 2a 2a 0a 2a 2a 20 54 68 65   Codes.**.** The
37c70 73 65 20 6d 61 63 72 6f 73 20 64 65 66 69 6e 65  se macros define
37c80 64 20 74 68 65 20 61 6c 6c 6f 77 65 64 20 76 61  d the allowed va
37c90 6c 75 65 73 20 66 6f 72 20 74 68 65 0a 2a 2a 20  lues for the.** 
37ca0 5b 73 71 6c 69 74 65 33 5f 69 6e 64 65 78 5f 69  [sqlite3_index_i
37cb0 6e 66 6f 5d 2e 61 43 6f 6e 73 74 72 61 69 6e 74  nfo].aConstraint
37cc0 5b 5d 2e 6f 70 20 66 69 65 6c 64 2e 20 20 45 61  [].op field.  Ea
37cd0 63 68 20 76 61 6c 75 65 20 72 65 70 72 65 73 65  ch value represe
37ce0 6e 74 73 0a 2a 2a 20 61 6e 20 6f 70 65 72 61 74  nts.** an operat
37cf0 6f 72 20 74 68 61 74 20 69 73 20 70 61 72 74 20  or that is part 
37d00 6f 66 20 61 20 63 6f 6e 73 74 72 61 69 6e 74 20  of a constraint 
37d10 74 65 72 6d 20 69 6e 20 74 68 65 20 77 48 45 52  term in the wHER
37d20 45 20 63 6c 61 75 73 65 20 6f 66 0a 2a 2a 20 61  E clause of.** a
37d30 20 71 75 65 72 79 20 74 68 61 74 20 75 73 65 73   query that uses
37d40 20 61 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c   a [virtual tabl
37d50 65 5d 2e 0a 2a 2f 0a 23 64 65 66 69 6e 65 20 53  e]..*/.#define S
37d60 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
37d70 54 52 41 49 4e 54 5f 45 51 20 20 20 20 32 0a 23  TRAINT_EQ    2.#
37d80 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
37d90 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 47  DEX_CONSTRAINT_G
37da0 54 20 20 20 20 34 0a 23 64 65 66 69 6e 65 20 53  T    4.#define S
37db0 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e 53  QLITE_INDEX_CONS
37dc0 54 52 41 49 4e 54 5f 4c 45 20 20 20 20 38 0a 23  TRAINT_LE    8.#
37dd0 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f 49 4e  define SQLITE_IN
37de0 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54 5f 4c  DEX_CONSTRAINT_L
37df0 54 20 20 20 20 31 36 0a 23 64 65 66 69 6e 65 20  T    16.#define 
37e00 53 51 4c 49 54 45 5f 49 4e 44 45 58 5f 43 4f 4e  SQLITE_INDEX_CON
37e10 53 54 52 41 49 4e 54 5f 47 45 20 20 20 20 33 32  STRAINT_GE    32
37e20 0a 23 64 65 66 69 6e 65 20 53 51 4c 49 54 45 5f  .#define SQLITE_
37e30 49 4e 44 45 58 5f 43 4f 4e 53 54 52 41 49 4e 54  INDEX_CONSTRAINT
37e40 5f 4d 41 54 43 48 20 36 34 0a 0a 2f 2a 0a 2a 2a  _MATCH 64../*.**
37e50 20 43 41 50 49 33 52 45 46 3a 20 52 65 67 69 73   CAPI3REF: Regis
37e60 74 65 72 20 41 20 56 69 72 74 75 61 6c 20 54 61  ter A Virtual Ta
37e70 62 6c 65 20 49 6d 70 6c 65 6d 65 6e 74 61 74 69  ble Implementati
37e80 6f 6e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 73 65 20  on.**.** ^These 
37e90 72 6f 75 74 69 6e 65 73 20 61 72 65 20 75 73 65  routines are use
37ea0 64 20 74 6f 20 72 65 67 69 73 74 65 72 20 61 20  d to register a 
37eb0 6e 65 77 20 5b 76 69 72 74 75 61 6c 20 74 61 62  new [virtual tab
37ec0 6c 65 20 6d 6f 64 75 6c 65 5d 20 6e 61 6d 65 2e  le module] name.
37ed0 0a 2a 2a 20 5e 4d 6f 64 75 6c 65 20 6e 61 6d 65  .** ^Module name
37ee0 73 20 6d 75 73 74 20 62 65 20 72 65 67 69 73 74  s must be regist
37ef0 65 72 65 64 20 62 65 66 6f 72 65 0a 2a 2a 20 63  ered before.** c
37f00 72 65 61 74 69 6e 67 20 61 20 6e 65 77 20 5b 76  reating a new [v
37f10 69 72 74 75 61 6c 20 74 61 62 6c 65 5d 20 75 73  irtual table] us
37f20 69 6e 67 20 74 68 65 20 6d 6f 64 75 6c 65 20 61  ing the module a
37f30 6e 64 20 62 65 66 6f 72 65 20 75 73 69 6e 67 20  nd before using 
37f40 61 0a 2a 2a 20 70 72 65 65 78 69 73 74 69 6e 67  a.** preexisting
37f50 20 5b 76 69 72 74 75 61 6c 20 74 61 62 6c 65 5d   [virtual table]
37f60 20 66 6f 72 20 74 68 65 20 6d 6f 64 75 6c 65 2e   for the module.
37f70 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 6d 6f 64 75  .**.** ^The modu
37f80 6c 65 20 6e 61 6d 65 20 69 73 20 72 65 67 69 73  le name is regis
37f90 74 65 72 65 64 20 6f 6e 20 74 68 65 20 5b 64 61  tered on the [da
37fa0 74 61 62 61 73 65 20 63 6f 6e 6e 65 63 74 69 6f  tabase connectio
37fb0 6e 5d 20 73 70 65 63 69 66 69 65 64 0a 2a 2a 20  n] specified.** 
37fc0 62 79 20 74 68 65 20 66 69 72 73 74 20 70 61 72  by the first par
37fd0 61 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 6e 61  ameter.  ^The na
37fe0 6d 65 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  me of the module
37ff0 20 69 73 20 67 69 76 65 6e 20 62 79 20 74 68 65   is given by the
38000 20 0a 2a 2a 20 73 65 63 6f 6e 64 20 70 61 72 61   .** second para
38010 6d 65 74 65 72 2e 20 20 5e 54 68 65 20 74 68 69  meter.  ^The thi
38020 72 64 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  rd parameter is 
38030 61 20 70 6f 69 6e 74 65 72 20 74 6f 0a 2a 2a 20  a pointer to.** 
38040 74 68 65 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69  the implementati
38050 6f 6e 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75  on of the [virtu
38060 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65 5d  al table module]
38070 2e 20 20 20 5e 54 68 65 20 66 6f 75 72 74 68 0a  .   ^The fourth.
38080 2a 2a 20 70 61 72 61 6d 65 74 65 72 20 69 73 20  ** parameter is 
38090 61 6e 20 61 72 62 69 74 72 61 72 79 20 63 6c 69  an arbitrary cli
380a0 65 6e 74 20 64 61 74 61 20 70 6f 69 6e 74 65 72  ent data pointer
380b0 20 74 68 61 74 20 69 73 20 70 61 73 73 65 64 20   that is passed 
380c0 74 68 72 6f 75 67 68 0a 2a 2a 20 69 6e 74 6f 20  through.** into 
380d0 74 68 65 20 5b 78 43 72 65 61 74 65 5d 20 61 6e  the [xCreate] an
380e0 64 20 5b 78 43 6f 6e 6e 65 63 74 5d 20 6d 65 74  d [xConnect] met
380f0 68 6f 64 73 20 6f 66 20 74 68 65 20 76 69 72 74  hods of the virt
38100 75 61 6c 20 74 61 62 6c 65 20 6d 6f 64 75 6c 65  ual table module
38110 0a 2a 2a 20 77 68 65 6e 20 61 20 6e 65 77 20 76  .** when a new v
38120 69 72 74 75 61 6c 20 74 61 62 6c 65 20 69 73 20  irtual table is 
38130 62 65 20 62 65 69 6e 67 20 63 72 65 61 74 65 64  be being created
38140 20 6f 72 20 72 65 69 6e 69 74 69 61 6c 69 7a 65   or reinitialize
38150 64 2e 0a 2a 2a 0a 2a 2a 20 5e 54 68 65 20 73 71  d..**.** ^The sq
38160 6c 69 74 65 33 5f 63 72 65 61 74 65 5f 6d 6f 64  lite3_create_mod
38170 75 6c 65 5f 76 32 28 29 20 69 6e 74 65 72 66 61  ule_v2() interfa
38180 63 65 20 68 61 73 20 61 20 66 69 66 74 68 20 70  ce has a fifth p
38190 61 72 61 6d 65 74 65 72 20 77 68 69 63 68 0a 2a  arameter which.*
381a0 2a 20 69 73 20 61 20 70 6f 69 6e 74 65 72 20 74  * is a pointer t
381b0 6f 20 61 20 64 65 73 74 72 75 63 74 6f 72 20 66  o a destructor f
381c0 6f 72 20 74 68 65 20 70 43 6c 69 65 6e 74 44 61  or the pClientDa
381d0 74 61 2e 20 20 5e 53 51 4c 69 74 65 20 77 69 6c  ta.  ^SQLite wil
381e0 6c 0a 2a 2a 20 69 6e 76 6f 6b 65 20 74 68 65 20  l.** invoke the 
381f0 64 65 73 74 72 75 63 74 6f 72 20 66 75 6e 63 74  destructor funct
38200 69 6f 6e 20 28 69 66 20 69 74 20 69 73 20 6e 6f  ion (if it is no
38210 74 20 4e 55 4c 4c 29 20 77 68 65 6e 20 53 51 4c  t NULL) when SQL
38220 69 74 65 0a 2a 2a 20 6e 6f 20 6c 6f 6e 67 65 72  ite.** no longer
38230 20 6e 65 65 64 73 20 74 68 65 20 70 43 6c 69 65   needs the pClie
38240 6e 74 44 61 74 61 20 70 6f 69 6e 74 65 72 2e 20  ntData pointer. 
38250 20 5e 54 68 65 20 64 65 73 74 72 75 63 74 6f 72   ^The destructor
38260 20 77 69 6c 6c 20 61 6c 73 6f 0a 2a 2a 20 62 65   will also.** be
38270 20 69 6e 76 6f 6b 65 64 20 69 66 20 74 68 65 20   invoked if the 
38280 63 61 6c 6c 20 74 6f 20 73 71 6c 69 74 65 33 5f  call to sqlite3_
38290 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
382a0 28 29 20 66 61 69 6c 73 2e 0a 2a 2a 20 5e 54 68  () fails..** ^Th
382b0 65 20 73 71 6c 69 74 65 33 5f 63 72 65 61 74 65  e sqlite3_create
382c0 5f 6d 6f 64 75 6c 65 28 29 0a 2a 2a 20 69 6e 74  _module().** int
382d0 65 72 66 61 63 65 20 69 73 20 65 71 75 69 76 61  erface is equiva
382e0 6c 65 6e 74 20 74 6f 20 73 71 6c 69 74 65 33 5f  lent to sqlite3_
382f0 63 72 65 61 74 65 5f 6d 6f 64 75 6c 65 5f 76 32  create_module_v2
38300 28 29 20 77 69 74 68 20 61 20 4e 55 4c 4c 0a 2a  () with a NULL.*
38310 2a 20 64 65 73 74 72 75 63 74 6f 72 2e 0a 2a 2f  * destructor..*/
38320 0a 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65  .int sqlite3_cre
38330 61 74 65 5f 6d 6f 64 75 6c 65 28 0a 20 20 73 71  ate_module(.  sq
38340 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20 20 20  lite3 *db,      
38350 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51 4c 69           /* SQLi
38360 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20 74 6f  te connection to
38370 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75 6c 65   register module
38380 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e 73 74   with */.  const
38390 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20 20 20   char *zName,   
383a0 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20 6f 66        /* Name of
383b0 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20   the module */. 
383c0 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33 5f 6d   const sqlite3_m
383d0 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a 20 4d  odule *p,   /* M
383e0 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65 20 6d  ethods for the m
383f0 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69 64 20  odule */.  void 
38400 2a 70 43 6c 69 65 6e 74 44 61 74 61 20 20 20 20  *pClientData    
38410 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e 74 20        /* Client 
38420 64 61 74 61 20 66 6f 72 20 78 43 72 65 61 74 65  data for xCreate
38430 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 29 3b 0a  /xConnect */.);.
38440 69 6e 74 20 73 71 6c 69 74 65 33 5f 63 72 65 61  int sqlite3_crea
38450 74 65 5f 6d 6f 64 75 6c 65 5f 76 32 28 0a 20 20  te_module_v2(.  
38460 73 71 6c 69 74 65 33 20 2a 64 62 2c 20 20 20 20  sqlite3 *db,    
38470 20 20 20 20 20 20 20 20 20 20 20 2f 2a 20 53 51             /* SQ
38480 4c 69 74 65 20 63 6f 6e 6e 65 63 74 69 6f 6e 20  Lite connection 
38490 74 6f 20 72 65 67 69 73 74 65 72 20 6d 6f 64 75  to register modu
384a0 6c 65 20 77 69 74 68 20 2a 2f 0a 20 20 63 6f 6e  le with */.  con
384b0 73 74 20 63 68 61 72 20 2a 7a 4e 61 6d 65 2c 20  st char *zName, 
384c0 20 20 20 20 20 20 20 20 2f 2a 20 4e 61 6d 65 20          /* Name 
384d0 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65 20 2a 2f  of the module */
384e0 0a 20 20 63 6f 6e 73 74 20 73 71 6c 69 74 65 33  .  const sqlite3
384f0 5f 6d 6f 64 75 6c 65 20 2a 70 2c 20 20 20 2f 2a  _module *p,   /*
38500 20 4d 65 74 68 6f 64 73 20 66 6f 72 20 74 68 65   Methods for the
38510 20 6d 6f 64 75 6c 65 20 2a 2f 0a 20 20 76 6f 69   module */.  voi
38520 64 20 2a 70 43 6c 69 65 6e 74 44 61 74 61 2c 20  d *pClientData, 
38530 20 20 20 20 20 20 20 20 2f 2a 20 43 6c 69 65 6e          /* Clien
38540 74 20 64 61 74 61 20 66 6f 72 20 78 43 72 65 61  t data for xCrea
38550 74 65 2f 78 43 6f 6e 6e 65 63 74 20 2a 2f 0a 20  te/xConnect */. 
38560 20 76 6f 69 64 28 2a 78 44 65 73 74 72 6f 79 29   void(*xDestroy)
38570 28 76 6f 69 64 2a 29 20 20 20 20 20 2f 2a 20 4d  (void*)     /* M
38580 6f 64 75 6c 65 20 64 65 73 74 72 75 63 74 6f 72  odule destructor
38590 20 66 75 6e 63 74 69 6f 6e 20 2a 2f 0a 29 3b 0a   function */.);.
385a0 0a 2f 2a 0a 2a 2a 20 43 41 50 49 33 52 45 46 3a  ./*.** CAPI3REF:
385b0 20 56 69 72 74 75 61 6c 20 54 61 62 6c 65 20 49   Virtual Table I
385c0 6e 73 74 61 6e 63 65 20 4f 62 6a 65 63 74 0a 2a  nstance Object.*
385d0 2a 20 4b 45 59 57 4f 52 44 53 3a 20 73 71 6c 69  * KEYWORDS: sqli
385e0 74 65 33 5f 76 74 61 62 0a 2a 2a 0a 2a 2a 20 45  te3_vtab.**.** E
385f0 76 65 72 79 20 5b 76 69 72 74 75 61 6c 20 74 61  very [virtual ta
38600 62 6c 65 20 6d 6f 64 75 6c 65 5d 20 69 6d 70 6c  ble module] impl
38610 65 6d 65 6e 74 61 74 69 6f 6e 20 75 73 65 73 20  ementation uses 
38620 61 20 73 75 62 63 6c 61 73 73 0a 2a 2a 20 6f 66  a subclass.** of
38630 20 74 68 69 73 20 6f 62 6a 65 63 74 20 74 6f 20   this object to 
38640 64 65 73 63 72 69 62 65 20 61 20 70 61 72 74 69  describe a parti
38650 63 75 6c 61 72 20 69 6e 73 74 61 6e 63 65 0a 2a  cular instance.*
38660 2a 20 6f 66 20 74 68 65 20 5b 76 69 72 74 75 61  * of the [virtua
38670 6c 20 74 61 62 6c 65 5d 2e 20 20 45 61 63 68 20  l table].  Each 
38680 73 75 62 63 6c 61 73 73 20 77 69 6c 6c 0a 2a 2a  subclass will.**
38690 20 62 65 20 74 61 69 6c 6f 72 65 64 20 74 6f 20   be tailored to 
386a0 74 68 65 20 73 70 65 63 69 66 69 63 20 6e 65 65  the specific nee
386b0 64 73 20 6f 66 20 74 68 65 20 6d 6f 64 75 6c 65  ds of the module
386c0 20 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 2e   implementation.
386d0 0a 2a 2a 20 54 68 65 20 70 75 72 70 6f 73 65 20  .** The purpose 
386e0 6f 66 20 74 68 69 73 20 73 75 70 65 72 63 6c 61  of this supercla
386f0 73 73 20 69 73 20 74 6f 20 64 65 66 69 6e 65 20  ss is to define 
38700 63 65 72 74 61 69 6e 20 66 69 65 6c 64 73 20 74  certain fields t
38710 68 61 74 20 61 72 65 0a 2a 2a 20 63 6f 6d 6d 6f  hat are.** commo
38720 6e 20 74 6f 20 61 6c 6c 20 6d 6f 64 75 6c 65 20  n to all module 
38730 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 73 2e  implementations.
38740 0a 2a 2a 0a 2a 2a 20 5e 56 69 72 74 75 61 6c 20  .**.** ^Virtual 
38750 74 61 62 6c 65 73 20 6d 65 74 68 6f 64 73 20 63  tables methods c
38760 61 6e 20 73 65 74 20 61 6e 20 65 72 72 6f 72 20  an set an error 
38770 6d 65 73 73 61 67 65 20 62 79 20 61 73 73 69 67  message by assig
38780 6e 69 6e 67 20 61 0a 2a 2a 20 73 74 72 69 6e 67  ning a.** string
38790 20 6f 62 74 61 69 6e 65 64 20 66 72 6f 6d 20 5b   obtained from [
387a0 73 71 6c 69 74 65 33 5f 6d 70 72 69 6e 74 66 28  sqlite3_mprintf(
387b0 29 5d 20 74 6f 20 7a 45 72 72 4d 73 67 2e 20 20  )] to zErrMsg.  
387c0 54 68 65 20 6d 65 74 68 6f 64 20 73 68 6f 75 6c  The method shoul
387d0 64 0a 2a 2a 20 74 61 6b 65 20 63 61 72 65 20 74  d.** take care t
387e0 68 61 74 20 61 6e 79 20 70 72 69 6f 72 20 73 74  hat any prior st
387f0 72 69 6e 67 20 69 73 20 66 72 65 65 64 20 62 79  ring is freed by
38800 20 61 20 63 61 6c 6c 20 74 6f 20 5b 73 71 6c 69   a call to [sqli
38810 74 65 33 5f 66 72 65 65 28 29 5d 0a 2a 2a 20 70  te3_free()].** p
38820 72 69 6f 72 20 74 6f 20 61 73 73 69 67 6e 69 6e  rior to assignin
38830 67 20 61 20 6e 65 77 20 73 74 72 69 6e 67 20 74  g a new string t
38840 6f 20 7a 45 72 72 4d 73 67 2e 20 20 5e 41 66 74  o zErrMsg.  ^Aft
38850 65 72 20 74 68 65 20 65 72 72 6f 72 20 6d 65 73  er the error mes
38860 73 61 67 65 0a 2a 2a 20 69 73 20 64 65 6c 69 76  sage.** is deliv
38870 65 72 6